feat(keys): keep a key's attribution after its row is purged; v2.31.0

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.31.0] — 2026-10-15
+
+### Added
+
+- A purged or deleted key keeps its attribution (#224). Migration `0036_key_tombstones` adds `api_key_tombstones` (`id, name, prefix, owner, owner_kind, tool, purged_at`; no value or ciphertext column). The janitor's revoked-key purge deletes the key and writes its tombstone in one statement, and `DELETE /api/admin/keys/:id` does the same in one statement, both stamped from the injected clock. The usage label loader names a key by its live row, else its tombstone, so `byKey` and the recent-attempts key subject keep the name (and the loader carries owner, owner kind and tool) instead of showing "deleted". The janitor sweeps tombstones at `RETENTION_USAGE_DAILY_DAYS` plus one day, since rollups age by whole UTC day and the tombstone must outlive the rollups it labels. Verification, reveal and the admin key list never read tombstones; the `GET /api/admin/usage` wire shape is unchanged. Keys purged before this release have no tombstone and stay "deleted"; there is no backfill.
+
 ## [2.30.1] — 2026-10-15
 
 ### Documentation
@@ -1245,3 +1251,4 @@ your tooling config.
 [2.29.0]: https://github.com/developerz-ai/multi-ai-router/releases/tag/v2.29.0
 [2.30.0]: https://github.com/developerz-ai/multi-ai-router/releases/tag/v2.30.0
 [2.30.1]: https://github.com/developerz-ai/multi-ai-router/releases/tag/v2.30.1
+[2.31.0]: https://github.com/developerz-ai/multi-ai-router/releases/tag/v2.31.0

CLAUDE.md

@@ -4,7 +4,7 @@ Self-hosted API router. A team of developers and AI agents shares one pool of AI
 
 Pooling is the product: **many Accounts of the same Provider is the normal case** (five Claude subs side by side). Nothing in the schema, UI, or routing may assume one account per provider.
 
-Full data plane shipped: accounts, pools, keys, `/v1/messages` + `/v1/chat/completions` + `/v1/responses`, cross-dialect translation, Claude subscriptions via the Agent SDK, ChatGPT/Codex OAuth, admin CRUD, 36 migrations (through 0035), and a complete SolidJS operator console. See `docs/idea/10-roadmap.md` for per-milestone state. Spec: `docs/idea/`. Behavior change → update the spec in the same PR. Shared code inventory: `docs/reusable-code.md`.
+Full data plane shipped: accounts, pools, keys, `/v1/messages` + `/v1/chat/completions` + `/v1/responses`, cross-dialect translation, Claude subscriptions via the Agent SDK, ChatGPT/Codex OAuth, admin CRUD, 37 migrations (through 0036), and a complete SolidJS operator console. See `docs/idea/10-roadmap.md` for per-milestone state. Spec: `docs/idea/`. Behavior change → update the spec in the same PR. Shared code inventory: `docs/reusable-code.md`.
 
 ## Response Rules
 

Dockerfile

@@ -205,7 +205,7 @@ LABEL org.opencontainers.image.title="multi-ai-router" \
       org.opencontainers.image.url="https://github.com/developerz-ai/multi-ai-router" \
       org.opencontainers.image.documentation="https://github.com/developerz-ai/multi-ai-router/blob/main/README.md" \
       org.opencontainers.image.licenses="MIT" \
-      org.opencontainers.image.version="2.30.1" \
+      org.opencontainers.image.version="2.31.0" \
       org.opencontainers.image.revision="${ROUTER_REVISION}"
 
 # ---- PID 1 ----

apps/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multi-ai-router/api",
-  "version": "2.30.1",
+  "version": "2.31.0",
   "private": true,
   "type": "module",
   "main": "src/main.ts",

apps/api/src/composition/admin.ts

@@ -2,6 +2,7 @@ import {
   type AccountRepository,
   type AdminCredentialRepository,
   type ApiKeyRepository,
+  type ApiKeyTombstoneRepository,
   type AuditRepository,
   type CredentialRefreshLock,
   createAdminMutationRepository,
@@ -100,6 +101,7 @@ export interface AdminPlaneDeps {
   readonly accounts: AccountRepository
   readonly refreshLock: Pick<CredentialRefreshLock, "tryRun">
   readonly keys: ApiKeyRepository
+  readonly keyTombstones: Pick<ApiKeyTombstoneRepository, "listAll">
   readonly pools: PoolRepository
   readonly auditEvents: AuditRepository
   readonly oauthStates: OauthStateRepository
@@ -165,7 +167,8 @@ export interface AdminPlane {
 }
 
 export function createAdminPlane(deps: AdminPlaneDeps): AdminPlane {
-  const { env, logger, now, accounts, keys, cipher, catalog, health, configDirs } = deps
+  const { env, logger, now, accounts, keys, keyTombstones, cipher, catalog, health, configDirs } =
+    deps
   const audit = createAuditRecorder(deps.auditEvents)
   const mutations = createAdminMutationRepository(deps.database)
 
@@ -388,7 +391,7 @@ export function createAdminPlane(deps: AdminPlaneDeps): AdminPlane {
       usage: createUsageService({
         history: createUsageHistoryRepository(deps.database),
         recent: createUsageRecentRepository(deps.database),
-        labels: catalogLabels({ keys, catalog }),
+        labels: catalogLabels({ keys, tombstones: keyTombstones, catalog }),
         ...env.usageRead,
         now,
       }),

apps/api/src/composition/index.ts

@@ -24,6 +24,7 @@ export function createRuntime(deps: RuntimeDeps): Runtime {
     accounts,
     refreshLock,
     keys,
+    keyTombstones,
     pools,
     auditEvents,
     oauthStates,
@@ -75,6 +76,7 @@ export function createRuntime(deps: RuntimeDeps): Runtime {
     refreshLock,
     recovery: recoveryComponents,
     keys,
+    keyTombstones,
     pools,
     auditEvents,
     oauthStates,

apps/api/src/composition/runtime-repositories.ts

@@ -2,6 +2,7 @@ import {
   createAccountRepository,
   createAdminCredentialRepository,
   createApiKeyRepository,
+  createApiKeyTombstoneRepository,
   createAuditRepository,
   createCredentialRefreshLockPool,
   createModelCatalogRepository,
@@ -21,6 +22,7 @@ export interface RuntimeRepositories {
   readonly schedulerLock: ReturnType<typeof createSchedulerLockPool>
   readonly accounts: ReturnType<typeof createAccountRepository>
   readonly keys: ReturnType<typeof createApiKeyRepository>
+  readonly keyTombstones: ReturnType<typeof createApiKeyTombstoneRepository>
   readonly pools: ReturnType<typeof createPoolRepository>
   readonly auditEvents: ReturnType<typeof createAuditRepository>
   readonly usageRecords: ReturnType<typeof createUsageRecordRepository>
@@ -51,6 +53,7 @@ export function createRuntimeRepositories(deps: RuntimeDeps): RuntimeRepositorie
     recoveryCooldownMs: env.recovery.cooldownMs,
   })
   const keys = createApiKeyRepository(database)
+  const keyTombstones = createApiKeyTombstoneRepository(database)
   const pools = createPoolRepository(database)
   const auditEvents = createAuditRepository(database)
   const usageRecords = createUsageRecordRepository(database)
@@ -76,6 +79,7 @@ export function createRuntimeRepositories(deps: RuntimeDeps): RuntimeRepositorie
     schedulerLock,
     accounts,
     keys,
+    keyTombstones,
     pools,
     auditEvents,
     usageRecords,

apps/api/src/composition/runtime-scheduler.ts

@@ -24,7 +24,7 @@ export function createRuntimeScheduler(
     sessions,
     usageRecords,
     auditEvents,
-    keys,
+    keyTombstones,
     oauthStates,
     usageHistory,
     accounts,
@@ -44,7 +44,7 @@ export function createRuntimeScheduler(
     sessions,
     usageRecords,
     auditEvents,
-    apiKeys: keys,
+    keyTombstones,
     oauthStates,
     history: usageHistory,
     accounts,

apps/api/src/scheduler/tasks/index.ts

@@ -1,7 +1,7 @@
 import type {
   AccountRepository,
   AccountRow,
-  ApiKeyRepository,
+  ApiKeyTombstoneRepository,
   AuditRepository,
   ModelCatalogRepository,
   OauthStateRepository,
@@ -51,7 +51,7 @@ export interface ScheduledTaskDeps
   readonly sessions: Pick<SessionRepository, "deleteIdleBefore">
   readonly usageRecords: Pick<UsageRecordRepository, "deleteRetainedBatch">
   readonly auditEvents: Pick<AuditRepository, "deleteOlderThan">
-  readonly apiKeys: Pick<ApiKeyRepository, "deleteRevokedOlderThan">
+  readonly keyTombstones: Pick<ApiKeyTombstoneRepository, "purgeRevoked" | "deleteOlderThan">
   readonly oauthStates: Pick<OauthStateRepository, "deleteExpiredBefore">
   readonly history: Pick<UsageHistoryRepository, "backfill" | "deleteRetainedHistory">
   /**
@@ -175,7 +175,7 @@ export function createScheduledTasks(deps: ScheduledTaskDeps): readonly Schedule
       history: deps.history,
       auditEvents: deps.auditEvents,
       taskRuns: deps.scheduledTasks,
-      apiKeys: deps.apiKeys,
+      keyTombstones: deps.keyTombstones,
       retention: env.retention,
       intervalMs: intervals.janitor_sweep,
       batchSize,

apps/api/src/scheduler/tasks/janitor.ts

@@ -1,5 +1,5 @@
 import type {
-  ApiKeyRepository,
+  ApiKeyTombstoneRepository,
   AuditRepository,
   ScheduledTaskRepository,
   SessionRepository,
@@ -11,21 +11,23 @@ import type { ScheduledTask } from "../types"
 import { runSweeps } from "./sweep"
 
 /**
- * The janitor: the retention sweep for the six tables that grow without bound.
+ * The janitor: the retention sweep for the seven tables that grow without bound.
  *
- * One task rather than six, because they share a schedule and an operator reads
+ * One task rather than seven, because they share a schedule and an operator reads
  * them as one answer — "the janitor ran 4 min ago and deleted 812 rows"
  * (docs/idea/09-deployment.md, "Cleanups & retention"). The per-category counts
  * are in the summary line, so "deleted 812 rows" can still be broken down.
  *
  * **Every window is `env.retention`, never a number in this file** (CLAUDE.md
  * non-negotiable 11). What is decided here is only the *order*, and it is
- * deliberate: revoked keys go last, because deleting one cascades to its
- * sessions and nulls the key on its usage rows, and doing that first would make
- * the sweeps in front of it race their own cascade for no reason.
+ * deliberate: revoked keys go after the rest, because deleting one cascades to its
+ * sessions and scope rows (its usage rows keep the id, and a tombstone written in the same
+ * statement keeps the name), and doing that first would make the sweeps in front of it race their
+ * own cascade for no reason. The key-tombstone sweep goes last: it touches only its own table, and
+ * a tombstone written by this very tick's purge is far too young to be swept.
  *
- * Two of the six grow slowly enough to have been overlooked rather than
- * excluded, and both are here for the same reason the other four are: `usage_daily`
+ * Two of the seven grow slowly enough to have been overlooked rather than
+ * excluded, and both are here for the same reason the other five are: `usage_daily`
  * banks one row per distinct `(day, key, account, pool, model)` and outlives the
  * raw rows by design, which is not the same as outliving them forever; and
  * `scheduled_task_runs` takes a row per task per tick, about a thousand a day,
@@ -48,7 +50,7 @@ export interface JanitorDeps {
   readonly history: Pick<UsageHistoryRepository, "deleteRetainedHistory">
   readonly auditEvents: Pick<AuditRepository, "deleteOlderThan">
   readonly taskRuns: Pick<ScheduledTaskRepository, "deleteOlderThan">
-  readonly apiKeys: Pick<ApiKeyRepository, "deleteRevokedOlderThan">
+  readonly keyTombstones: Pick<ApiKeyTombstoneRepository, "purgeRevoked" | "deleteOlderThan">
   /** Every retention window, straight from `env.retention`. */
   readonly retention: RetentionConfig
   /** `JANITOR_INTERVAL_MINUTES`, in milliseconds. The runner jitters it. */
@@ -75,6 +77,10 @@ export function createJanitorTask(deps: JanitorDeps): ScheduledTask {
       const staleAudit = before(now, retention.auditDays * DAY_MS)
       const staleTaskRuns = before(now, retention.taskRunsDays * DAY_MS)
       const purgeableKeys = before(now, retention.revokedKeysDays * DAY_MS)
+      // A tombstone labels rollups, so it lives as long as they do — plus one day, because rollups
+      // age by whole UTC day: the purge day's own rollup is still inside the window for up to a day
+      // after `purged_at + usageDailyDays`.
+      const staleTombstones = before(now, (retention.usageDailyDays + 1) * DAY_MS)
 
       const report = await runSweeps(
         [
@@ -109,7 +115,12 @@ export function createJanitorTask(deps: JanitorDeps): ScheduledTask {
           },
           {
             category: "revokedKeys",
-            deleteBatch: (limit) => deps.apiKeys.deleteRevokedOlderThan(purgeableKeys, limit),
+            // Delete and tombstone are one statement; `purged_at` is this tick's clock.
+            deleteBatch: (limit) => deps.keyTombstones.purgeRevoked(purgeableKeys, now, limit),
+          },
+          {
+            category: "keyTombstones",
+            deleteBatch: (limit) => deps.keyTombstones.deleteOlderThan(staleTombstones, limit),
           },
         ],
         { batchSize: deps.batchSize, signal },

apps/api/src/services/keys/mutations.ts

@@ -156,7 +156,10 @@ export function createKeyMutations(deps: KeysServiceDeps): Pick<KeysService, Key
         deps.mutations.run({ kind: "key", id }, async (tx) => {
           const current = await tx.keys.findById(id)
           if (current === undefined) return notFound(`no key with id "${id}"`)
-          if (!(await tx.keys.delete(id))) return notFound(`no key with id "${id}"`)
+          // One statement deletes the row and writes its tombstone (the key's name outlives its
+          // row for the rollups). The row is already locked FOR UPDATE by `run`.
+          if (!(await tx.tombstones.deleteKey(id, deps.now())))
+            return notFound(`no key with id "${id}"`)
           await createAuditRecorder(tx.audit).record({
             kind: AUDIT_KINDS.keyDeleted,
             subjectType: AUDIT_SUBJECTS.key,

apps/api/src/services/usage-read/labels.ts

@@ -1,24 +1,48 @@
-import type { ApiKeyRepository } from "@multi-ai-router/db"
+import type { ApiKeyRepository, ApiKeyTombstoneRepository } from "@multi-ai-router/db"
 import type { RoutingCatalogStore } from "../catalog"
-import type { UsageLabelSets } from "./service"
+import type { KeyLabel, UsageLabelSets } from "./service"
 
 /**
  * Naming the subjects of a usage report, from what the router already has.
  *
  * Accounts and pools come from the warm catalog, so the two axes an operator filters on cost
- * nothing; keys need the one query, which is unremarkable on the admin plane and is why this is not
- * a third cache. A miss is not an error — spend that happened is still spend, and a deleted subject
- * keeps its totals under its id.
+ * nothing; keys need two queries, which is unremarkable on the admin plane and is why this is not
+ * a third cache. A miss is not an error — spend that happened is still spend, and a subject with
+ * no name anywhere keeps its totals under its id.
+ *
+ * A key is named by its live row, else by the tombstone its purge or delete left behind (the
+ * rollups outlive the row). Tombstones are read through their own method and merged here, never
+ * unioned into `keys.list()`: that list is the admin keys list, which must not show a purged key.
+ *
+ * The two reads are not one snapshot. A delete committing between them removes the row after
+ * `keys.list()` saw it, so for that one load the key is still named from the live read; a delete
+ * committing the other way round (row read as gone, tombstone read before the commit lands) shows
+ * a transient "deleted" for that key until the next load. Neither is worse than the label being
+ * decoration, so it is not worth a transaction.
  */
 export function catalogLabels(deps: {
   readonly keys: Pick<ApiKeyRepository, "list">
+  readonly tombstones: Pick<ApiKeyTombstoneRepository, "listAll">
   readonly catalog: Pick<RoutingCatalogStore, "accounts" | "pools">
 }): () => Promise<UsageLabelSets> {
-  return async () => ({
-    keys: new Map((await deps.keys.list()).map((key) => [key.id, key.name])),
-    accounts: new Map(
-      deps.catalog.accounts().map((account) => [account.id, account.snapshot.label]),
-    ),
-    pools: new Map(deps.catalog.pools().map((pool) => [pool.id, pool.name])),
-  })
+  return async () => {
+    const [live, stones] = await Promise.all([deps.keys.list(), deps.tombstones.listAll()])
+    const keys = new Map<string, KeyLabel>()
+    // Tombstones first, so a live row wins if the two ever coexist (a delete racing a read).
+    for (const row of [...stones, ...live]) {
+      keys.set(row.id, {
+        name: row.name,
+        owner: row.owner,
+        ownerKind: row.ownerKind,
+        tool: row.tool,
+      })
+    }
+    return {
+      keys,
+      accounts: new Map(
+        deps.catalog.accounts().map((account) => [account.id, account.snapshot.label]),
+      ),
+      pools: new Map(deps.catalog.pools().map((pool) => [pool.id, pool.name])),
+    }
+  }
 }

apps/api/src/services/usage-read/recent.ts

@@ -2,7 +2,7 @@ import type { Dialect, EgressMode, ProviderId, UsageFault } from "@multi-ai-rout
 import { isSuccessOutcome, UsageOutcome, usageOutcomeFault } from "@multi-ai-router/core"
 import type { RecentAttemptRow } from "@multi-ai-router/db"
 import { z } from "zod"
-import type { UsageLabelSets } from "./service"
+import type { DisplayNames } from "./types"
 
 /**
  * The live request feed's contract: what the console may ask for, and what one
@@ -93,7 +93,7 @@ export function outcomesFor(query: RecentQuery): readonly UsageOutcome[] | undef
  * served, the pool it was drawn from.
  *
  * Same three fields and same rules as a breakdown row: a label may be missing
- * because the subject was deleted (usage rows outlive what they name) or because
+ * because the subject was deleted (usage rows outlive what they name; for a key, no live row and no tombstone) or because
  * the dimension did not apply (a key scoped `all` was placed by no pool), and
  * the reason is on the row so the console never has to guess which.
  */
@@ -150,7 +150,7 @@ export interface RecentView {
 
 export function toRecentAttemptView(
   row: RecentAttemptRow,
-  labels: UsageLabelSets,
+  labels: DisplayNames,
 ): RecentAttemptView {
   return {
     id: row.id,

apps/api/src/services/usage-read/service.ts

@@ -2,11 +2,13 @@ import type { UsageHistoryRepository, UsageRecentRepository } from "@multi-ai-ro
 import { type AdminResult, ok } from "../admin/result"
 import { outcomesFor, type RecentQuery, type RecentView, toRecentAttemptView } from "./recent"
 import { readSummary } from "./summary"
+import { keyNames } from "./summary-view"
 import type { UsageWindowQuery } from "./window"
 
 /** Summary facts share one database snapshot; labels are current best-effort decoration. */
 
 export type {
+  KeyLabel,
   UsageBreakdownRow,
   UsageCoverage,
   UsageLabelSets,
@@ -54,11 +56,14 @@ export function createUsageService(deps: UsageServiceDeps): UsageService {
         }),
       ])
 
+      // Projected once, not per row: a poll costs O(rows + labels).
+      const names = { keys: keyNames(labels.keys), accounts: labels.accounts, pools: labels.pools }
+
       // `limit` is echoed as asked for, never as `rows.length`: a quiet router
       // returning four rows has truncated nothing, and a caption reading "at
       // most 4" would be describing the traffic rather than the page.
       return ok({
-        attempts: rows.map((row) => toRecentAttemptView(row, labels)),
+        attempts: rows.map((row) => toRecentAttemptView(row, names)),
         limit: query.limit,
       })
     },

apps/api/src/services/usage-read/summary-view.ts

@@ -1,6 +1,6 @@
 import type { UsageGroupRow, UsageGroupSeriesPoint, UsageSeriesPoint } from "@multi-ai-router/db"
 import { densify } from "./axis"
-import type { UsageBreakdownRow, UsageSeriesEntry } from "./types"
+import type { KeyLabel, UsageBreakdownRow, UsageSeriesEntry } from "./types"
 
 /**
  * Puts the summary series on the same axis every breakdown row uses.
@@ -25,6 +25,11 @@ export function alignSeries(
   })
 }
 
+/** Projects the loader's richer key entries to the display name the wire shape carries. */
+export function keyNames(keys: ReadonlyMap<string, KeyLabel>): ReadonlyMap<string, string> {
+  return new Map([...keys].map(([id, key]) => [id, key.name]))
+}
+
 export function label(
   rows: readonly UsageGroupRow[],
   names: ReadonlyMap<string, string>,