feat: add durable idempotency key storage

Author: mikewheeleer

docs/db/schema.md

@@ -99,6 +99,13 @@ The schema enforces eight invariants (I1–I8), verified by
 | `billingInvoices` | `billing_invoices` | Invoice records |
 | `sessions` | `sessions` | Auth sessions with sliding and absolute expiry |
 | `backfillProgress` | `backfill_progress` | Backfill job progress tracking |
+| `idempotencyKeys` | `idempotency_keys` | Durable 24-hour response replay records |
+
+Idempotency records are keyed by `(route, key)` and include the request body
+fingerprint, response status, response body, and expiry timestamp. The unique
+primary key gives billing and diagnostics handlers a shared database-level
+claim point; expired rows can be removed by a scheduled cleanup query using the
+`expires_at` index.
 
 ## Security Boundary (Sensitive Fields)
 

src/db/migrations/0005_idempotency_keys.sql

@@ -0,0 +1,12 @@
+CREATE TABLE IF NOT EXISTS "idempotency_keys" (
+  "route" text NOT NULL,
+  "key" text NOT NULL,
+  "body_fingerprint" text NOT NULL,
+  "status_code" integer NOT NULL,
+  "response_body" jsonb NOT NULL DEFAULT '{}'::jsonb,
+  "expires_at" timestamp NOT NULL,
+  CONSTRAINT "idempotency_keys_pkey" PRIMARY KEY ("route", "key")
+);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "idempotency_keys_expires_at_idx"
+  ON "idempotency_keys" USING btree ("expires_at");

src/db/schema-consistency.test.ts

@@ -139,8 +139,8 @@ describe("schema contract invariants", () => {
       expect(exportedTableNames.sort()).toEqual(schemaTableNames.sort());
     });
 
-    it("has exactly 11 tables", () => {
-      expect(schema.SCHEMA_TABLES).toHaveLength(11);
+    it("has exactly 12 tables", () => {
+      expect(schema.SCHEMA_TABLES).toHaveLength(12);
     });
 
     it("every SCHEMA_TABLES entry has a defined table reference", () => {

src/db/schema.ts

@@ -6,6 +6,8 @@ import {
   boolean,
   timestamp,
   index,
+  primaryKey,
+  jsonb,
   numeric,
   check,
   type PgTableWithColumns,
@@ -659,6 +661,23 @@ export const backfillProgress = pgTable(
   }),
 );
 
+/** Shared durable response cache used by idempotent mutating routes. */
+export const idempotencyKeys = pgTable(
+  "idempotency_keys",
+  {
+    route: text("route").notNull(),
+    key: text("key").notNull(),
+    bodyFingerprint: text("body_fingerprint").notNull(),
+    statusCode: integer("status_code").notNull(),
+    responseBody: jsonb("response_body").notNull().default({}),
+    expiresAt: timestamp("expires_at").notNull(),
+  },
+  (table) => ({
+    primaryKey: primaryKey({ columns: [table.route, table.key] }),
+    expiresAtIdx: index("idempotency_keys_expires_at_idx").on(table.expiresAt),
+  }),
+);
+
 // ---------------------------------------------------------------------------
 // Compatibility Version
 // ---------------------------------------------------------------------------
@@ -794,5 +813,5 @@ export const SCHEMA_TABLES: Array<{ name: string; table: PgTableWithColumns<any>
   { name: "billingInvoices", table: billingInvoices },
   { name: "sessions", table: sessions },
   { name: "backfillProgress", table: backfillProgress },
+  { name: "idempotencyKeys", table: idempotencyKeys },
 ];
-