@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/db/schema.js

@@ -0,0 +1,1433 @@
+/**
+ * Database schema — the source of truth. Edit here → `bun run db:generate` → `bun run db:migrate`.
+ *
+ * Cloudflare D1 (SQLite): tables are `sqliteTable` from `drizzle-orm/sqlite-core`; timestamps are
+ * `integer({ mode: "timestamp_ms" })`, booleans `integer({ mode: "boolean" })`, JSON columns
+ * `text({ mode: "json" })`. Columns are written snake_case from camelCase field names (the
+ * `casing` option in drizzle.config.ts and db/client.ts). Enums are `text({ enum })` — SQLite has
+ * no enum type, so the allowed values are enforced by the type and the app, not the database.
+ *
+ * Timestamps default app-side (`$defaultFn` / `$onUpdate`): every write goes through Drizzle, and
+ * a JS `Date` keeps millisecond precision without depending on which SQLite `unixepoch()` variant
+ * the D1 build carries.
+ *
+ * D1 has NO documented transaction atomicity through `db.transaction()` (each statement auto-commits);
+ * a multi-statement write that must be atomic goes through `db.batch([...])`. Every write in this
+ * schema is designed as ONE statement (`onConflictDoNothing` / `onConflictDoUpdate`), so nothing
+ * here needs a transaction at all.
+ */
+import { sql } from "drizzle-orm";
+import { index, integer, primaryKey, sqliteTable, text, uniqueIndex, } from "drizzle-orm/sqlite-core";
+/**
+ * Collections this oracle has been hired to evaluate (README "How a claim flows" step 1). Upserted on
+ * `collectionId` by `POST /v1/collections/register`: `ownerDid` is the CHAIN owner (who deposits
+ * the owner→oracle delegation in the UCAN Store), `enrolledByDid` whoever passed the register
+ * gates. This is the poll-set the cron scans, and the authority the read path trusts for the
+ * delegation root.
+ */
+export const watchedCollections = sqliteTable("watched_collections", {
+    collectionId: text().primaryKey(),
+    /**
+     * The CHAIN owner's wallet DID (`entity.owner` of the collection's deed entity) — who pays the
+     * evaluation fees, and the delegation root we look up when reading this collection's claims.
+     * Always the chain's answer, never the enroller's.
+     */
+    ownerDid: text().notNull(),
+    /**
+     * Who registered it — the principal that signed the register: the owner, or a holder of an
+     * active evaluate grant for the collection. Admitted by the read gate beside the owner; NEVER
+     * the delegation root (that stays the owner's, above — the Matrix delegation is theirs).
+     */
+    enrolledByDid: text().notNull(),
+    /**
+     * The collection's on-chain evaluation payment as accepted at (re-)register — what this
+     * collection pays per `MsgEvaluateClaim` (the chain splits it 80/10/10 to the oracle). Checked
+     * against the oracle config's `pricing` on every register; recorded so the dashboard can show it.
+     */
+    evaluationDenom: text(),
+    evaluationAmount: text(),
+    /** Protocol entity DID backing the collection (blocksync `collection.protocol`) — where `#rub` is anchored. */
+    protocolDid: text(),
+    /**
+     * The pinned rubric: sha256 of its stored bytes, which IS its id and the on-chain
+     * LinkedResource `proof`. Pinned by the workflow's evaluate step on first sight; the chain is the
+     * authority. Null until
+     * resolved.
+     */
+    rubricId: text(),
+    /**
+     * The owner→oracle delegation (base64 CAR), persisted at register time so the read path makes
+     * ZERO UCAN-Store round trips. Refreshed from the store when missing/expired (the portal still
+     * deposits there — the store stays the fleet registry and our refresh source).
+     */
+    delegationCar: text(),
+    /** When the stored delegation expires (null = it declares no expiry). */
+    delegationExpiresAt: integer({ mode: "timestamp_ms" }),
+    /** Where the commissioner is reached (review requests, pauses). Captured at register. */
+    contactEmail: text(),
+    /**
+     * `paused` stops the scan enqueuing anything for this collection — the engine answering 402
+     * (credits exhausted) or 403 (not hired) flips it, an operator flips it back. The row and its
+     * delegation stand.
+     */
+    status: text({ enum: ["active", "paused"] })
+        .notNull()
+        .default("active"),
+    /**
+     * WHY the engine paused it, for the operator and the dashboard: `engine-credits` (402 — every
+     * active collection pauses, resume after the top-up), `engine-no-grant` (403 — this oracle
+     * lost the collection's `EvaluateClaimAuthorization`; re-register once re-granted) or
+     * `rubric-unusable` (the engine's rubric manifest is `unusable`, or a 200 `decision.status:
+     * "unusable"` — the engine cannot resolve/bind the protocol's rubric to its form / the facts;
+     * every claim would be refused the same way, so the broken catalog entry is paid for at most
+     * once; resume once `#rub`/`#vct` are fixed) or `admin-unfunded` (the chain refused our
+     * `MsgEvaluateClaim` with "insufficient funds: payment withdrawal failed" — the collection's
+     * admin account cannot pay the evaluation leg, and every further decision would be billed by
+     * the engine and then parked the same way; `cron/funding.ts` resumes it and re-delivers the
+     * parked decisions once the account covers `evaluationAmount`), or — per-review billing
+     * (`billingSourceId` set) — `payer-credits` (the facilitator refused the reservation for want of
+     * the paying organisation's credits: a top-up fixes it) or `payer-delegation` (no usable
+     * review-billing delegation: none, expired, cap used up, its signer no longer the
+     * organisation's owner, the company disputed, no published price — a new delegation in the
+     * Console fixes it), or `oracle-plan` (the facilitator says IXO's plan does not let this
+     * oracle bill reviews: IXO's to fix, paged, the owner not told); `cron/payer-billing.ts`
+     * resumes all three. Null on an
+     * operator pause; cleared on resume/re-register. A TEXT column: the enum is type-only (SQLite),
+     * so a new value needs no migration.
+     */
+    pausedReason: text({
+        enum: [
+            "engine-credits",
+            "engine-no-grant",
+            "rubric-unusable",
+            "admin-unfunded",
+            "payer-credits",
+            "payer-delegation",
+            "oracle-plan",
+        ],
+    }),
+    /**
+     * Per-review checker billing (IXO's plan for the oracle, payments/review-billing.ts): the
+     * Decision API source whose stored delegation pays for each of this collection's claims over
+     * x402 — set at register when the collection's company (the engine's answer) holds one, so the
+     * collection registered with an empty evaluation leg. Null = the chain's evaluation payment pays
+     * (today's model; never both). Re-resolved on every claim's reservation, and written again if
+     * the organisation's paying source changed.
+     */
+    billingSourceId: text(),
+    /**
+     * The cron scan watermark: the newest claim `submissionDate` we've enqueued for this
+     * collection. Null = never scanned, so the next tick sweeps the collection from the beginning.
+     * Scans are inclusive (`>=`) so claims sharing a timestamp are never skipped; `claim_ingests`
+     * is the forever dedup that stops the boundary claim being re-pulled.
+     */
+    cursor: text(),
+    /**
+     * The cron rotation clock: stamped on EVERY visit (found claims, found nothing, or failed).
+     * Ticks pick the least-recently-scanned collections first, so a bounded per-tick batch still
+     * covers every watched collection fairly. Null = never scanned → front of the queue.
+     */
+    lastScannedAt: integer({ mode: "timestamp_ms" }),
+    /**
+     * Whether the act seam's on-chain amount may stand (company authority D7, F6): `off` — the
+     * default, the owner never said yes — ignores it for the lane's default and logs it. Set by the
+     * collection OWNER only (`PATCH /v1/collections/:id/settings`), enforced by the act lane
+     * (chain-write.ts). A TEXT column: the enum is type-only (SQLite).
+     */
+    operatorAmounts: text({ enum: ["off", "allowed"] })
+        .notNull()
+        .default("off"),
+    /**
+     * Who set `operatorAmounts` — the chain owner's address as the settings route checked it. The
+     * act lane honours `allowed` only while this is STILL the collection's live owner, so a yes
+     * never outlives an ownership transfer: the new owner has to say it again (D7).
+     */
+    operatorAmountsBy: text(),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+    updatedAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date())
+        .$onUpdate(() => new Date()),
+}, (t) => [
+    // The cron's rotation read: active rows, least recently scanned first.
+    index("watched_collections_status_last_scanned_idx").on(t.status, t.lastScannedAt),
+]);
+/**
+ * The ingestion ledger: one row per claim we've ever accepted, and where it got to.
+ *
+ * This — not the existence of a Workflow instance — is the source of truth for "have we got this
+ * claim already?", because instances are retained only 3–30 days; after that the runtime would
+ * happily accept the same id again and we'd silently re-ingest forever.
+ *
+ * The workflow owns its row for its whole lifecycle (record-queued → … → mark-processed); the
+ * cron never writes it. The cron's only dedupe is "row exists → already started", plus the
+ * workflow instance id's own idempotency. The claim is taken by INSERTing here with
+ * `onConflictDoNothing()` — one statement, so the primary key is the mutex: no select-then-insert
+ * race, and no matching on error strings.
+ */
+export const claimIngests = sqliteTable("claim_ingests", {
+    claimId: text().primaryKey(),
+    collectionId: text().notNull(),
+    status: text({ enum: ["queued", "processing", "processed", "failed", "skipped"] })
+        .notNull()
+        .default("queued"),
+    /**
+     * How the claim arrived (Go Prod §7.1): `chain` (the cron scan) or `api` (`POST /v1/api/claims`,
+     * `collectionId` = the scope id `api:<sourceId>:<protocolDid>`). `ReviewComplete` reads it to
+     * pick the `ClaimSource` its re-pull goes through. Defaulted, so every pre-existing row and every
+     * cron insert that never names it stays `chain`.
+     */
+    lane: text({ enum: ["chain", "api"] })
+        .notNull()
+        .default("chain"),
+    /** The Workflow instance id (the claimId, or its sha256 — lib/ids.ts), to follow it while it lives. */
+    instanceId: text(),
+    /** The terminal failure's message, for the claim read and the operator — null unless `failed`. */
+    error: text(),
+    /**
+     * When the collection's owner erased this CHAIN claim's answer copies (company authority F14,
+     * `DELETE /v1/claims/:claimId/body`, lib/claim-erase.ts): the fact transcripts on
+     * `decisions.facts` and the registry's `normalizedText`. Null = never erased — the oracle never
+     * erases chain-lane data on its own. The body itself was never stored here (it lives on the
+     * claim's own store). Never set on an `api` row — that lane's marker is `api_claims.bodyErasedAt`.
+     */
+    erasedAt: integer({ mode: "timestamp_ms" }),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+    updatedAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date())
+        .$onUpdate(() => new Date()),
+}, (t) => [
+    // Covers the hot list query (`GET /v1/claims`, routes/v1/claims.ts): filtered by collectionId,
+    // ordered by (createdAt, claimId) desc for keyset pagination. Same leading column as the
+    // single-column index this replaces, so it serves an equality-only lookup on collectionId
+    // too (e.g. a future one) — no need to keep both.
+    index("claim_ingests_collection_created_claim_idx").on(t.collectionId, t.createdAt, t.claimId),
+    // The operator's claim list (`GET /v1/api/admin/claims`, lib/api-lane/claim-list.ts): the
+    // chain branch over EVERY watched collection is `lane = 'chain'` ordered by (createdAt,
+    // claimId) desc — without it that page is a full scan and sort of the ledger.
+    index("claim_ingests_lane_created_claim_idx").on(t.lane, t.createdAt, t.claimId),
+]);
+/**
+ * The engine's decision as returned to THIS oracle (`POST /v1/decisions`, README "How a claim flows" step 5),
+ * cached once per claim. The engine's ledger is the authority — this row exists so the act lane,
+ * the review fold and the claim read never re-ask for a decision already made. `claimId` PK +
+ * `onConflictDoNothing` is the decided-once guard on our side, matching the engine's own
+ * evaluated-once mutex. Written once by the evaluate step; changed only by the review fold (the
+ * SAME decision with the answers folded in — never a second evaluation) and by delivery state
+ * (`chainStatus`/`txHash`/`chainError`).
+ *
+ * A claim the facts lane could not build for — `unusable` (the engine's rubric manifest says the
+ * protocol's rubric cannot be resolved or bound: no `#rub`, swapped bytes, a drifted `#vct` — its
+ * issues verbatim), `invalid_facts` (the producer's answer doesn't match the rubric's work order —
+ * our/the provider's bug) — gets a row too, with the engine never asked to decide (nothing to
+ * decide, nothing charged): `status` names the reason, `explanation` the issues, and every
+ * engine-owned column (`rubricId` where unknown, `factsDigest`, `verdict`, `resultDigest`,
+ * `decision`) is null. A decide-time `unusable` (the engine's fact-coverage check) is a real
+ * decision row (receipt and all); both pause the collection (`watched_collections.pausedReason`).
+ */
+export const decisions = sqliteTable("decisions", {
+    claimId: text().primaryKey(),
+    collectionId: text().notNull(),
+    /** The rubric the engine judged against — pinned per claim, so a later re-anchor changes nothing here. */
+    rubricId: text(),
+    /** sha256(canonicalJson(FactSet)) — what we sent; binds this decision to the facts we produced. */
+    factsDigest: text(),
+    /** The engine's verdict (approve · partial · reject · review); null on a facts-lane outcome. */
+    verdict: text(),
+    /**
+     * `decided` · `pending_review` · `unusable` from the engine; the facts lane's `unusable` ·
+     * `invalid_facts`; or the engine's refusal of the claim's content (company authority) —
+     * `content_mismatch` · `payload_too_large`, recorded like a facts-lane outcome (no engine
+     * columns, `skipped`). Type-only enum: a new value needs no migration.
+     */
+    status: text().notNull(),
+    /** The engine's `resultDigest` — what a review answer is folded against (`answeredAgainst`). */
+    resultDigest: text(),
+    /** The engine's signed receipt CID — what `MsgEvaluateClaim.verification_proof` carries. */
+    receiptCid: text(),
+    /**
+     * The receipt itself — the engine's Ed25519 compact JWS (codes, scores, identifiers; never
+     * answer values). The receipt is the engine's product and the artifact this oracle acted on,
+     * so the oracle holds it: `GET /v1/claims/:claimId` serves it, and a Matrix republish of the
+     * CID (a follow-up) needs the bytes. Written together with `receiptCid`, always.
+     */
+    receiptJws: text(),
+    /** The engine's decision object verbatim (codes, scores, outcomes — never answer values). */
+    decision: text({ mode: "json" }).$type(),
+    /** The engine's plain-English narrative, display-only. */
+    explanation: text(),
+    /**
+     * The `ext`/`ai` facts this decision was made on, frozen exactly as they went to the engine
+     * (never `answers`/`attachments` — this row outlives the claim's erasable surface). The act
+     * policy (act.ts) reads them by name at signing time, which is why they cannot live in the
+     * connector cache: that dies in the same batch that writes this row (claim-ingest.ts `record`).
+     * Null ONLY on a row the engine never decided — a facts-lane `unusable`/`invalid_facts`, which
+     * is `skipped` from the start; a `decided` row without them is an ingest contract violation and
+     * the act lane parks it rather than sign blind.
+     */
+    facts: text({ mode: "json" }).$type(),
+    /**
+     * The engine's `erroredFacts` (engine/types.ts `ErroredFact`): each errored fact's lane-prefixed
+     * name and its own error text, each detail capped — WHY a claim was held, which the engine's
+     * hashed reason line never says. Only the derived list, never facts or answers; written in the
+     * decision's own statement (and replaced by a fold that carries one). Null when nothing errored
+     * or the engine sent none (an older engine).
+     */
+    erroredFacts: text({ mode: "json" }).$type(),
+    /**
+     * The engine's `pendingTaskDetails` (engine/types.ts `PendingTaskDetail`): per pending
+     * `unique:<ruleId>` task, the duplicate score and the prior claim's id — what the review view's
+     * `duplicates` is built from. Written with the decision only (a fold always answers `{}`:
+     * nothing pends after it). Null when none pends or the engine sent none (an older engine).
+     */
+    pendingTaskDetails: text({ mode: "json" }).$type(),
+    /**
+     * Where the verdict got to on chain: `pending` (not yet acted on) → `submitted` (our tx) /
+     * `blocked` (broadcast failed, retryable) / `skipped` (AUTO_SIGN off, or a non-terminal
+     * verdict) / `held` (the oracle's act policy is keeping it back for a later `signEvaluation` —
+     * NOT a delivered state) / `owner_submitted` (someone else evaluated it first — the chain locks
+     * a claim on its first terminal evaluation). A TEXT column: the enum is type-only (SQLite), so a
+     * new value needs no migration.
+     */
+    chainStatus: text({
+        enum: ["pending", "submitted", "blocked", "skipped", "held", "owner_submitted"],
+    })
+        .notNull()
+        .default("pending"),
+    txHash: text(),
+    /** The last delivery failure (a `blocked` reason, or the broadcast error the step is retrying); null once submitted. */
+    chainError: text(),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+    updatedAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date())
+        .$onUpdate(() => new Date()),
+}, (t) => [
+    // The review-reminder sweep (Go Prod §10.4: 3 and 14 days) and the operator's pending list:
+    // rows in one status, oldest first.
+    index("decisions_status_created_idx").on(t.status, t.createdAt),
+    // The funding cron's parked decisions of one collection (cron/funding.ts `redeliverParked`:
+    // collection + `chainStatus in (pending, blocked)`, oldest first) — without it every resume
+    // walked the whole table.
+    index("dec_collection_chain").on(t.collectionId, t.chainStatus, t.createdAt),
+]);
+/**
+ * Human-review answers + their fold (README "How a claim flows" step 6). The decision row stays as the engine
+ * returned it — the fold is recorded BESIDE it. `claimId` PK = the answered-once mutex
+ * (`onConflictDoNothing`): the POST is idempotent until folded, then conflicts. `foldedAt` is
+ * written once by the `ReviewComplete` workflow when the engine has folded the answers.
+ */
+export const claimReviews = sqliteTable("claim_reviews", {
+    claimId: text().primaryKey(),
+    /** `{ [taskId]: boolean | string }` — covers EXACTLY the decision's pending review tasks. */
+    answers: text({ mode: "json" }).$type().notNull(),
+    /** From the UCAN principal. Our word alone unless `attestationJws` backs it. */
+    reviewerDid: text().notNull(),
+    /**
+     * The reviewer's signed attestation over `answers` (compact JWS, design §B.3) — stored VERBATIM
+     * because the signature is over exact bytes; null for a review answered without one (optional
+     * this round). Erasable with this row: it is the one place answer VALUES are signed, which is why
+     * the receipt and the Matrix card carry only its CID.
+     */
+    attestationJws: text(),
+    answeredAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+    foldedAt: integer({ mode: "timestamp_ms" }),
+    /**
+     * Why the fold did not land (the engine's `STALE_REVIEW` — the answers named a digest the engine
+     * no longer holds — or a validation refusal), surfaced on `GET /v1/reviews/:claimId` so the
+     * reviewer can answer again; a re-POST clears it.
+     */
+    foldError: text(),
+    /**
+     * The reviewer's grant (company authority D2): base64 CAR, one link, controller → reviewer
+     * did:ixo, as `ReviewerGrant` in lib/engine/types.ts — the bytes the controller FILED
+     * (`collection_reviewers.delegation`), never the reviewer's copy. Stored with the answers so a
+     * retried fold forwards the same proof. Erasable with the row.
+     */
+    reviewerGrant: text(),
+});
+/**
+ * A chain collection's reviewers (company authority D2, F2, F12): each row one signed delegation
+ * from a root the engine accepts (`rootDid` — the collection owner or an entity controller) to a
+ * member `did:ixo`, kept with what it says (`expiresAt`) so a check needs no CAR parse — as
+ * `api_members` keeps a source's grants. The CID is the identity: a re-grant is a new row, and
+ * revoking stamps `revokedAt` (a row is never edited otherwise). Read by (collection, member) when a
+ * review is answered; enforced from CA-M3.
+ */
+export const collectionReviewers = sqliteTable("collection_reviewers", {
+    collectionId: text().notNull(),
+    /** The member's `did:ixo` the delegation names as audience. */
+    memberDid: text().notNull(),
+    /** Who signed it: the root the engine checks against the chain. */
+    rootDid: text().notNull(),
+    /** Base64 of the delegation CAR. */
+    delegation: text().notNull(),
+    delegationCid: text().notNull(),
+    /** The delegation's expiry, in ms (`exp * 1000`). Required: a reviewer grant never lives forever. */
+    expiresAt: integer({ mode: "timestamp_ms" }).notNull(),
+    revokedAt: integer({ mode: "timestamp_ms" }),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+}, (t) => [
+    primaryKey({ columns: [t.collectionId, t.delegationCid] }),
+    // The review gate: this member's grants on this collection.
+    index("collection_reviewers_member_idx").on(t.collectionId, t.memberDid),
+]);
+/**
+ * Canonical-body registry for duplicate detection (duplicate spec §9; the registry is
+ * oracle-side — docs/ENGINE-CONTRACT.md "Fact coverage + manifest") — one row per
+ * (collection, digest, claim), written by the stock producer's resolve phase BEFORE it reads
+ * siblings (insert-self-first, spec §3.2): two racing claims each see the other, so neither can
+ * slip through the race window. `onConflictDoNothing` on the PK makes the insert idempotent under
+ * workflow step retry. The prior-claim scope is every claim THIS oracle ingested for the
+ * collection — the D1 is this oracle's, so no oracle column is needed and no other oracle's
+ * registry is ever visible.
+ *
+ * `digest` is the keyed HMAC over the canonical body — matching digests mean matching content,
+ * but the digest alone reveals nothing (spec §12.3). `normalizedText` is the near-text lane's
+ * haystack and the ONLY column carrying claim-derived text: erasable PII, nullable by design —
+ * wiping it degrades fuzzy recall for old rows without touching the exact-match lane.
+ * `finalVerdict` is denormalized when the engine's decision lands (workflows, never the producer)
+ * so the `countPrior` filter reads one table; NULL means still pending, which counts as blockable.
+ *
+ * Indexes: the composite PK already serves the (collection, digest) exact lookup (SQLite's
+ * autoindex covers a leading prefix); `cbd_recent` serves the near-text pool read (newest rows of
+ * a collection first — lib/facts/stock/unique-store.ts, where Postgres had a GIN trigram index);
+ * `cbd_claim` serves every read keyed on the claim — the workflows' `finalVerdict` UPDATE (every
+ * decided claim), the CID lane's join and the erase routes (`claim_id = ?` alone,
+ * hence claimId leading). The PK cannot: `digest` sits between collection and claim, so each of
+ * them walked every registry row of the collection, or of the table.
+ */
+export const claimBodyDigests = sqliteTable("claim_body_digests", {
+    collectionId: text().notNull(),
+    /** HMAC-SHA256 over the canonical body (spec §4.1) — the exact-match lane's key. */
+    digest: text().notNull(),
+    claimId: text().notNull(),
+    agentAddress: text(),
+    /** Near-text lane haystack; erasable PII — nullable by design (spec §12.3). */
+    normalizedText: text(),
+    /** Denormalized at decision time (registry token: approved · rejected · pending_review); NULL = pending, blockable. */
+    finalVerdict: text(),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+}, (t) => [
+    primaryKey({ columns: [t.collectionId, t.digest, t.claimId] }),
+    index("cbd_recent").on(t.collectionId, t.createdAt),
+    index("cbd_claim").on(t.claimId, t.collectionId),
+]);
+/**
+ * Attachment-CID registry (duplicate spec §9, §4 L2) — one row per (collection, cid, claim),
+ * same insert-self-first + retry-idempotent discipline as `claim_body_digests`. A CID seen on
+ * two different claims IS the same bytes (content addressing does the proving) — no fetch
+ * needed. `phash` is the perceptual dHash for the near-match lane (§4 L4): nullable because not
+ * every attachment decodes (non-image, oversized, undecodable — and every PDF here: the kit has
+ * no Browser Run binding, so PDFs are never rendered) and a missing hash only narrows recall,
+ * never blocks registration. `cac_recent` serves the bounded pHash pool read (newest first).
+ */
+export const claimAttachmentCids = sqliteTable("claim_attachment_cids", {
+    collectionId: text().notNull(),
+    cid: text().notNull(),
+    claimId: text().notNull(),
+    agentAddress: text(),
+    /** dHash64 hex (16 chars) of the decoded image; null = not hashable. */
+    phash: text(),
+    /**
+     * The ATTACHMENT's own media type — what `phash` was derived from, which decides how far
+     * apart two hashes may sit and still count (unique-score's §5 tiers): a rendered document is
+     * deterministic and moves a bit or two, a photo of the same scene moves much more. NULL only
+     * on a row written without one: scored with the looser image tiers.
+     */
+    mediaType: text(),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+}, (t) => [
+    primaryKey({ columns: [t.collectionId, t.cid, t.claimId] }),
+    index("cac_recent").on(t.collectionId, t.createdAt),
+]);
+/**
+ * Resolved connector answers, cached per claim while its evaluate step is still in flight — the
+ * crash-recovery twin of the engine's decided-once read: `GET /v1/decisions/:claimId` covers a
+ * crash AFTER the engine decided, this table covers a crash MID-produce, so a step retry re-runs
+ * only the connectors that never answered instead of re-buying every AI/ext call. Written
+ * fail-soft by the stock producer as each `ext`/`ai` fact resolves (lib/facts/fact-cache.ts);
+ * `unique`/`frequency` are NEVER cached — registry state and calendar windows must be fresh per
+ * attempt. The one exception is a `unique-judge` row: the same-event judge's `valid` verdict on ONE
+ * (claim, candidate) pair, `name` = the candidate claimId (stock/unique.ts `judgePairs`) — a
+ * question about two fixed bodies, so a retry need not pay for it again; the candidate SET is still
+ * read fresh. `kind` is a type-only enum on TEXT, so that value needed no migration. Keyed by the
+ * manifest's `rubricId` too: an answer is an answer to ONE work order, and a `#rub` re-anchored
+ * between two attempts (or the `RUBRIC_PIN_MISMATCH` rebuild, workflows/claim-ingest.ts) is a new
+ * one — same-named facts must run again, never come back from the old rubric's sources or
+ * instructions. Deleted (every rubric's rows) in the same `db.batch` as the claim's `decisions`
+ * row write and on terminal failure: decided or dead, the cache is gone — rows only ever outlive a
+ * crashed attempt.
+ */
+export const factCache = sqliteTable("fact_cache", {
+    claimId: text().notNull(),
+    /** The work order the row answered (the manifest's `rubricId`, canonical lowercase). */
+    rubricId: text().notNull(),
+    kind: text({ enum: ["ext", "ai", "unique-judge"] }).notNull(),
+    /**
+     * The `<name>` in `ext.<name>` / `ai.<name>` — the work-order key (lib/facts/expected.ts); for
+     * `unique-judge`, the candidate claimId.
+     */
+    name: text().notNull(),
+    /** The resolved fact (or judgement) verbatim — returned as-is on a retry's hit. */
+    fact: text({ mode: "json" }).$type().notNull(),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+}, (t) => [primaryKey({ columns: [t.claimId, t.rubricId, t.kind, t.name] })]);
+/**
+ * The side-effect ledger (the review-notification lane, lib/matrix/deliver.ts; the email notices,
+ * workflows/steps.ts + routes/v1/collections.ts). `dedupeKey` is
+ * the primary key AND the sent-once mutex: a step/route that re-enters finds a `sent` row and does
+ * zero HTTP/email. It is ALSO the review room's reuse index — a `sent` `review_room` row is the
+ * answer to "does this room already exist" for a `(collectionId, ownerDid)` pair. Kinds:
+ *
+ *   review_room:{collectionId}:{ownerDid}          ← the oracle-owned room, reused across every claim
+ *   review_request:{claimId}                       ← the sent v2 review-request Matrix event
+ *   review_fold:{claimId}                          ← the `m.replace` edit that completes it
+ *   notice_review_email:{claimId}:{resultDigest}   ← the review-request EMAIL twin (deliver.ts),
+ *                                                     independent of review_request so one lane's
+ *                                                     failure never blocks or hides the other's
+ *   notice_paused:{collectionId}                   ← the paused-collection email (steps.ts)
+ *   notice_resumed:{collectionId}                  ← its alternating twin (steps.ts, collections.ts)
+ *   review_room:{sourceId}                         ← an API source's review room (Go Prod §10.1), keyed by
+ *                                                     the source alone: one room per source on this oracle
+ *   rvi:{sourceId}:{mxid}                          ← a person invited to it (`review_invite`; the MXID in
+ *                                                     `targetUrl` too, so a removed member can still be kicked);
+ *                                                     keyed by MXID, not memberId, so a member removed and
+ *                                                     re-added is the same row; `dead` once kicked
+ *   rvm:{claimId}                                  ← the room's notice for one API claim (`review_notice`)
+ *   rv:{claimId}:{memberId|contact}                ← one recipient's review email for one API claim
+ *                                                     (`review_email`): `sending` once claimed, `pending` while
+ *                                                     held for the batch (lib/api-lane/reviewers.ts), then its
+ *                                                     email's outcome
+ *   rvw:{sourceId}                                 ← the source contact's 15-minute review-email window
+ *                                                     (`review_window`): `updatedAt` is its last email
+ *   rv3|rv14:{claimId}:{memberId|contact}          ← one recipient's 3-/14-day reminder (`review_reminder`)
+ *   notice_review_reminder:{claimId}:{3|14}        ← an API claim's unanswered-review reminder done (Go Prod
+ *                                                     §10.4) — what keeps the hourly pass off the claim
+ *   notice_review_expired:{claimId}                ← a paid API claim's review closed unanswered at its
+ *                                                     `answerBy`, announced (`review_expired` + webhook)
+ *   notice_balance_low:{sourceId}:{yyyy-mm-dd}     ← the `balance.low` email to the source's contact, once a
+ *                                                     day at most (§12.4; member-emails.ts) — the webhook is
+ *                                                     once per crossing, keyed by `balanceLowAt`
+ *   wh:{eventId}:{endpointId|claim}                ← one webhook event to one target (`kind: "webhook"`, §4.5)
+ *   inv:{memberId}:{tokenHash[0,16]}               ← an email invite (`member_invite`, member-emails §2); a
+ *                                                     re-invite mints a new token, so a new row
+ *   acc:{memberId}                                 ← "invitation accepted" to the inviter (`member_accepted`, §3)
+ *   grant:{memberId}:{delegationCid}               ← "access granted" to the member (`member_granted`, §4)
+ *
+ * `notice_paused`/`notice_resumed` alternate PER COLLECTION (not per reason, and not owner-pooled
+ * like eval-engine v1's billing notices — this kit has one `status` column and no shared
+ * subscription/payout accounts to group): a state is announced only when its own marker is not
+ * already the newer of the pair, so a step retry inside one pause re-sends nothing and a pause
+ * following a recovery is a fresh notice.
+ *
+ * `resultDigest` is captured ONLY on the `review_request` row, at send time — the PRE-fold digest
+ * "the frozen evaluation the reviewer's answers bind to" (events.ts). `deliverReviewFold` reads it
+ * back from HERE, never from `decisions.resultDigest`, which the fold has already overwritten with
+ * the NEW (post-fold) digest by the time the edit is built.
+ *
+ * Rows are mutable (attempts/lastError); nothing here ever influences a decision — delivery only,
+ * exactly like the engine's own `decisions.chainStatus` lane.
+ */
+export const matrixDeliveries = sqliteTable("matrix_deliveries", {
+    dedupeKey: text().primaryKey(),
+    // A TEXT column: the enum is type-only (SQLite, same note as watched_collections.pausedReason
+    // above), so adding a kind needs no migration — `db:generate` reports nothing.
+    kind: text({
+        enum: [
+            "review_room",
+            "review_request",
+            "review_fold",
+            "notice_paused",
+            "notice_resumed",
+            "notice_review_email",
+            "notice_review_reminder",
+            "notice_review_expired",
+            "review_invite",
+            "review_notice",
+            "review_email",
+            "review_reminder",
+            "review_window",
+            "member_invite",
+            "member_accepted",
+            "member_granted",
+            "notice_balance_low",
+            "notice_review_billing_expiring",
+            "notice_review_billing_cap",
+            "webhook",
+        ],
+    }).notNull(),
+    claimId: text(),
+    collectionId: text(),
+    /** The resolved room id — an alias resolved, or `createRoom`'s answer. */
+    roomId: text(),
+    /** The sent (or edited) event id. */
+    eventId: text(),
+    /** The `review_request` row's PRE-fold `resultDigest` — see the table header comment. */
+    resultDigest: text(),
+    /**
+     * `pending` and `dead` are the webhook lane's: queued before the first attempt (enqueue sets
+     * `nextAttemptAt = now`, so the retry cron's due read finds it even if the first inline attempt
+     * never ran), and out of attempts (8 over 24 h, Go Prod §4.5) — the dead-letter the portal
+     * shows and a redeliver re-queues. A `failed` webhook row with a `nextAttemptAt` is due for the
+     * retry cron. On the wire (`webhook.status`, the delivery log) `sent` reads `delivered`.
+     * `sending` is the review/member emails' claim (lib/api-lane/reviewers.ts `claimRows`): the
+     * row is written before the send so two callers never both send; a crash mid-send leaves it.
+     */
+    status: text({ enum: ["sent", "failed", "skipped", "pending", "dead", "sending"] })
+        .notNull()
+        .default("failed"),
+    attempts: integer().notNull().default(0),
+    lastError: text(),
+    // --- `kind: "webhook"` only (Go Prod §4.5, §6.1); null on every Matrix/email row. The row is
+    // `wh:<eventId>:<endpointId>` (or `wh:<eventId>:claim` for a per-claim `webhookUrl`) — one
+    // row per event per target, so a redeliver re-queues the same row instead of adding one. ---
+    sourceId: text(),
+    /** The `webhook_endpoints` row, or null for the claim's own `webhookUrl`. */
+    endpointId: text(),
+    /** Where it is posted — copied at enqueue, so an endpoint edit never retargets a sent event. */
+    targetUrl: text(),
+    /** The App. B event type (`claim.decided`, …). */
+    eventType: text(),
+    /**
+     * The signed envelope's JSON, frozen at enqueue so every retry posts the same bytes the
+     * `Oracle-Event-Id` promises. Carries the record (metadata included — personal data), so the
+     * oracle never deletes the row on its own (owner, 2026-10-11); erasing a claim nulls `payload` and
+     * `targetUrl` on its rows too.
+     */
+    payload: text({ mode: "json" }).$type(),
+    /** When the retry cron may attempt it next; null once delivered or dead. */
+    nextAttemptAt: integer({ mode: "timestamp_ms" }),
+    /** The receiver's last HTTP status (null on a network failure) — the delivery log's column. */
+    lastStatusCode: integer(),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+    updatedAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date())
+        .$onUpdate(() => new Date()),
+}, (t) => [
+    index("matrix_deliveries_claim_idx").on(t.claimId),
+    // The webhook-retry cron's read: due rows of one kind, oldest due first.
+    index("matrix_deliveries_due_idx").on(t.kind, t.status, t.nextAttemptAt),
+    // The delivery log (`GET /v1/api/webhooks/deliveries`): one source's rows, newest first.
+    index("matrix_deliveries_source_created_idx").on(t.sourceId, t.createdAt),
+    // A kind's rows oldest first (the review batch flush, reviewers.ts) without a full scan.
+    index("matrix_deliveries_kind_created_idx").on(t.kind, t.createdAt),
+]);
+// ------------------------------------------------------------------------------------------------
+// The Decision API lane (Go Prod §3, §6.1). Every table below is written only when `API_LANE` is on;
+// with it off they exist empty. An API claim reuses `claim_ingests` / `decisions` / the registries
+// under the scope id `api:<sourceId>:<protocolDid>` in their `collectionId`, so nothing above changes
+// meaning. `sourceId` scopes every read: across sources a row does not exist (404, never 403, §14).
+// ------------------------------------------------------------------------------------------------
+/**
+ * One organisation's account with this oracle (Go Prod §3.2) — the API lane's `watched_collections`.
+ * `ownerDid` is the IXO account whose deed pays; members and keys hang off `sourceId`.
+ */
+export const apiSources = sqliteTable("api_sources", {
+    /** `src_<ULID>`. */
+    sourceId: text().primaryKey(),
+    name: text().notNull(),
+    /** The paying IXO account (`did:ixo`) — the root of its members' payment delegations. */
+    ownerDid: text().notNull(),
+    /**
+     * Protocol DIDs this source may submit against (§17). EMPTY = NONE — unlike the chain lane's
+     * `supportedProtocols`, where empty means "no restriction": a source can only ever be narrowed to
+     * nothing, never opened to everything by an empty list. Sign-up copies the oracle's catalogue.
+     */
+    allowedProtocols: text({ mode: "json" }).$type().notNull().default([]),
+    /**
+     * UNUSED since contracts v1.1: there are no per-source prices — every source pays the oracle's
+     * published price (payments spec §3.1), and a partner who should not pay gets `billingMode:
+     * none`. Kept only because dropping a column is a table rebuild in SQLite.
+     */
+    priceOverrides: text({ mode: "json" }).$type(),
+    /**
+     * How the source pays (§3.2): `x402` — an outside customer pays per decision (§11) — or `none` —
+     * the operator's own organisation or an unbilled partner: no 402, no `api_charges` row. Set by the
+     * oracle's operator only, never by a member: it is a commercial term.
+     */
+    billingMode: text({ enum: ["x402", "none"] })
+        .notNull()
+        .default("x402"),
+    /** The `balance.low` floor (§12.4), whole cents; null = no alert. */
+    refillFloorCents: integer(),
+    /**
+     * When the balance watch last saw the balance cross BELOW the floor; cleared when it recovers.
+     * The watch runs every 15 min — this is what keeps it to one `balance.low` per crossing.
+     */
+    balanceLowAt: integer({ mode: "timestamp_ms" }),
+    /** Default target for claims that name no `webhookUrl` and no endpoint subscribes. */
+    webhookUrl: text(),
+    /**
+     * The source's ONE signing secret for deliveries to a claim's own `webhookUrl` and to the default
+     * `webhookUrl` above (§4.5) — encrypted exactly like `webhook_endpoints.secretCiphertext`
+     * (`v1:<ciphertext>`), created with the source and shown once. Null for a source created before
+     * contracts v1.1: those deliveries then stay `dead` ("no signing secret") until an owner rotates.
+     */
+    webhookSecretCiphertext: text(),
+    /** The secret a rotation replaced, still signing beside the new one for 24 h — as an endpoint's. */
+    previousWebhookSecretCiphertext: text(),
+    previousWebhookSecretExpiresAt: integer({ mode: "timestamp_ms" }),
+    /**
+     * D10: a source starts `pending-link` and turns `active` when the company sync reads its
+     * organisation's link from the engine; a link for another entity (or the engine's `disputed`)
+     * makes it `disputed`. Neither takes claims, keys, invites or webhooks (`409
+     * SOURCE_PENDING_LINK` / `SOURCE_DISPUTED`). `paused` answers new submits `503 SOURCE_PAUSED`
+     * (App. A); in-flight claims finish. Reasons (paused only) as App. A's `details.reason`:
+     * `rubric-unusable`, `engine-credits`, `payments-disabled`, and `operator` for a hand pause from
+     * the operator view. TEXT with a type-only enum (no migration), like
+     * `watched_collections.pausedReason`.
+     */
+    status: text({ enum: ["pending-link", "active", "paused", "disputed"] })
+        .notNull()
+        .default("active"),
+    /**
+     * The first time the company sync made the source `active`; set once, never cleared (a later
+     * `disputed` keeps it). Null ⇒ the source was never active, so its id has never left its
+     * organisation's controllers: logs hash it (`sourceLogId`) and only their listing shows it (never
+     * the operator's). On the wire as `Source.activatedAt` (1.17.0).
+     */
+    activatedAt: integer({ mode: "timestamp_ms" }),
+    pausedReason: text({
+        enum: ["rubric-unusable", "engine-credits", "payments-disabled", "operator"],
+    }),
+    contactEmail: text(),
+    /** Operator-only free text (the operator view); never shown to the source. */
+    notes: text(),
+    /**
+     * The organisation (its on-chain entity) this source belongs to (company authority D1, D10): set
+     * at insert by the controller who adds the oracle, never changed. Its CURRENT controllers are the
+     * source's roots (`lib/api-lane/company.ts` `sourceRoots`). Nullable in SQL only — a table rebuild
+     * to say NOT NULL is not worth its risk: every insert sets it, migration 0017 deleted the rows
+     * made before D10, and `sourceView` refuses a null.
+     */
+    companyEntityDid: text(),
+    /**
+     * A COPY of the controller-signed `SourceCompanyLink` JWS the engine holds (owner: the engine is
+     * the link's single home — the Console PUTs it there, this oracle reads it with `company/read` and
+     * never verifies or forwards it). Kept verbatim so a reader can check what the mirror came from.
+     */
+    companyLink: text(),
+    /** The engine's link `issuedAt` as last read — a sync that reads an older one is stale. */
+    companyLinkIssuedAt: integer({ mode: "timestamp_ms" }),
+    /** A copy of the link's `credentialSubject.payeeField` (D3), for reads; the JWS is the truth. */
+    payeeField: text(),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+    updatedAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date())
+        .$onUpdate(() => new Date()),
+});
+/**
+ * API keys (Go Prod §3.2, §3.3): `eo_live_<prefix>_<secret>` / `eo_test_…`. The prefix is the lookup
+ * (PK), the sha256 of the whole key the proof — the key itself is shown once and never stored.
+ * Revoked rows stay a year for the audit trail. Rotation (§3.3) sets the old key's `revokedAt` in
+ * the FUTURE (up to 30 days), so auth admits a key while `revokedAt IS NULL OR revokedAt > now`.
+ */
+export const apiKeys = sqliteTable("api_keys", {
+    /** The 8-char prefix — unique, the lookup, and what the masked form shows. */
+    prefix: text().primaryKey(),
+    /** Lowercase hex sha256 of the full key string. */
+    keyHash: text().notNull(),
+    sourceId: text().notNull(),
+    /** A label for the Keys page. */
+    name: text(),
+    /** `eo_live_` (mainnet) or `eo_test_` (the testnet sandbox, §3.2). */
+    environment: text({ enum: ["live", "test"] }).notNull(),
+    scopes: text({ mode: "json" })
+        .$type()
+        .notNull(),
+    /** Daily spend cap, whole cents (§4.1 `402 SPEND_CAP`); null = no cap beyond the delegation's. */
+    maxSpendCentsPerDay: integer(),
+    /** Who created it (a member's `did:ixo`, or the operator). */
+    createdBy: text(),
+    lastUsedAt: integer({ mode: "timestamp_ms" }),
+    revokedAt: integer({ mode: "timestamp_ms" }),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+}, (t) => [index("api_keys_source_idx").on(t.sourceId)]);
+/**
+ * People on a source (Go Prod §3.2): an IXO account, a role, and the `did:key` their review answers
+ * are signed with (§10). Invited by email, bound to a DID on accept — so `did` is null until then.
+ * One DID once per source (the unique index; SQLite admits many NULLs). Removed on request.
+ *
+ * A role is a UCAN delegation (§3.4, contracts v1.1): the owner signs, in their browser, a grant of
+ * the role's preset (`ROLE_CAPABILITIES`) over the source's resource to the member's DID, and the
+ * row keeps it (`delegation` + `delegationCid`) with what it says (`nbProtocols`, `expiresAt`) so
+ * a check needs no CAR parse. `role` is the preset's label, nothing more. The owner row is the root
+ * and carries no grant. A member without a stored grant can call nothing. Revoking stamps
+ * `revokedAt` AND lists the CID in `api_revocations`; a role change is a revoke plus a new grant.
+ */
+export const apiMembers = sqliteTable("api_members", {
+    /** `mem_<ULID>`. */
+    memberId: text().primaryKey(),
+    sourceId: text().notNull(),
+    /** The member's `did:ixo` (AuthHub); null while the invite is open. */
+    did: text(),
+    email: text(),
+    role: text({ enum: ["owner", "developer", "reviewer", "viewer", "submitter"] }).notNull(),
+    /** The owner's signed grant, base64 of the delegation CAR; null until uploaded (and for the owner). */
+    delegation: text(),
+    /** The grant's CID — what a revocation lists and what `api_revocations` is checked against. */
+    delegationCid: text(),
+    /** The grant's `nb.protocols`: the protocols its `claims/*` are narrowed to; null = all. */
+    nbProtocols: text({ mode: "json" }).$type(),
+    /** The grant's expiry, in ms — a UCAN `exp` is in SECONDS, so `exp * 1000`; null = none. */
+    expiresAt: integer({ mode: "timestamp_ms" }),
+    revokedAt: integer({ mode: "timestamp_ms" }),
+    /**
+     * Lowercase hex sha256 of an email invite's one-time `inviteToken` (shown once, never stored);
+     * cleared on accept. Unique, so accept is one indexed lookup.
+     */
+    inviteTokenHash: text(),
+    /**
+     * When the email invite (`inviteTokenHash`) stops working — 7 days after it was sent (§3.4
+     * step 2); null for a member invited by DID, and once accepted.
+     */
+    inviteExpiresAt: integer({ mode: "timestamp_ms" }),
+    /** The Ed25519 `did:key` generated in their browser; a review answer's issuer must be one of these. */
+    reviewerDid: text(),
+    /**
+     * The member's own link to `reviewerDid` (company authority D2, F1): base64 CAR of the member
+     * did:ixo → reviewer did:key `claims/review` delegation, signed by the member — the middle of the
+     * chain the engine walks to name the member on the fold's receipt. Null until signed.
+     */
+    reviewerDelegation: text(),
+    /** That delegation's expiry, in ms (`exp * 1000`); null = none or none uploaded. */
+    reviewerDelegationExpiresAt: integer({ mode: "timestamp_ms" }),
+    /** The member's own switch for review emails (§10.1); Matrix follows the room's mute instead. */
+    notifyReviews: integer({ mode: "boolean" }).notNull().default(true),
+    /**
+     * When this member was last sent a review email for this source — the 15-minute window
+     * (§10.1, member-emails §6) opens here, and claims arriving inside it are held for one batch
+     * (lib/api-lane/reviewers.ts). Claimed by a conditional UPDATE, so two racing notify steps
+     * never both send.
+     */
+    reviewEmailAt: integer({ mode: "timestamp_ms" }),
+    invitedBy: text(),
+    invitedAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+    acceptedAt: integer({ mode: "timestamp_ms" }),
+}, (t) => [
+    uniqueIndex("api_members_source_did_idx").on(t.sourceId, t.did),
+    // The console's role lookup at sign-in: every source a DID belongs to.
+    index("api_members_did_idx").on(t.did),
+    // The review gate (§10.2): is this `did:key` a reviewer key of a member of THIS source? One
+    // key per member — registering from a second browser replaces it.
+    uniqueIndex("api_members_source_reviewer_idx").on(t.sourceId, t.reviewerDid),
+    uniqueIndex("api_members_invite_token_idx").on(t.inviteTokenHash),
+]);
+/**
+ * A source's revocation list (§3.4): the CIDs of member grants the owner has withdrawn. Revoking
+ * adds the CID here and it is effective at once — every grant check reads this list, so a copy of
+ * the CAR still held by a browser (or re-uploaded) proves nothing. A grant REPLACED by a new one (a
+ * role change is a revoke plus a new grant) lands here too. Rows are never deleted: a CID is
+ * revoked for life. The PK is the lookup and the added-once mutex.
+ */
+export const apiRevocations = sqliteTable("api_revocations", {
+    sourceId: text().notNull(),
+    cid: text().notNull(),
+    /** The member's `did:ixo` who revoked it, or the operator. */
+    revokedBy: text(),
+    revokedAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+}, (t) => [primaryKey({ columns: [t.sourceId, t.cid] })]);
+/**
+ * An API claim's body and envelope (Go Prod §6.1, §6.2) — the D1 store the `api` `ClaimSource` pulls
+ * from. `body` is the canonical JSON of the answers; `bodyDigest` its sha256, checked on every pull
+ * (a mismatch fails closed, never a retry). Erasure nulls `body` (and `attachments`, `submitter`,
+ * `metadata`, `webhookUrl`, `content` — the personal data of §6.3), the claim's webhook rows' `payload` and
+ * `targetUrl`, deletes its `api_uploads` objects, and stamps `bodyErasedAt`; the row, the digests
+ * and the decision survive. Written in the SAME `db.batch` as the `claim_ingests` row and the
+ * `api_charges` row at accept (§4.6).
+ */
+export const apiClaims = sqliteTable("api_claims", {
+    /** `apc_…` — also the `claim_ingests` / `decisions` key. */
+    claimId: text().primaryKey(),
+    sourceId: text().notNull(),
+    protocolDid: text().notNull(),
+    /** Canonical JSON of `answers`; null once erased. */
+    body: text({ mode: "json" }).$type(),
+    /** sha256 hex of the canonical body — the pull's integrity check; survives erasure. */
+    bodyDigest: text().notNull(),
+    /** The request's attachment descriptors (question, name, mediaType, url, cid) — never bytes. */
+    attachments: text({ mode: "json" }).$type(),
+    /** The org's end-user id, for display; personal data, so erased. */
+    submitter: text(),
+    /**
+     * HMAC-SHA256 (`UNIQUE_HMAC_KEY`) of `sourceId|submitter` — the frequency counter's key (§9),
+     * and why it is not `submitter` itself: it SURVIVES erasure, so a claim erased early still
+     * counts in its window. Null without a submitter ⇒ the fact is `unresolved`.
+     */
+    submitterDigest: text(),
+    /** Echoed on every webhook and GET, never evaluated (≤ 4 KB). */
+    metadata: text({ mode: "json" }).$type(),
+    idempotencyKey: text(),
+    /**
+     * sha256 of the whole canonical request — what a repeat of the same `Idempotency-Key` is
+     * compared against (`409 IDEMPOTENCY_MISMATCH`, §4.1). Null without a key.
+     */
+    requestDigest: text(),
+    webhookUrl: text(),
+    /**
+     * How the claim came in when not by an API key or the console: `oauth:<client_id>` for an AI
+     * app connected to `/v1/mcp` over OAuth (S7). Stamped on its `accepted` event; null otherwise.
+     */
+    via: text(),
+    /** The x402 offer to pay IF approved (§11.10). UNUSED at GA (contracts v1.1: no decision-to-pay,
+     *  a submit carries no `payment`); always null, kept so the feature can return without a migration. */
+    payment: text({ mode: "json" }).$type(),
+    receivedAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+    /** When the organisation erased the body (`DELETE /v1/api/claims/:claimId/body`) — never on a clock. */
+    bodyErasedAt: integer({ mode: "timestamp_ms" }),
+    /**
+     * `contentDigest(content)` (lib/hash.ts, `sha256:<hex>`) — the claim's content id, which the
+     * receipt carries and the SDK recomputes from what the app sent (company authority D3, A8).
+     * Survives erasure, like `bodyDigest`. Null for a claim accepted before contracts v1.7.
+     */
+    contentDigest: text(),
+    /**
+     * The claim CONTENT exactly as digested (`ApiClaimContent`): the submit body minus transport,
+     * with the resolved `protocolDid`, the caller's explicit `submitter` only and the attachments
+     * as SENT (before media-type detection rewrites `attachments` above). Kept apart from `body` so
+     * the engine can recompute the digest; it holds the answers, so it is erased with them.
+     */
+    content: text({ mode: "json" }).$type(),
+    /** Who SENT the claim, set server-side from the caller, never from the content: the OAuth
+     *  user's DID (hosted MCP); null for an API key or a console submit, and before contracts v1.7.
+     *  Not who the claim is about — that is `submitter`. */
+    submittedBy: text(),
+    /** WHICH AI app sent it (contracts v1.12.0 `submittedVia.name`): the OAuth client's registered
+     *  name (`caller.clientName`, the AuthHub token's `client_name`), trimmed, ≤ 100 chars; null
+     *  for an API key, a console submit and a chain claim. Self-declared at dynamic client
+     *  registration, so a display hint for the console — never an authorisation input. */
+    submittedVia: text(),
+    /** The token's `verified` at submit (`submittedVia.verified`): AuthHub saw only Claude's or
+     *  ChatGPT's own callback registered, so the token can only be theirs. Null iff
+     *  `submittedVia` is. */
+    submittedViaVerified: integer({ mode: "boolean" }),
+}, (t) => [
+    // The list route's keyset (`GET /v1/api/claims`): one source, newest first.
+    index("api_claims_source_received_idx").on(t.sourceId, t.receivedAt, t.claimId),
+    // The frequency counter (§9): one D1 count per (source, protocol, submitter, window).
+    index("api_claims_frequency_idx").on(t.sourceId, t.protocolDid, t.submitterDigest, t.receivedAt),
+]);
+/**
+ * The oracle's pointer to each claim's payment (Go Prod §6.1, §11.3; payments spec §4, §13.4). The
+ * facilitator's reservations and settlements are the financial record; this row is for the timeline,
+ * support, the reconcile cron and the per-key cap. One row per accepted claim — `claimId` is the
+ * charged-once mutex. No refunds (nothing moves without a receipt, payments spec §0 rule 1).
+ *
+ * Lifecycle (contracts v1.3, standard x402): the row lands `reserved` in the accept batch, AFTER
+ * `/verify` reserved the price (the claim starts only then); after the decision row, `/settle` with
+ * the engine's receipt answers `settlement_pending` ⇒ `settled` (the receipt is accepted, the
+ * minute's transfer has not paid it yet) or `success` ⇒ `paid` with `txHash`; `reservation_released`
+ * ⇒ `released` (24 h without a receipt: nothing moved); any other refusal ⇒ `failed`, never retried.
+ * The reconcile re-settles `reserved`/`settled` rows of decided claims with the identical body until
+ * `paid`, and marks `released` a reservation past the facilitator's 24 h with no receipt — which a
+ * late settle the facilitator still accepts overwrites (`reservation_expired_late`). `settlementId` is the facilitator's, one per offer, so a batch's claims share it; `amount`
+ * is always THIS claim's price.
+ */
+export const apiCharges = sqliteTable("api_charges", {
+    claimId: text().primaryKey(),
+    sourceId: text().notNull(),
+    /** The facilitator's settlement id (`org.udid.receipt@1` `settlementId`, 64 hex); null until settled. */
+    settlementId: text(),
+    /** Base units of `asset`, as a string (`"1200000"` = 1.20 PAY). */
+    amount: text().notNull(),
+    asset: text().notNull().default("upay"),
+    /** The facilitator offer (the 402's single-use nonce). */
+    offerId: text(),
+    /** The account at the root of the payment delegation — who was charged. */
+    payerDid: text(),
+    /** The API key that submitted — what the per-key daily cap (`402 SPEND_CAP`, §4.1) sums over. */
+    keyPrefix: text(),
+    /**
+     * `oauth:<grant id>` for a claim an AI app submitted over OAuth (S7) — what the per-grant daily
+     * cap sums over, as `keyPrefix` is for a key; null for a key or a console submit.
+     */
+    via: text(),
+    /** `amount` in whole USD cents (1 PAY = 1 USD), so the cap sums integers, never casts upay strings. */
+    amountCents: integer().notNull(),
+    /** TEXT with a type-only enum: adding a value needs no migration. */
+    status: text({
+        enum: [
+            // A chain claim's offer registered, its `/verify` not answered yet (review-billing.ts): a
+            // retry re-verifies the stored header, never re-offers. Never on an API claim.
+            "offered",
+            "reserved",
+            "settled",
+            "paid",
+            "released",
+            "failed",
+            // Card only (PAY's transfer is final): the facilitator's refund, read there (refund.ts).
+            "refunded",
+            "partially_refunded",
+        ],
+    })
+        .notNull()
+        .default("reserved"),
+    /** The transfer that paid it (`/settle`'s `transaction`, a chain tx hash) — only ever real. */
+    txHash: text(),
+    /** The facilitator's last `/settle` answer, verbatim: a sync 200's `PAYMENT-RESPONSE`. A
+     *  pre-v1.3 hold keeps its old id here instead (`{ legacyChargeId }`). */
+    settleResult: text({ mode: "json" }).$type(),
+    /** The verified `PAYMENT-SIGNATURE` every `/settle` of this claim is built from (identical on
+     *  every retry), SEALED (`v1:`, payments/header-seal.ts — it embeds the payer's reusable
+     *  payment delegation); KV holds a second copy. Null for rows written before contracts v1.3;
+     *  in the clear on rows written before 2026-10-14, until the housekeeping sweep seals them. */
+    paymentHeader: text(),
+    /** What the header pays with (`ixo-pay` | `stripe-manual-capture` | `exact`), in the clear so
+     *  a claim read never decrypts. Null on rows the sweep has not reached (read off a clear header). */
+    scheme: text({ enum: ["ixo-pay", "stripe-manual-capture", "exact"] }),
+    /**
+     * Per-review checker billing: `chain` for a CHAIN claim's charge (the claim id is the chain's,
+     * `collectionId` its collection) — the two fields the facilitator keys the reservation by
+     * besides the claim (x402-ixo-pay 0.7.0). Null = an API decision.
+     */
+    lane: text({ enum: ["chain"] }),
+    collectionId: text(),
+    /**
+     * When the facilitator will release the reservation, once a `pending_review` claim's hold was
+     * extended for its human review (`POST /v1/reservations/extend`, payments/extend.ts); null =
+     * the default 24 h from `createdAt`. What the reconcile's expiry arm and a review's deadline read.
+     */
+    reservationExpiresAt: integer({ mode: "timestamp_ms" }),
+    /**
+     * A card payment's refund, as the facilitator reports it (`GET /v1/card/refunds/:claimId`,
+     * payments/refund.ts) — never on the console's word. Null for PAY and an unrefunded card.
+     */
+    refundedAt: integer({ mode: "timestamp_ms" }),
+    refundId: text(),
+    refundedAmountCents: integer(),
+    /** When the reconcile last asked the facilitator about this card charge's refund (its turn). */
+    refundCheckedAt: integer({ mode: "timestamp_ms" }),
+    error: text(),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+    updatedAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date())
+        .$onUpdate(() => new Date()),
+}, (t) => [
+    index("api_charges_settlement_idx").on(t.settlementId),
+    // The reconcile: open rows by status, the least recently tried first.
+    index("api_charges_status_updated_idx").on(t.status, t.updatedAt),
+    // The Spend page: one source's charges by day.
+    index("api_charges_source_created_idx").on(t.sourceId, t.createdAt),
+    // The per-key daily cap: today's charges of one key.
+    index("api_charges_key_created_idx").on(t.keyPrefix, t.createdAt),
+    // The per-grant daily cap (S7): today's charges of one OAuth grant.
+    index("api_charges_via_created_idx").on(t.via, t.createdAt),
+    // The daily reconciliation (one day across every source) and the retention trim.
+    index("api_charges_created_idx").on(t.createdAt),
+]);
+/**
+ * A source's standing review-billing delegation (per-review checker billing,
+ * active by IXO's plan for the oracle; payments/review-billing.ts): the x402-ixo-pay payment delegation its
+ * organisation's chain OWNER signed — one `billing/pay` to the facilitator, bound to this oracle
+ * alone (`nb.oracles`) — that pays for every chain claim of the organisation's collections. One
+ * row per source, and one source per organisation holding a live one (the PUT route enforces it).
+ *
+ * `delegationCiphertext` is a bearer credential: sealed (`v1:`, webhook-crypto.ts), never logged,
+ * never returned, never a step result. `spentUpay` is this oracle's mirror of what the facilitator
+ * counts against the delegation's `maxAmount` (it exposes no read): raised by ONE conditional
+ * statement per reservation (`spentUpay + price ≤ capUpay`), given back only when `/verify` reserved
+ * nothing — a lapsed reservation keeps counting, as the facilitator's does. With `nb.oracles` =
+ * [this oracle] nobody else can spend the CID, so the mirror is exact. A new CID starts at 0, as
+ * the facilitator's per-CID count does. `capUpay` is `maxAmount` capped to a safe integer (the
+ * comparison is SQL), `maxAmount` the exact string. Deleted with the source, and 30 days past
+ * `expiresAt` by the housekeeping sweep.
+ */
+export const reviewBillingDelegations = sqliteTable("review_billing_delegations", {
+    sourceId: text().primaryKey(),
+    /** The delegation's issuer — the organisation's chain owner when stored; who pays. */
+    payerDid: text().notNull(),
+    delegationCid: text().notNull(),
+    /** `nb.maxAmount`, upay base units, exact. */
+    maxAmount: text().notNull(),
+    capUpay: integer().notNull(),
+    spentUpay: integer().notNull().default(0),
+    expiresAt: integer({ mode: "timestamp_ms" }).notNull(),
+    notBefore: integer({ mode: "timestamp_ms" }),
+    delegationCiphertext: text().notNull(),
+    /** The member who stored it (`keys/manage` or a controller) — not necessarily the payer. */
+    createdBy: text().notNull(),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+    updatedAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date())
+        .$onUpdate(() => new Date()),
+}, (t) => [
+    // The expiry reminders and the housekeeping sweep: rows by expiry.
+    index("review_billing_delegations_expires_idx").on(t.expiresAt),
+]);
+/**
+ * The per-claim timeline (`GET /v1/api/claims/:claimId/events`, Go Prod §4.2): accepted, paid, facts
+ * produced (names and durations, NEVER values), decided, webhook attempts, review answered, folded,
+ * erased. Append-only, one statement per event; source-level events carry a null `claimId`. Kept a
+ * year (the retention cron trims). The claim index is not source-scoped: a timeline read proves the
+ * claim is the caller's through `api_claims` first (404 otherwise, §14).
+ */
+export const apiEvents = sqliteTable("api_events", {
+    /** `evt_<ULID>` — sortable, so the timeline orders by id. */
+    eventId: text().primaryKey(),
+    sourceId: text().notNull(),
+    claimId: text(),
+    type: text().notNull(),
+    /** Small, log-safe detail: fact names + durations, a status code, the engine's issues. Never an answer. */
+    data: text({ mode: "json" }).$type(),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+}, (t) => [
+    index("api_events_claim_idx").on(t.claimId, t.eventId),
+    index("api_events_source_created_idx").on(t.sourceId, t.createdAt),
+    index("api_events_created_idx").on(t.createdAt),
+]);
+/** Every portal, CLI and operator action on a source — who, what, when (Go Prod §6.1; kept 2 years). */
+export const apiAudit = sqliteTable("api_audit", {
+    /** `aud_<ULID>`. */
+    auditId: text().primaryKey(),
+    /** Null for an operator action not tied to one source. */
+    sourceId: text(),
+    /** Who acted — a member or operator DID, or the API key's prefix. */
+    actor: text().notNull(),
+    /** What `actor` is, so the audit log can show it without guessing from the string. */
+    /**
+     * `system` is the oracle acting on its own schedule (a cron); its `actor` is then
+     * `system:<job>`, e.g. `system:link-recheck`. `oauth` is a user acting through an AI app over
+     * OAuth (S7). TEXT with a type-only enum: a new kind is no migration.
+     */
+    actorKind: text({ enum: ["member", "key", "operator", "system", "oauth"] }).notNull(),
+    /**
+     * For `actorKind: oauth` (S7) — the user's `did:ixo` is `actor`, and these name the AI app
+     * acting for them, as AuthHub registered it. Null for every other kind.
+     */
+    clientId: text(),
+    clientName: text(),
+    /** `key.created`, `key.revoked`, `member.invited`, `claim.erased`, `source.paused`, … */
+    action: text().notNull(),
+    /** What it acted on (a key prefix, a member id, a claim id). */
+    target: text(),
+    details: text({ mode: "json" }).$type(),
+    requestId: text(),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+}, (t) => [
+    index("api_audit_source_created_idx").on(t.sourceId, t.createdAt),
+    index("api_audit_created_idx").on(t.createdAt),
+]);
+/**
+ * A source's webhook endpoints (Go Prod §4.5). The signing secret is stored ENCRYPTED with the
+ * deployment's `WEBHOOK_ENCRYPTION_KEY` (§6.1) — it must be recoverable to sign, so a hash will not
+ * do. `events` empty = every event. Deliveries are `matrix_deliveries` rows of `kind: "webhook"`.
+ */
+export const webhookEndpoints = sqliteTable("webhook_endpoints", {
+    /** `whe_<ULID>`. */
+    endpointId: text().primaryKey(),
+    sourceId: text().notNull(),
+    url: text().notNull(),
+    /**
+     * The HMAC secret, encrypted at rest; returned in clear once, on create or rotate. Prefixed
+     * with the key version (`v1:<ciphertext>`) so `WEBHOOK_ENCRYPTION_KEY` can be rotated (§14's
+     * compromise runbook) by re-encrypting row by row.
+     */
+    secretCiphertext: text().notNull(),
+    /**
+     * The secret a rotation replaced, still signing beside the new one until
+     * `previousSecretExpiresAt` (24 h) — the signature header then carries one `v1=` per live
+     * secret, so a receiver can swap without dropping events.
+     */
+    previousSecretCiphertext: text(),
+    previousSecretExpiresAt: integer({ mode: "timestamp_ms" }),
+    events: text({ mode: "json" }).$type().notNull().default([]),
+    status: text({ enum: ["active", "disabled"] })
+        .notNull()
+        .default("active"),
+    description: text(),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+    updatedAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date())
+        .$onUpdate(() => new Date()),
+}, (t) => [index("webhook_endpoints_source_idx").on(t.sourceId)]);
+/**
+ * The idempotency store for every POST/PUT that is not a claim submit (Go Prod §4.1): same key +
+ * same request ⇒ the stored answer for 24 h; same key + a different request ⇒ `409
+ * IDEMPOTENCY_MISMATCH`. The INSERT with `onConflictDoNothing` is the in-flight mutex (`status:
+ * in_flight` until the answer lands). A claim submit does not use it: its `claimId` is derived from
+ * the key, so the `claim_ingests` PK is the guard and `api_claims.requestDigest` the mismatch check
+ * — and a repeat answers the claim's CURRENT state, not a stored response (§4.6).
+ *
+ * An `in_flight` row older than 60 s is a request that died: the next attempt reclaims it with one
+ * conditional upsert (`onConflictDoUpdate … where status = 'in_flight' and created_at < now - 60s`),
+ * so a crash never locks a key for the day. A response carrying a one-time secret (a new API key,
+ * a webhook secret) is stored WITHOUT it — the secret field replaced by null — since keys live only
+ * as hashes and secrets only encrypted (§3.2, §6.1); the replay says so, and the caller rotates.
+ */
+export const apiIdempotency = sqliteTable("api_idempotency", {
+    sourceId: text().notNull(),
+    idempotencyKey: text().notNull(),
+    /** sha256 of method + path + canonical body. */
+    requestDigest: text().notNull(),
+    status: text({ enum: ["in_flight", "done"] })
+        .notNull()
+        .default("in_flight"),
+    responseStatus: integer(),
+    responseBody: text({ mode: "json" }).$type(),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+    /** createdAt + 24 h; the retention cron deletes past it. */
+    expiresAt: integer({ mode: "timestamp_ms" }).notNull(),
+}, (t) => [
+    primaryKey({ columns: [t.sourceId, t.idempotencyKey] }),
+    index("api_idempotency_expires_idx").on(t.expiresAt),
+]);
+/**
+ * Files uploaded through `PUT /v1/api/uploads` (Go Prod §6.2), and the export bundles: the R2
+ * object's pointer, so an erase or the housekeeping sweep can find every object without reading
+ * erasable claim columns. `claimId` is bound when a submit references the upload, and the claim's
+ * erase deletes it. `deleteAt` is set only by an organisation's own action — an export bundle's one
+ * day, a deleted source's files — and the hourly sweep then deletes the object and the row; null =
+ * kept (the oracle never deletes an organisation's files on its own).
+ */
+export const apiUploads = sqliteTable("api_uploads", {
+    /** `upl_<ULID>`. */
+    uploadId: text().primaryKey(),
+    sourceId: text().notNull(),
+    /** `uploads/<sourceId>/<ULID>` in `API_UPLOADS`. */
+    r2Key: text().notNull(),
+    cid: text().notNull(),
+    mediaType: text().notNull(),
+    size: integer().notNull(),
+    claimId: text(),
+    deleteAt: integer({ mode: "timestamp_ms" }),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+}, (t) => [
+    index("api_uploads_delete_idx").on(t.deleteAt),
+    index("api_uploads_claim_idx").on(t.claimId),
+]);
+/**
+ * On-chain collections an organisation (a source) has linked, so its claim reads include that
+ * collection's CHAIN claims (Go Prod S3 M6). Linked by a console member who is, ON CHAIN, the
+ * collection entity's owner (company authority D9); the hourly re-check
+ * (`lib/api-lane/linked.ts`) drops a link whose linker no longer owns it — the link
+ * rides on that one member's standing, never the source's. Billing for these claims stays the
+ * collection owner's on-chain evaluation payment: nothing is charged at the oracle.
+ *
+ * The same collection may be linked to several sources (PK `(sourceId, collectionId)`); the
+ * `collectionId` index serves "which sources see this collection". `checkedAt` rotates the
+ * re-check: least recently checked first, every link each hour up to a hard cap. `verifiedAt` is
+ * the last check that CONFIRMED the linker's standing — a record for operators, never a read
+ * filter: a link is shown while the row exists, and only the re-check's POSITIVE finding deletes it
+ * (lib/api-lane/linked.ts header). An unreadable chain or engine keeps it.
+ */
+export const apiSourceCollections = sqliteTable("api_source_collections", {
+    sourceId: text().notNull(),
+    collectionId: text().notNull(),
+    /** The collection's protocol, read off the chain at link time. */
+    protocolDid: text().notNull(),
+    /** The member's `did:ixo` — whose standing the re-check verifies. */
+    linkedBy: text().notNull(),
+    linkedAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+    checkedAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+    /** The last check that confirmed the linker's standing (the link itself is the first). */
+    verifiedAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+    /**
+     * Consecutive re-checks that found no such collection on chain. One is not enough to unlink —
+     * an indexer that lags or re-syncs answers "not found" for a while — so the link goes on the
+     * second in a row; any confirmed check resets it.
+     */
+    missCount: integer().notNull().default(0),
+}, (t) => [
+    primaryKey({ columns: [t.sourceId, t.collectionId] }),
+    index("api_source_collections_collection_idx").on(t.collectionId),
+    index("api_source_collections_checked_idx").on(t.checkedAt),
+]);
+/**
+ * One AI Gateway call per row (spec 2026-10-02 §6) — the `cloudflare` provider's spend, for
+ * operators and admin apps only: nothing that decides or verifies reads it. Written once per build
+ * by builder.ts (`onConflictDoNothing` on the gateway log id — a replayed write inserts nothing);
+ * the USD lands later from the gateway's own log (cron/ai-cost.ts): `pending` → `ok`, or
+ * `unavailable` (logging off, no price for the model, retention). OpenRouter calls are not here —
+ * their cost is frozen on the FactSet at call time. Trimmed after 90 days by the same job.
+ */
+export const aiCalls = sqliteTable("ai_calls", {
+    /** The gateway log id (`cf-aig-log-id`). */
+    callId: text().primaryKey(),
+    claimId: text().notNull(),
+    /** `<name>` of the ai check (or `<name>#n` for a handler's nth judge call), or `unique.judge`. */
+    fact: text().notNull(),
+    model: text().notNull(),
+    promptTokens: integer(),
+    completionTokens: integer(),
+    cachedTokens: integer(),
+    /** USD × 1e6 — integers, the money rule. Null until backfilled. */
+    costMicroUsd: integer(),
+    costStatus: text({ enum: ["pending", "ok", "unavailable"] })
+        .notNull()
+        .default("pending"),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+    costAt: integer({ mode: "timestamp_ms" }),
+}, (t) => [
+    index("ai_calls_pending_idx").on(t.costStatus, t.createdAt),
+    index("ai_calls_claim_idx").on(t.claimId),
+]);
+/**
+ * One per-submit approval of an AI app's claim (MCP over OAuth, spec 2026-10-06; S7). An OAuth
+ * caller's `submit_claim` never pays on the token alone: the first call files this row and answers
+ * `APPROVAL_REQUIRED` with AuthHub's approve link; the user approves THERE (AuthHub reads the row
+ * over the back-channel, `GET /v1/oauth/approvals/:id`, so the page shows the oracle's record, never
+ * the model's words) and AuthHub posts back a one-claim payment delegation. The same request again
+ * finds the row by `(grantId, requestDigest)` and spends it ONCE: a conditional UPDATE
+ * (`approved` → `used`) claims it before anything is paid. A card that wants 3-D Secure parks it
+ * as `awaiting_3ds`, bound to that offer and PaymentIntent, until the resume.
+ *
+ * `delegation` is a bearer credential: never logged, never returned (the GET back-channel omits
+ * it), and NULL again the moment the row is used, declined or expired. The housekeeping sweep deletes
+ * rows past `expiresAt`.
+ */
+export const mcpApprovals = sqliteTable("mcp_approvals", {
+    /** 128 random bits, base64url (22 chars) — the approve link's `id`. */
+    id: text().primaryKey(),
+    /** AuthHub's grant (`gid`) the token carried: an approval never moves to another app. */
+    grantId: text().notNull(),
+    /** The user (`sub`, a `did:ixo`) — the delegation's root issuer must be this. */
+    did: text().notNull(),
+    sourceId: text().notNull(),
+    protocolDid: text().notNull(),
+    clientId: text().notNull(),
+    clientName: text().notNull(),
+    /** sha256 over protocol, source, canonical body, attachments and the idempotency key. */
+    requestDigest: text().notNull(),
+    /** The price as the approve page shows it (`$1.20`, or `No charge`). */
+    price: text().notNull(),
+    /** What the delegation must cover, upay (1 PAY = 1 USD = 1 000 000 upay); `0` for `none`. */
+    maxAmountUpay: text().notNull(),
+    /** The source's billing mode when asked: `none` approves without a delegation. */
+    billingMode: text({ enum: ["x402", "none"] }).notNull(),
+    /** TEXT with a type-only enum. */
+    status: text({ enum: ["pending", "approved", "awaiting_3ds", "used", "expired", "declined"] })
+        .notNull()
+        .default("pending"),
+    /** The one-claim payment delegation (base64 CAR); null until approved, and once spent. */
+    delegation: text(),
+    /**
+     * `awaiting_3ds` only: the card offer and PaymentIntent the bank asked to confirm. Only a resume
+     * of exactly that offer, paid by exactly that PaymentIntent, may spend the row again.
+     */
+    offerId: text(),
+    paymentIntentId: text(),
+    /** 15 min after asking; reset to 15 min after approving, for the retry to use it. */
+    expiresAt: integer({ mode: "timestamp_ms" }).notNull(),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+}, (t) => [
+    // The retry's lookup, and the find-or-create's mutex: at most ONE live approval per app and
+    // exact request, so two racing first calls file one row (`onConflictDoNothing`).
+    uniqueIndex("mcp_approvals_live_idx")
+        .on(t.grantId, t.requestDigest)
+        .where(sql `status in ('pending', 'approved', 'awaiting_3ds')`),
+    // The housekeeping sweep.
+    index("mcp_approvals_expires_idx").on(t.expiresAt),
+]);
+/**
+ * A grant's auto-approve ("don't ask again", spec 2026-10-06 "Auto-approve"; S7): the standing
+ * payment authority the user gave an AI app on AuthHub — up to `perClaimUpay` a claim and
+ * `totalUpay` in all, until `until`. One row per AuthHub grant. `delegation` is a bearer credential
+ * whose `maxAmount` IS `totalUpay` (the facilitator enforces the total too): never logged or
+ * returned, deleted with the row. `spentUpay` is moved only by single conditional statements, so
+ * concurrent submits can never take it past `totalUpay`. Amounts are upay INTEGERs (the total is at
+ * most $100 = 1e8 upay, far inside SQLite's 64-bit range).
+ */
+export const mcpStanding = sqliteTable("mcp_standing", {
+    /** AuthHub's grant (`gid`). */
+    grantId: text().primaryKey(),
+    /** The user (`sub`): the delegation's root issuer. */
+    did: text().notNull(),
+    perClaimUpay: integer().notNull(),
+    totalUpay: integer().notNull(),
+    spentUpay: integer().notNull().default(0),
+    until: integer({ mode: "timestamp_ms" }).notNull(),
+    /** The standing payment delegation (base64 CAR), `maxAmount` = `totalUpay`. */
+    delegation: text(),
+    updatedAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date())
+        .$onUpdate(() => new Date()),
+});
+/**
+ * A grant's ONE day counter and per-request lock (S3 reviews of #87 and #90). Three kinds of row,
+ * all keyed (grant, key):
+ *   - an auto-approve spend (key = the request digest): written in the SAME `db.batch` as the
+ *     `mcp_standing` spend, which lands only if this row did — so a retry of the same request (a
+ *     model timeout, an ambiguous failure) never spends or pays again;
+ *   - a one-claim approval's spend (`approvalSpendKey`), written by `spendApproval`, whose flip
+ *     needs it — so the $20/day cap is atomic across both paths; a restore deletes it;
+ *   - an answer's marker (`answer:<approval id>`, 0 upay): the one AuthHub answer that won an
+ *     approval (`approveWithStanding`).
+ * Each spend row is kept on any outcome but a proven-nothing-reserved refund or restore, which
+ * deletes it in the same batch. `upay` is what the daily cap sums. The sweep trims old rows.
+ */
+export const mcpStandingSpends = sqliteTable("mcp_standing_spends", {
+    grantId: text().notNull(),
+    /** The approval digest of the request (`approvalDigest`). */
+    requestDigest: text().notNull(),
+    /** Random per attempt: the spend's own claim on the row (its batch checks it is this one). */
+    spendId: text().notNull(),
+    upay: integer().notNull(),
+    createdAt: integer({ mode: "timestamp_ms" })
+        .notNull()
+        .$defaultFn(() => new Date()),
+}, (t) => [
+    primaryKey({ columns: [t.grantId, t.requestDigest] }),
+    // The daily cap's sum, and the sweep.
+    index("mcp_standing_spends_grant_created_idx").on(t.grantId, t.createdAt),
+]);
+//# sourceMappingURL=schema.js.map