feat(releases): sortable inbox columns and split observed/released dates

crates/codex-api/src/routes/v1/dto/release.rs

@@ -91,7 +91,11 @@ pub struct ReleaseLedgerEntryDto {
     /// Source-specific extras (free-form).
     #[serde(skip_serializing_if = "Option::is_none")]
     pub metadata: Option<serde_json::Value>,
+    /// When Codex detected this release.
     pub observed_at: DateTime<Utc>,
+    /// Upstream publish date from the source feed. `null` when unavailable.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub released_at: Option<DateTime<Utc>>,
     pub created_at: DateTime<Utc>,
 }
 
@@ -119,6 +123,7 @@ impl ReleaseLedgerEntryDto {
             state: m.state,
             metadata: m.metadata,
             observed_at: m.observed_at,
+            released_at: m.released_at,
             created_at: m.created_at,
         }
     }

crates/codex-api/src/routes/v1/handlers/releases.rs

@@ -42,7 +42,7 @@ use crate::{
 };
 use codex_db::entities::release_ledger::state as ledger_state;
 use codex_db::repositories::{
-    LedgerInboxFilter, LibraryRepository, PluginsRepository, ReleaseLedgerRepository,
+    InboxSort, LedgerInboxFilter, LibraryRepository, PluginsRepository, ReleaseLedgerRepository,
     ReleaseSourceRepository, ReleaseSourceUpdate, SeriesRepository,
 };
 use codex_events::{EntityChangeEvent, EntityEvent};
@@ -227,6 +227,11 @@ pub struct ReleaseInboxParams {
     /// Restrict to series belonging to this library.
     #[serde(default)]
     pub library_id: Option<Uuid>,
+    /// Sort order as `"field,direction"`. Supported fields: `series`
+    /// (default), `observed`, `released`. Directions: `asc` (default),
+    /// `desc`. Unknown values fall back to `series,asc`.
+    #[serde(default)]
+    pub sort: Option<String>,
     #[serde(default = "default_page")]
     pub page: u64,
     #[serde(default = "default_page_size")]
@@ -281,9 +286,20 @@ pub async fn list_release_inbox(
         language: params.language.clone(),
         library_id: params.library_id,
     };
-    let rows = ReleaseLedgerRepository::list_inbox(&state.db, filter.clone(), page_size, offset)
-        .await
-        .map_err(|e| ApiError::Internal(format!("Failed to list inbox: {}", e)))?;
+    let sort = params
+        .sort
+        .as_deref()
+        .map(InboxSort::parse)
+        .unwrap_or_default();
+    let rows = ReleaseLedgerRepository::list_inbox_sorted(
+        &state.db,
+        filter.clone(),
+        sort,
+        page_size,
+        offset,
+    )
+    .await
+    .map_err(|e| ApiError::Internal(format!("Failed to list inbox: {}", e)))?;
     let total = ReleaseLedgerRepository::count_inbox(&state.db, filter)
         .await
         .map_err(|e| ApiError::Internal(format!("Failed to count inbox: {}", e)))?;
@@ -310,6 +326,9 @@ pub async fn list_release_inbox(
     if let Some(lib) = params.library_id {
         builder = builder.with_param("libraryId", &lib.to_string());
     }
+    if let Some(ref s) = params.sort {
+        builder = builder.with_param("sort", s);
+    }
     let response = PaginatedResponse::with_builder(dtos, page, page_size, total, &builder);
     Ok(paginated_response(response, &builder))
 }

crates/codex-db/src/entities/release_ledger.rs

@@ -53,7 +53,11 @@ pub struct Model {
     /// `announced` | `dismissed` | `marked_acquired` | `ignored` | `hidden`.
     pub state: String,
     pub metadata: Option<serde_json::Value>,
+    /// When Codex detected this release (plugin-set, defaults to record time).
     pub observed_at: DateTime<Utc>,
+    /// Upstream publish date (from the source feed). `None` when the feed
+    /// carried no usable date or the emitting plugin predates this field.
+    pub released_at: Option<DateTime<Utc>>,
     pub created_at: DateTime<Utc>,
 }
 

crates/codex-db/src/repositories/mod.rs

@@ -81,7 +81,7 @@ pub use read_progress::ReadProgressRepository;
 pub use refresh_token::{NewRefreshToken, RefreshTokenRepository};
 #[allow(unused_imports)]
 pub use release_ledger::{
-    LedgerInboxFilter, NewReleaseEntry, RecordOutcome, ReleaseLedgerRepository,
+    InboxSort, LedgerInboxFilter, NewReleaseEntry, RecordOutcome, ReleaseLedgerRepository,
 };
 #[allow(unused_imports)]
 pub use release_sources::{NewReleaseSource, ReleaseSourceRepository, ReleaseSourceUpdate};