feat(upstreams): track saved reset first-seen metadata

Store sanitized available_expirations rows with pooler-owned first_seen_at while preserving legacy available_expires_at metadata.

Backfill existing legacy expiration arrays with migration-run timestamps, surface first-seen values in admin list and cockpit views, and document the compatibility/privacy contract.

Verification covered focused saved-reset/admin suites, browser QA, mix precommit, mix quality, and global review/debugging gates. Routing and redemption policy behavior are unchanged.

Author: masterkain

docs-site/src/content/docs/operators/upstreams.mdx

@@ -102,7 +102,9 @@ Manual redemption is enabled only when the upstream is not deleted or disabled,
 
 Auto redemption is a per-upstream opt-in policy available from the account-card `Saved resets` dialog and the upstream cockpit. New accounts default to auto redemption off. Operators choose whether automatic redemption waits until weekly quota is blocked or may start earlier when fresh weekly quota evidence shows every eligible candidate account is near the configured `Near-limit threshold`. The blocked mode is still allowed to rescue a saved reset with a known expiration inside the next 24 hours when that same account already has weekly usage to recover and the natural weekly reset is not close. The `Natural reset buffer` prevents spending when the weekly quota will reset naturally soon, and `Keep credits` reserves banked resets from automatic use.
 
-Saved reset observations and redemption attempts stay metadata-only on `upstream_identities.metadata` under `saved_resets` and `saved_reset_redemption`. The saved-reset observation may include sanitized aggregate expiration fields such as `available_expires_at`, `next_expires_at`, `expires_observed_at`, and `expires_refresh_attempted_at`; it must not include raw provider credit objects, identifiers, titles, descriptions, or redemption request ids. Policy fields live on the upstream identity as `saved_reset_auto_redeem_enabled`, `saved_reset_auto_redeem_trigger_mode`, `saved_reset_auto_redeem_quota_threshold_percent`, `saved_reset_auto_redeem_min_blocked_minutes`, and `saved_reset_auto_redeem_keep_credits`. Do not copy provider payloads, raw credit objects or identifiers, redemption request identifiers, token material, or account secrets into metadata, logs, docs, or tests.
+Saved reset observations and redemption attempts stay metadata-only on `upstream_identities.metadata` under `saved_resets` and `saved_reset_redemption`. The saved-reset observation may include sanitized expiration rows in `available_expirations`, where each row has an `expires_at` timestamp and a pooler-owned `first_seen_at` timestamp. Legacy `available_expires_at` stays available for compatibility, and `next_expires_at`, `expires_observed_at`, and `expires_refresh_attempted_at` remain sanitized aggregate fields. Historical rows are backfilled with the migration time as `first_seen_at`; future observations preserve `first_seen_at` only while the same expiration remains present, and disappeared expirations are not retained. Missing or invalid provider expiration fields are not guessed.
+
+Policy fields live on the upstream identity as `saved_reset_auto_redeem_enabled`, `saved_reset_auto_redeem_trigger_mode`, `saved_reset_auto_redeem_quota_threshold_percent`, `saved_reset_auto_redeem_min_blocked_minutes`, and `saved_reset_auto_redeem_keep_credits`. Do not copy provider payloads, raw provider credit objects, raw credit identifiers, titles, descriptions, request ids, redemption request identifiers, token material, secrets, or account credentials into metadata, logs, docs, or tests.
 
 ## Readiness States
 

lib/codex_pooler/upstreams/reconciliation/pool_reconciliation.ex

@@ -244,7 +244,10 @@ defmodule CodexPooler.Upstreams.Reconciliation.PoolReconciliation do
       metadata:
         identity.metadata
         |> Kernel.||(%{})
-        |> Map.put("saved_resets", SavedResets.usage_snapshot(payload, observed_at, usage_url)),
+        |> Map.put(
+          "saved_resets",
+          SavedResets.usage_snapshot(payload, observed_at, usage_url, identity)
+        ),
       updated_at: observed_at
     })
     |> Repo.update!()

lib/codex_pooler/upstreams/saved_reset_redemption.ex

@@ -552,23 +552,51 @@ defmodule CodexPooler.Upstreams.SavedResetRedemption do
   defp update_saved_reset_count!(identity, snapshot, available_count, observed_at) do
     metadata = identity.metadata || %{}
 
+    saved_reset_metadata =
+      %{
+        "status" => "reported",
+        "available_count" => available_count,
+        "source" => "codex_reset_credits_api",
+        "path_style" => snapshot.path_style,
+        "observed_at" => DateTime.to_iso8601(observed_at),
+        "usage_path" => snapshot.usage_path,
+        "reason" => nil
+      }
+      |> Map.merge(expiration_metadata_from_snapshot(snapshot))
+
     identity
     |> UpstreamIdentity.changeset(%{
-      metadata:
-        Map.put(metadata, "saved_resets", %{
-          "status" => "reported",
-          "available_count" => available_count,
-          "source" => "codex_reset_credits_api",
-          "path_style" => snapshot.path_style,
-          "observed_at" => DateTime.to_iso8601(observed_at),
-          "usage_path" => snapshot.usage_path,
-          "reason" => nil
-        }),
+      metadata: Map.put(metadata, "saved_resets", saved_reset_metadata),
       updated_at: observed_at
     })
     |> Repo.update!()
   end
 
+  @spec expiration_metadata_from_snapshot(SavedResets.snapshot_projection()) :: map()
+  defp expiration_metadata_from_snapshot(snapshot) do
+    %{
+      "available_expires_at" => snapshot.available_expires_at,
+      "available_expirations" => stored_available_expiration_rows(snapshot.available_expirations),
+      "next_expires_at" => snapshot.next_expires_at,
+      "expires_observed_at" => snapshot.expires_observed_at,
+      "expires_refresh_attempted_at" => snapshot.expires_refresh_attempted_at
+    }
+  end
+
+  @spec stored_available_expiration_rows([SavedResets.available_expiration_row()]) :: [map()]
+  defp stored_available_expiration_rows(rows) when is_list(rows) do
+    rows
+    |> Enum.map(fn
+      %{expires_at: expires_at, first_seen_at: first_seen_at}
+      when is_binary(expires_at) and is_binary(first_seen_at) ->
+        %{"expires_at" => expires_at, "first_seen_at" => first_seen_at}
+
+      _row ->
+        nil
+    end)
+    |> Enum.reject(&is_nil/1)
+  end
+
   defp mark_stale_redemption_failed!(identity, redemption, finished_at) do
     metadata = identity.metadata || %{}
     generation = next_generation(metadata)