@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/contracts/api.js

@@ -0,0 +1,1303 @@
+/**
+ * The Decision API's wire contract (`/v1/api/*`, go-prod spec §4) as Zod — the mirror of
+ * `openapi/decision-api.yaml`, whose component schemas are GENERATED from these
+ * (`openapi/generate.ts`) and whose examples `test/node/contracts-openapi.test.ts` parses here.
+ * x402 and UDID shapes mirror the board's contracts (`board/contracts/{x402,ixo-pay,udid}`).
+ *
+ * REQUEST bodies are `z.strictObject`: an unknown key is a `400 VALIDATION` (§4.3 "validation is
+ * complete before anything is charged or stored"), never silently dropped. RESPONSES are
+ * `z.object`, so a reader tolerates the additive changes §4.1 ships without a bump. Query strings
+ * are loose: an unknown parameter is ignored. URLs we ACCEPT are https only (§14); URLs we RETURN
+ * are plain `z.url()`, so a local dev oracle on http still validates.
+ *
+ * Not a published subpath: the router parses with it, and clients (S7) are generated from the
+ * OpenAPI. NODE-SAFE all the same (zod + the engine's type mirror), because the node lane tests it.
+ */
+import { z } from "zod";
+import { Decision, ErroredFact, ManifestReviewAnswer, Verdict } from "../lib/engine/types.js";
+import { Capability, MemberRole } from "./capabilities.js";
+import { ApiErrorCode, ApiErrorEnvelope, SourcePausedReason } from "./errors.js";
+// --- limits (§4.1, §4.3, §4.6) --------------------------------------------------------------------
+/** `Prefer: wait=N` / `?wait=N` ceiling: under the step's 4-minute timeout and the ~100 s most
+ *  gateways cut at, above the typical AI + external-source budget (§4.6). */
+export const MAX_WAIT_SECONDS = 90;
+export const MAX_BATCH_CLAIMS = 100;
+export const MAX_PAGE_LIMIT = 500;
+/** `metadata` is echoed on every GET and webhook, never evaluated — kept small (§4.3). */
+export const MAX_METADATA_BYTES = 4096;
+export const MAX_JSON_BODY_BYTES = 1024 * 1024;
+export const MAX_UPLOAD_BYTES = 25_000_000;
+// --- ids and scalars --------------------------------------------------------------------------------
+const ULID = "[0-9A-HJKMNP-TV-Z]{26}";
+const ulidId = (prefix) => z.string().regex(new RegExp(`^${prefix}_${ULID}$`));
+/** `apc_` + 40 hex of sha256(sourceId|Idempotency-Key) — so the ledger's PK insert IS the
+ *  duplicate guard (§4.6) — or `apc_` + a fresh ULID when the caller sent no key. */
+export const ClaimId = z.string().regex(new RegExp(`^apc_([0-9a-f]{40}|${ULID})$`));
+/** Any claim a record can show (contracts v1.2): an API claim's `ClaimId`, or a chain claim's own
+ *  id — a CID, or (on older collections) a Matrix event id — at most 512 chars. What the READ
+ *  routes take as `:claimId` (the record, timeline, receipt, report — a source's for its linked
+ *  collections' chain claims, and the operator's); submit, review and erase stay `ClaimId`. */
+export const RecordClaimId = z.string().min(1).max(512);
+export const SourceId = ulidId("src");
+export const EndpointId = ulidId("whe");
+export const EventId = ulidId("evt");
+export const MemberId = ulidId("mem");
+export const UploadId = ulidId("upl");
+export const AuditId = ulidId("aud");
+/** `wh:<eventId>:<endpointId>`, or `wh:<eventId>:claim` for the claim's own `webhookUrl` — the
+ *  `matrix_deliveries.dedupeKey`, so a redelivery can never double-post one event to one target. */
+export const DeliveryId = z.string().regex(new RegExp(`^wh:evt_${ULID}:(whe_${ULID}|claim)$`));
+/** The facilitator's settlement id (`org.udid.receipt@1` `settlementId`, payments spec §13.1): 64
+ *  hex, one per offer — a batch's claims share it. Replaces the hold id `chargeId` (contracts v1.3). */
+export const SettlementId = z.string().regex(/^[0-9a-f]{64}$/);
+/** The 8-char lookup prefix of an API key (`eo_live_<prefix>_<secret>`, §3.2). */
+export const KeyPrefix = z.string().regex(/^[0-9a-z]{8}$/);
+export const ProtocolDid = z.string().regex(/^did:ixo:entity:[0-9a-zA-Z]+$/);
+/** An IXO user account (`ixo1` + 38 bech32 chars) — members, owners, payers. Contract and DAO
+ *  accounts are not supported at launch (the board's `didIxo`). */
+export const AccountDid = z.string().regex(/^did:ixo:ixo1[02-9ac-hj-np-z]{38}$/);
+/** A company entity (company authority D1): the on-chain entity whose controllers administer every
+ *  source linked to it. */
+export const EntityDid = z.string().regex(/^did:ixo:entity:[0-9a-f]{32}$/);
+/** A reviewer key: `did:key` (Ed25519) generated in the member's browser (§3.2, §10). */
+export const ReviewerDid = z.string().regex(/^did:key:z[1-9A-HJ-NP-Za-km-z]+$/);
+/** ISO-8601 UTC (§4.1) — `Z`, never an offset — on everything we write. */
+export const Timestamp = z.iso.datetime();
+/** A compact JWS: base64url(header).base64url(payload).base64url(signature). */
+export const CompactJws = z.string().regex(/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/);
+/** SSRF control §14 starts at the schema: https only. The public-DNS / private-range checks run
+ *  at fetch time, per redirect hop, where the resolved address is known. */
+export const HttpsUrl = z.url({ protocol: /^https$/ });
+/** A non-negative integer in an asset's base units as a decimal STRING, never a float — PAY
+ *  (`upay`, 1 PAY = 1 USD = 1,000,000 upay) or a customer's own asset. 78 digits covers uint256. */
+export const BaseUnitAmount = z.string().regex(/^(0|[1-9][0-9]{0,77})$/);
+/** Any CAIP-2 `namespace:reference` — the network of a customer's own x402 offer. */
+export const Caip2Network = z.string().regex(/^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$/);
+/** x402's network id for the IXO chain the facilitator settles on, CAIP-2 `cosmos:<chain-id>`
+ *  (`cosmos:devnet-1`, `cosmos:pandora-8` testnet, `cosmos:ixo-5` mainnet). */
+export const IxoNetwork = z.string().regex(/^cosmos:[-_a-zA-Z0-9]{1,32}$/);
+/** The card scheme's networks (payments spec §6.3, `stripe-manual-capture`): Stripe test or live. */
+export const StripeNetwork = z.enum(["stripe:test", "stripe:live"]);
+/** CAIP-2 `eip155:<chainId>`: the `exact` scheme's EVM chain (USDC on Base: `eip155:8453`). */
+export const EvmNetwork = z.string().regex(/^eip155:[1-9][0-9]{0,19}$/);
+/** A 20-byte EVM account, hex: an `exact` payment's payer (its EIP-3009 authorization's signer). */
+export const EvmAddress = z.string().regex(/^0x[0-9a-fA-F]{40}$/);
+/** Where a payment settles: the IXO chain (PAY), Stripe (card, contracts v1.4) or an EVM chain
+ *  (`exact`: USDC on Base, a plan without PAY). */
+export const SettleNetwork = z.union([IxoNetwork, StripeNetwork, EvmNetwork]);
+/** The facilitator's offer id, the 402's single-use nonce: a lowercase UUID. */
+export const OfferNonce = z
+    .string()
+    .regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+export const Scope = z.enum(["claims:write", "claims:read", "webhooks:manage"]);
+export { Capability, MemberRole };
+/** The ledger's `claim_ingests.status` — where the claim got to, independent of the verdict. */
+export const ClaimStatus = z.enum(["queued", "processing", "processed", "failed"]);
+/** How a claim arrived (contracts v1.2): `POST /v1/api/claims`, or the cron's scan of a watched
+ *  on-chain collection. */
+export const ClaimLane = z.enum(["api", "chain"]);
+/** The `decisions.chainStatus` column: where a verdict got to on chain. Always `skipped` on the API
+ *  lane (nothing is signed); a chain claim's is the act lane's real state. */
+export const ChainStatus = z.enum([
+    "pending",
+    "submitted",
+    "blocked",
+    "skipped",
+    "held",
+    "owner_submitted",
+]);
+/**
+ * The `decisions.status` column: the engine's three, the facts lane's own `invalid_facts`, and the
+ * engine's two refusals of the claim's content (v1.7): `content_mismatch` (the facts don't match the
+ * content you sent) and `payload_too_large` — both with no decision, and the claim `failed`.
+ */
+export const DecisionStatus = z.enum([
+    "decided",
+    "pending_review",
+    "unusable",
+    "invalid_facts",
+    "content_mismatch",
+    "payload_too_large",
+]);
+/**
+ * A claim's payment (contracts v1.3, payments spec §4): `reserved` at accept (`/verify` reserved the
+ * price; the claim runs), `settled` once the engine's receipt was accepted (the minute's transfer has
+ * not paid it yet), `paid` with the transfer's `transaction`, `released` when no receipt came within
+ * 24 h (nothing moved), `failed` when the facilitator refused the receipt (nothing moved).
+ */
+/** `refunded` / `partially_refunded` (v1.4.3) are a paid CARD payment the operator refunded since —
+ *  PAY is final on chain and never reaches them. */
+export const PaymentStatus = z.enum([
+    "reserved",
+    "settled",
+    "paid",
+    "released",
+    "failed",
+    "refunded",
+    "partially_refunded",
+]);
+/** `failed` will be retried; `dead` spent its 8 attempts (§4.5) and waits for a redeliver. The
+ *  delivery row's `sent` is `delivered` here: the wire says what the receiver got. */
+export const DeliveryStatus = z.enum(["pending", "delivered", "failed", "dead"]);
+/**
+ * v1.8 (D10): a source starts `pending-link` — created by a controller of its organisation, waiting
+ * for the engine to hold the organisation's link for it — and turns `active` at the company sync.
+ * `disputed`: the engine holds a link for ANOTHER entity (first link wins), or says disputed — no
+ * authority; delete the source and add the oracle again. Neither takes claims, keys, invites or
+ * webhooks. `paused` is the only state with a `pausedReason`.
+ */
+export const SourceStatus = z.enum(["pending-link", "active", "paused", "disputed"]);
+/**
+ * How a source pays (§3.2): `x402` — an outside customer pays per decision (§11) — or `none` — the
+ * operator's own organisation or a partner it does not charge: no 402, no `api_charges` row. Set
+ * only by the oracle's operator; the engine bills the oracle's owner its fee either way (§11.12).
+ */
+export const BillingMode = z.enum(["x402", "none"]);
+export { Verdict };
+/**
+ * The oracle's published price for one protocol (payments spec §3.1) — what
+ * `GET /v1/api/protocols/:did` serves, every offer quotes and the facilitator checks each charge
+ * against (`price_mismatch` otherwise). `amountMicroUsd` is the price, and the PAY base units
+ * (`amount`, 1 upay = 1 micro-USD) the same number; `amountCents` is it rounded DOWN to a whole
+ * cent, for display and the per-key daily cap.
+ */
+export const Price = z.object({
+    amountMicroUsd: z.int().min(0),
+    amountCents: z.int().min(0),
+    currency: z.literal("USD"),
+    amount: BaseUnitAmount,
+    asset: z.literal("upay"),
+});
+const keysetPage = (item) => z.object({ items: z.array(item), nextCursor: z.string().nullable() });
+// --- x402 (§4.3, §11.2, §11.9, §11.10; board contracts x402/, ixo-pay/, udid/) -----------------------
+/**
+ * x402 v2 `PaymentRequirements` in its generic form — what a customer's own payment service
+ * advertised, forwarded to the engine untouched (§11.10 step 1). LOOSE on purpose, the one loose
+ * request object: the engine binds the decision-to-pay to `sha256(RFC 8785 canonical JSON of
+ * requirements)`, so dropping a key we do not know would change the digest the payer's
+ * facilitator recomputes — and the credential would never verify. v2 has no `resource` here.
+ */
+export const PaymentRequirements = z.looseObject({
+    scheme: z.string().min(1),
+    network: Caip2Network,
+    amount: BaseUnitAmount,
+    asset: z.string().min(1),
+    payTo: z.string().min(1),
+    maxTimeoutSeconds: z.int().min(1),
+    extra: z.record(z.string(), z.unknown()).optional(),
+});
+/** x402 v2 `ResourceInfo`: what is paid for. LOOSE — upstream grows it. */
+export const ResourceInfo = z.looseObject({
+    url: z.url().max(2048),
+    description: z.string().optional(),
+    mimeType: z.string().optional(),
+});
+/**
+ * One ixo-pay `accepts[]` entry (§11.2) exactly as the facilitator registered it — strict, because
+ * the payer echoes it byte for byte as `accepted` and the facilitator refuses anything not
+ * canonically equal (`terms_mismatch`). `extra.nonce` is the facilitator's single-use offerId.
+ */
+export const IxoPayRequirements = z.strictObject({
+    scheme: z.literal("ixo-pay"),
+    network: IxoNetwork,
+    asset: z.literal("upay"),
+    amount: BaseUnitAmount,
+    /** The real recipient: the operator's own `EARNINGS_ADDRESS`, an IXO account (payments spec §3.2,
+     *  §13.1). The oracle names it in the offer; the facilitator checks it, never picks one. */
+    payTo: z.string().regex(/^ixo1[02-9ac-hj-np-z]{38,58}$/),
+    maxTimeoutSeconds: z.int().min(1).max(3600),
+    extra: z.strictObject({ nonce: OfferNonce, fundingUrl: z.url() }),
+});
+/**
+ * The `PAYMENT-REQUIRED` header (base64 of UTF-8 JSON) — authoritative for x402 clients (board
+ * D30). It is the facilitator's `/offers` answer verbatim: `resource.url` is the submit URL with
+ * the claimId as fragment, or the batch URL. `accepts` holds the ways the oracle's plan takes: an
+ * ixo-pay entry (PAY, IXO-run oracles only), the facilitator's `stripe-manual-capture` entry when
+ * it takes card (contracts v1.4, payments spec §6.3), and x402's `exact` EVM entry when it takes
+ * USDC on Base — a plan without PAY lists no ixo-pay entry at all (§11.7).
+ */
+export const X402PaymentRequired = z.object({
+    x402Version: z.literal(2),
+    error: z.string().optional(),
+    resource: ResourceInfo,
+    accepts: z
+        .array(PaymentRequirements)
+        .min(1)
+        .refine((a) => a.some((r) => IxoPayRequirements.safeParse(r).success ||
+        (r.scheme === "stripe-manual-capture" && StripeNetwork.safeParse(r.network).success) ||
+        (r.scheme === "exact" && EvmNetwork.safeParse(r.network).success)), {
+        message: "accepts must contain an ixo-pay, a stripe-manual-capture (card) or an exact entry",
+    }),
+    extensions: z.record(z.string(), z.unknown()).optional(),
+});
+/** The `PAYMENT-SIGNATURE` request header (base64 of UTF-8 JSON, x402 v2 PaymentPayload): the
+ *  chosen terms echoed as `accepted`, and the developer's delegation with the 402's nonce. */
+export const IxoPayPaymentPayload = z.strictObject({
+    x402Version: z.literal(2),
+    resource: ResourceInfo.optional(),
+    accepted: IxoPayRequirements,
+    payload: z.strictObject({
+        /** `IXO_PAYMENT_DELEGATION` verbatim: base64 of the encoded UCAN delegation. */
+        delegation: z
+            .string()
+            .min(16)
+            .regex(/^[A-Za-z0-9+/_-]+={0,2}$/),
+        nonce: OfferNonce,
+    }),
+    extensions: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * One card `accepts[]` entry (contracts v1.4, payments spec §6.3): the facilitator's
+ * `stripe-manual-capture` terms — `amount` in US cents, `payTo` the operator's Stripe account,
+ * `extra` exactly `{ nonce }`. Listed after the ixo-pay entry when the oracle takes card.
+ */
+export const CardRequirements = z.strictObject({
+    scheme: z.literal("stripe-manual-capture"),
+    network: StripeNetwork,
+    amount: z.string().regex(/^[1-9][0-9]{0,77}$/),
+    asset: z.literal("usd"),
+    payTo: z.string().regex(/^acct_[a-zA-Z0-9]+$/),
+    maxTimeoutSeconds: z.int().min(10).max(300),
+    extra: z.strictObject({ nonce: OfferNonce }),
+});
+/**
+ * The `PAYMENT-SIGNATURE` header for card (contracts v1.4): the card entry echoed as `accepted` and
+ * the PaymentIntent the payer authorized (uncaptured) on its saved card. There is no delegation:
+ * the payer is the account the facilitator's `/verify` names. After a 3-D Secure confirmation the
+ * SAME header (the original offer) is sent again, even past the offer's `maxTimeoutSeconds`.
+ */
+export const CardPaymentPayload = z.strictObject({
+    x402Version: z.literal(2),
+    resource: ResourceInfo.optional(),
+    accepted: CardRequirements,
+    payload: z.strictObject({
+        paymentIntentId: z.string().regex(/^pi_[a-zA-Z0-9]+$/),
+        customerId: z.string().regex(/^cus_[a-zA-Z0-9]+$/),
+    }),
+    extensions: z.record(z.string(), z.unknown()).optional(),
+});
+/** One claim of a (possibly batched) settlement and where it got to at the facilitator. */
+/**
+ * A chain claim's id as the facilitator keys its reservation (1.22.0, x402-ixo-pay 0.7.0): a CIDv1
+ * in lowercase base32 — checked by form, as the facilitator does.
+ */
+export const ChainClaimId = z.string().regex(/^b[a-z2-7]{50,100}$/);
+/** A settled claim: an API claim, or (1.22.0) a chain claim a per-review collection paid for. */
+export const SettlementClaim = z.looseObject({
+    claimId: z.union([ClaimId, ChainClaimId]),
+    state: z.string().min(1),
+});
+/** `org.udid.receipt@1` — the settlement receipt: one `settlementId` per offer, the claims the
+ *  `/settle` call carried receipts for; `decision` is absent on ixo-pay (no decision-to-pay). */
+export const UdidReceipt = z.looseObject({
+    settlementId: SettlementId,
+    offerId: OfferNonce,
+    replayed: z.boolean(),
+    claims: z.array(SettlementClaim).min(1).max(MAX_BATCH_CLAIMS),
+    decision: z.object({ issuer: z.string().min(1), id: z.string().min(1) }).optional(),
+});
+/**
+ * The `PAYMENT-RESPONSE` header on a sync `200` (contracts v1.3): the facilitator's `/settle` answer
+ * for the claim's receipt, forwarded VERBATIM — loose, so nothing it adds is stripped. `success`
+ * with the real `transaction` once the minute's transfer paid it; before that (usual for PAY)
+ * `settlement_pending` (its `transaction` empty, or at most a reference that is not yet final) with
+ * the `settlementId`.
+ */
+/** Who paid: an IXO account (PAY, and card — bound to one), or an `exact` payment's EVM signer. */
+const SettlePayer = z.union([AccountDid, EvmAddress]);
+export const X402PaymentResponse = z.union([
+    z.looseObject({
+        success: z.literal(true),
+        /** The IXO transfer's tx hash, the card's captured PaymentIntent (`pi_…`, v1.4), or the
+         *  `exact` USDC transfer's EVM tx hash. */
+        transaction: z.string().min(1).max(256),
+        network: SettleNetwork,
+        payer: SettlePayer,
+        extensions: z.looseObject({ "org.udid.receipt@1": UdidReceipt }),
+    }),
+    z.looseObject({
+        success: z.literal(false),
+        errorReason: z.literal("settlement_pending"),
+        /** Empty until the transfer; any string is accepted here, only `success` makes it real. */
+        transaction: z.string(),
+        network: SettleNetwork,
+        payer: SettlePayer,
+        extensions: z.looseObject({ "org.udid.receipt@1": UdidReceipt }),
+    }),
+]);
+const PaymentCode = ApiErrorCode.extract(["PAYMENT_REQUIRED", "SPEND_CAP", "INSUFFICIENT_CREDITS"]);
+/**
+ * The 402 BODY (Appendix A, board D30): our error envelope, the x402 object in
+ * `details.paymentRequired` for a client that reads bodies, and `price` / `fundingUrl` for a human.
+ * Only `PAYMENT_REQUIRED` carries an offer: `SPEND_CAP` and `INSUFFICIENT_CREDITS` have nothing an
+ * SDK may auto-pay, so it branches on `error.code` and surfaces those two to the developer.
+ */
+export const PaymentRequiredBody = z
+    .object({
+    error: ApiErrorEnvelope.shape.error.extend({
+        code: PaymentCode,
+        details: z.object({
+            paymentRequired: X402PaymentRequired.optional(),
+            price: Price,
+            fundingUrl: z.url(),
+        }),
+    }),
+})
+    .refine((b) => (b.error.code === "PAYMENT_REQUIRED") === (b.error.details.paymentRequired !== undefined), { message: "details.paymentRequired is present exactly on PAYMENT_REQUIRED" });
+// --- submit (§4.3) ---------------------------------------------------------------------------------
+const AttachmentBase = {
+    /** The claim form's file question this answers — what `attachments[].question` carries in a FactSet. */
+    question: z.string().min(1).max(256),
+    name: z.string().min(1).max(256).optional(),
+    mediaType: z
+        .string()
+        .min(1)
+        .max(256)
+        .optional()
+        .describe("Optional. Left out on a url attachment, the oracle detects it once at accept — from the URL's extension, else the Content-Type of one HEAD — and stores it with the claim; unknown stays application/octet-stream. An upload's type is the one sniffed at upload."),
+    cid: z.string().min(1).max(256).optional(),
+};
+/**
+ * A file the claim points at: EXACTLY one of an https `url` or an `uploadId` from
+ * `PUT /v1/api/uploads` (strict objects, so both-or-neither matches no branch). An `uploadId` is
+ * resolved to its R2 object inside the workflow — never through a signed URL, whose `exp` would
+ * expire under a slow retry ladder. v1.7: an upload carries the `cid` its upload returned — it is
+ * part of the claim's content (company authority: the engine binds the file by it), and accept
+ * refuses one that is not the upload's.
+ */
+export const Attachment = z.union([
+    z.strictObject({ ...AttachmentBase, url: HttpsUrl }),
+    z.strictObject({
+        ...AttachmentBase,
+        uploadId: UploadId,
+        cid: z
+            .string()
+            .min(1)
+            .max(256)
+            .describe("Required: the `cid` PUT /v1/api/uploads returned for this upload."),
+    }),
+]);
+const Metadata = z
+    .record(z.string(), z.unknown())
+    .refine((m) => new TextEncoder().encode(JSON.stringify(m)).length <= MAX_METADATA_BYTES, {
+    message: `metadata must serialize to at most ${MAX_METADATA_BYTES} bytes`,
+});
+export const SubmitClaimRequest = z.strictObject({
+    /** Optional when the source has exactly one allowed protocol. */
+    protocolDid: ProtocolDid.optional(),
+    /** The credentialSubject, shaped by `GET /v1/api/protocols/:did` `answers` — checked against
+     *  that JSON Schema at the route, since it is per-protocol. Never returned by any read. */
+    answers: z.record(z.string(), z.unknown()),
+    attachments: z.array(Attachment).max(100).optional(),
+    /**
+     * Your own stable id for the person the claim is about (e.g. a courier id) — the frequency rule's
+     * per-submitter count. When absent, the answer the source's company link names (`payeeField`)
+     * is used. Required when the protocol has a frequency rule (its work order's
+     * `facts.frequency`) and neither is there: otherwise `400 VALIDATION` at `submitter` (at
+     * `answers.<payeeField>` when the source has one), before any payment. Over OAuth (an AI app
+     * signed in as a person) it must be that person's DID, else `400 VALIDATION` at `submitter`.
+     */
+    submitter: z.string().min(1).max(256).optional(),
+    metadata: Metadata.optional(),
+    webhookUrl: HttpsUrl.optional(),
+});
+/** `202` when the decision did not land inside the wait budget — also a repeat of a running key. */
+export const Accepted = z.object({
+    claimId: ClaimId,
+    status: ClaimStatus,
+    pollUrl: z.url(),
+});
+/**
+ * Async only; ONE offer covers the batch (price × valid items), one reservation per claim, each
+ * settled on its own receipt. With an `Idempotency-Key` K on the batch, item i's claimId derives from
+ * `K:i`, so a retried batch re-finds every item.
+ */
+export const BatchSubmitRequest = z.strictObject({
+    claims: z.array(SubmitClaimRequest).min(1).max(MAX_BATCH_CLAIMS),
+});
+/** One item's answer: accepted, or its own validation error inline — one bad item never fails the batch. */
+export const BatchItemResult = z.discriminatedUnion("status", [
+    z.object({
+        index: z.int().min(0),
+        status: z.literal("accepted"),
+        claimId: ClaimId,
+        pollUrl: z.url(),
+    }),
+    z.object({
+        index: z.int().min(0),
+        status: z.literal("rejected"),
+        error: ApiErrorEnvelope.shape.error.omit({ requestId: true }),
+    }),
+]);
+export const BatchSubmitResponse = z.object({ items: z.array(BatchItemResult) });
+// --- the record (§4.4) -----------------------------------------------------------------------------
+export const ReceiptRef = z.object({ cid: z.string().min(1), jws: z.string().min(1) });
+/**
+ * The `decisions` row as the API shows it. `decision` is the ENGINE's `Decision` verbatim — the
+ * oracle never decides, so there is no field here it computed; null for the facts lane's
+ * `invalid_facts` (no engine call was made). `chainStatus` is always `skipped` on the API lane;
+ * on a chain claim it is where the `MsgEvaluateClaim` got to (contracts v1.2).
+ */
+export const ClaimDecision = z.object({
+    status: DecisionStatus,
+    verdict: Verdict.nullable(),
+    rubricId: z.string().nullable(),
+    factsDigest: z.string().nullable(),
+    resultDigest: z.string().nullable(),
+    decision: Decision.nullable(),
+    explanation: z.string().nullable(),
+    /**
+     * The engine's one public credential for this decision (UDID). On an approved claim whose
+     * protocol has `OracleConfig.payouts` it is also typed `DecisionToPayCredential` and carries the
+     * payment binding a company's facilitator pays from (v1.13).
+     */
+    receipt: ReceiptRef.nullable(),
+    chainStatus: ChainStatus,
+    /**
+     * WHY a claim was held or refused (1.20.0): each `ext`/`ai` fact that came back `error`, as the
+     * engine names it — `name` lane-prefixed (`ext.beforeAfter`, `ai.sameBoat`), `detail` the fact's
+     * own error text (the handler's or the stock lane's, never an answer field), at most 500 chars.
+     * The engine's `reasons` stay generic. Omitted when no fact errored.
+     */
+    erroredFacts: z.array(ErroredFact).min(1).optional(),
+});
+/** A task a human must answer (§10), with the prompt and answer shape the manifest declares. */
+export const ReviewTask = z.object({
+    id: z.string().min(1),
+    prompt: z.string().min(1),
+    answer: ManifestReviewAnswer,
+});
+/**
+ * `pendingTasks` are what the engine asked for, with prompt and answer shape from the manifest —
+ * stored in the claim's `review_required` timeline event at decision time, so a later manifest
+ * change never rewrites what the reviewer was asked.
+ */
+export const ClaimReviewState = z.object({
+    pendingTasks: z.array(ReviewTask),
+    answeredAt: Timestamp.nullable(),
+    foldedAt: Timestamp.nullable(),
+    /** Why the fold did not land (e.g. the engine's `STALE_REVIEW`) — cleared by a re-answer. */
+    foldError: z.string().nullable(),
+    /**
+     * A paid claim's review deadline (contracts v1.3.1): when its payment reservation runs out — the
+     * facilitator's extended expiry, else 24 h after verify. Answers after it are refused
+     * `409 REVIEW_EXPIRED`, since the claim could no longer be paid. Null for a source that does not
+     * bill (`billingMode: none`), and once the claim no longer awaits review.
+     */
+    answerBy: Timestamp.nullable(),
+});
+export const ClaimPayment = z.object({
+    /** How it was paid: PAY (`ixo-pay`, in upay), since v1.4 card (`stripe-manual-capture`, US
+     *  cents: the claim's price), or USDC on Base (`exact`, in USDC base units = micro-USD). */
+    scheme: z.enum(["ixo-pay", "stripe-manual-capture", "exact"]),
+    amount: BaseUnitAmount,
+    asset: z.enum(["upay", "usd", "usdc"]),
+    /** The facilitator's settlement id; null while `reserved` (contracts v1.3; was `chargeId`). */
+    settlementId: SettlementId.nullable(),
+    status: PaymentStatus,
+    /** What paid it, once `paid`: the transfer's chain tx hash (PAY) or the captured PaymentIntent
+     *  (`pi_…`, card); never invented. */
+    transaction: z.string().min(1).max(256).nullable(),
+    /** A card refund (v1.4.3), as the facilitator reports it — the latest refund's time and id, and
+     *  the total refunded in US cents. All null until one exists, and always for PAY. */
+    refundedAt: Timestamp.nullable(),
+    refundId: z.string().min(1).max(256).nullable(),
+    refundedAmountCents: z.number().int().nonnegative().nullable(),
+});
+/** The claim's latest event, aggregated over its deliveries (the claim's own `webhookUrl` and
+ *  every subscribed endpoint): `delivered` only when all are; `dead` if any is; the attempts summed. */
+export const ClaimWebhookState = z.object({
+    status: DeliveryStatus,
+    attempts: z.int().min(0),
+});
+/** Why a claim failed (§5): the facts lane missed the work order, the engine refused the facts,
+ *  the stored body no longer matched its digest, or the retry ladder (~4 h) ran out. */
+export const ClaimErrorCode = z.enum([
+    "invalid_facts",
+    "engine_rejected",
+    "body_mismatch",
+    "retries_exhausted",
+]);
+/**
+ * §4.4 — the sync 200, the GET, and every `claim.*` webhook's `data`. NEVER the answers (§6.3):
+ * they are personal data and only the fold re-reads them. `null` wherever a part has not happened.
+ * Since v1.2 it shows either lane: an API claim has its `sourceId` and no `collectionId`; a chain
+ * claim its on-chain `collectionId`, `metadata` and `payment` null, and a `sourceId` only when read
+ * through a source's linked collection.
+ */
+export const ClaimRecord = z.object({
+    claimId: RecordClaimId,
+    lane: ClaimLane,
+    sourceId: SourceId.nullable(),
+    collectionId: z.string().min(1).nullable(),
+    /** An API claim's protocol; a chain claim's is its collection's. */
+    protocolDid: ProtocolDid,
+    /**
+     * v1.5 (S16) — who the claim is ABOUT: `submitter` on submit, else (v1.7) the answer the
+     * source's company link names (`payeeField`) — the payee a decision to pay binds
+     * (`submitter:<sourceId>:<submitter>`). An OPAQUE id — never a name, email or phone. Null for a
+     * chain claim (its payee is the on-chain agent) and after erasure. Optional only so a record from
+     * an oracle before 1.5 still parses.
+     */
+    submitter: z.string().nullable().optional(),
+    /**
+     * v1.7 — who SENT the claim, set by the oracle from the caller, never from the content: the
+     * signed-in user's DID for an AI app over OAuth; null for an API key, a console submit and a
+     * chain claim.
+     */
+    submittedBy: z.string().nullable(),
+    /**
+     * v1.12.0 — WHICH AI app sent the claim over OAuth; null for an API key, a console submit and a
+     * chain claim. `name` is the app's registered name (e.g. "Claude", "ChatGPT", "Codex"),
+     * self-declared when it registered — trimmed, at most 100 characters — so on its own it is a
+     * hint. `verified` is true when AuthHub registered the app with only Claude's or ChatGPT's own
+     * callback, so the token can only be theirs: show the app's icon then. A local app (Claude Code,
+     * Codex: loopback redirects) is `verified: false`, whatever its name.
+     */
+    submittedVia: z
+        .strictObject({ name: z.string().min(1).max(100), verified: z.boolean() })
+        .nullable()
+        .meta({ example: { name: "Claude", verified: true } }),
+    /**
+     * v1.7 — the claim content's id, `sha256:<hex>` over the canonical JSON of what you sent (minus
+     * `webhookUrl`, with the resolved `protocolDid`): recompute it from your own
+     * request to check the receipt is about your claim. Survives erasure. Null for a chain claim and
+     * for an API claim accepted before 1.7.
+     */
+    contentDigest: z.string().nullable(),
+    status: ClaimStatus,
+    decision: ClaimDecision.nullable(),
+    review: ClaimReviewState.nullable(),
+    payment: ClaimPayment.nullable(),
+    webhook: ClaimWebhookState.nullable(),
+    /** Set when `status` is `failed` (§5). `message` is fixed text per code — never a handler's or
+     *  the engine's own error text, which can echo answer values. */
+    error: z.object({ code: ClaimErrorCode, message: z.string() }).nullable(),
+    metadata: z.record(z.string(), z.unknown()).nullable(),
+    createdAt: Timestamp,
+    decidedAt: Timestamp.nullable(),
+});
+export const ClaimPage = keysetPage(ClaimRecord);
+/**
+ * v1.2.1 — the operator's read of a record (`/admin/claims*`): the owning source's display name
+ * beside its `sourceId`, since an operator is no member of its customers' sources and cannot look
+ * the name up. `null` for a chain claim, which no source owns.
+ */
+export const AdminClaimRecord = ClaimRecord.extend({ sourceName: z.string().nullable() });
+export const AdminClaimPage = keysetPage(AdminClaimRecord);
+/** `GET /v1/api/claims` filters (§4.2); newest first, keyset (§4.1). Loose: an unknown
+ *  parameter is ignored, as HTTP caches and tracing proxies add their own. `lane` picks one lane;
+ *  absent, a console member gets both — the source's API claims and its linked collections' chain
+ *  claims (contracts v1.2) — and an API key `api`, so an integration written before 1.2 sees no
+ *  chain record it did not ask for (`lane=chain`). `collectionId` narrows to one linked
+ *  collection's chain claims. */
+export const ListClaimsQuery = z.object({
+    lane: ClaimLane.optional(),
+    collectionId: z.string().min(1).max(256).optional(),
+    status: ClaimStatus.optional(),
+    /** The decision's status — `pending_review` is the review queue. */
+    decision: DecisionStatus.optional(),
+    protocol: ProtocolDid.optional(),
+    verdict: Verdict.optional(),
+    since: Timestamp.optional(),
+    until: Timestamp.optional(),
+    limit: z.coerce.number().int().min(1).max(MAX_PAGE_LIMIT).default(100),
+    cursor: z.string().max(1024).optional(),
+});
+/** `GET /v1/api/admin/claims` (contracts v1.2): the source list's filters over EVERY source and
+ *  every watched collection, plus `sourceId` — which finds API claims only. */
+export const AdminListClaimsQuery = ListClaimsQuery.extend({
+    sourceId: SourceId.optional(),
+});
+// --- timeline, receipt, report, review, erase (§4.2) -----------------------------------------------
+export const ClaimEventType = z.enum([
+    "accepted",
+    "paid",
+    "facts_produced",
+    "decided",
+    "review_required",
+    "review_answered",
+    "folded",
+    "unusable",
+    "failed",
+    "webhook_attempt",
+    "erased",
+    /** A chain claim's verdict is on chain (contracts v1.2): `data.chainStatus` says whose tx. */
+    "chain_submitted",
+    /** A paid claim's review passed its `answerBy` unanswered (contracts v1.3.1): `data.answerBy`.
+     *  The claim stays `pending_review` — closed unpaid. */
+    "review_expired",
+]);
+/** One `api_events` row — or, for a chain claim, one step derived from its ledger rows' times.
+ *  `data` carries names, codes, durations and counts — for `facts_produced` the fact names and
+ *  their timings, NEVER a value (§4.2). `accepted` carries `protocolDid`, and `via:
+ *  "oauth:<client_id>"` (1.4.6) when an AI app submitted the claim over OAuth. */
+export const ClaimEvent = z.object({
+    id: EventId,
+    type: ClaimEventType,
+    at: Timestamp,
+    data: z.record(z.string(), z.unknown()).nullable(),
+});
+export const ClaimEvents = z.object({ claimId: RecordClaimId, items: z.array(ClaimEvent) });
+/** Everything needed to verify offline: the engine's receipt and where its keys live. */
+export const Receipt = z.object({
+    cid: z.string().min(1),
+    jws: z.string().min(1),
+    /** The engine's `/v1/issuer-keys` — pin the `kid` from there. */
+    issuerKeysUrl: z.url(),
+    verifyUrl: z.url(),
+});
+/**
+ * Mirrors the chain lane's review body (`routes/v1/reviews.ts`): answers cover EXACTLY the
+ * pending tasks, and `attestation` — the reviewer's signed statement — is required: a member's
+ * from its registered `did:key` (§10), an organisation controller's (a root, 1.11.0) from its
+ * `did:ixo` with a `kid` on that DID's document. It is typed optional only so a missing one
+ * answers `ATTESTATION_REQUIRED` rather than a generic `VALIDATION`, as on the chain lane.
+ */
+export const ReviewRequest = z.strictObject({
+    answers: z.record(z.string().min(1).max(256), z.union([z.boolean(), z.string().max(4096)])),
+    attestation: z.string().min(1).max(16384).optional(),
+    /** 1.11.0 — the reviewer's authority, a base64 CAR (the chain route's bounds); every link has
+     *  `nbf` and `exp` ≤ 30 days apart and a `claims/review` cap on `ixo:oracle/<oracle did:web>/
+     *  source/<sourceId>`, no wildcard. A ROOT: one delegation, issuer = audience = its did:ixo,
+     *  signed by the attestation's key. A MEMBER: two links — its stored access from a controller,
+     *  then its did:ixo → its registered reviewer did:key (exactly `claims/review`). REQUIRED — typed
+     *  optional so a missing one is `400 REVIEWER_GRANT_INVALID` (`absent`), the engine's code. */
+    reviewerGrant: z.string().min(1).max(16384).optional(),
+    /** The `resultDigest` the reviewer answered; when sent, a different current digest is
+     *  `409 NOT_PENDING_REVIEW` before the attestation is checked. */
+    answeredAgainst: z.string().min(1).optional(),
+});
+/** The stored review, as the chain lane's `reviewBody` shows it — the JWS itself never leaves. */
+export const ReviewRow = z.object({
+    claimId: ClaimId,
+    answers: z.record(z.string(), z.union([z.boolean(), z.string()])),
+    /** A member's reviewer key, or (1.11.0) the organisation controller who answered as root. */
+    reviewerDid: z.union([ReviewerDid, AccountDid]),
+    answeredAt: Timestamp,
+    foldedAt: Timestamp.nullable(),
+    foldError: z.string().nullable(),
+});
+/**
+ * Why the CALLER cannot answer reviews on this oracle (1.15.0), known before it tries — only what is
+ * cheap and certain: `oracle-owner`, it is the account that registered this oracle with the decision
+ * engine, which never folds an answer from the oracle's own side (`403 REVIEWER_NOT_AUTHORIZED`,
+ * `details.reason: "oracle-owner"`); `not-reviewer`, the caller does not sign answers — an API key
+ * (which may still relay a member-signed answer), or a member or AI app without `claims/review`.
+ */
+export const ReviewBlock = z.enum(["oracle-owner", "not-reviewer"]);
+/** Can the caller answer this review? `reason` is set iff `ok` is false. */
+export const CanAnswer = z.object({ ok: z.boolean(), reason: ReviewBlock.optional() });
+/**
+ * `GET /v1/api/claims/:claimId/review` — what a reviewer needs to answer (§3.4 `claims/review`):
+ * the ONLY read that returns a claim's answers, and only while it awaits review. Every read is an
+ * audit row. A file is its own https URL, or a short-lived signed read of an upload.
+ */
+/** A file as a reviewer opens it: its own https URL, or a short-lived signed read of an upload. */
+const ReviewFile = z.object({
+    question: z.string().min(1),
+    name: z.string().nullable(),
+    mediaType: z.string().nullable(),
+    url: z.url(),
+});
+/**
+ * A possible duplicate the engine holds as review task `unique:<ruleId>` (1.24.0), from its
+ * `pendingTaskDetails`. `score` is the duplicate lane's similarity in basis points. `prior` is the
+ * earlier claim, never its answers or submitter: its `outcome` is this oracle's decision on it
+ * (null when it has none); `claimId`, `submittedAt` and the earlier claim's matched `files` only
+ * when it is the SAME source's claim, under the same protocol.
+ */
+const ReviewDuplicate = z.object({
+    taskId: z.string().min(1),
+    ruleId: z.string().min(1),
+    score: z.number().int().min(0).max(10_000).optional(),
+    prior: z.object({
+        outcome: Verdict.nullable(),
+        claimId: ClaimId.optional(),
+        submittedAt: Timestamp.optional(),
+        files: z.array(ReviewFile).optional(),
+    }),
+});
+export const ReviewView = z.object({
+    claimId: ClaimId,
+    protocolDid: ProtocolDid,
+    /** The `resultDigest` being reviewed — send it back as `answeredAgainst`. */
+    resultDigest: z.string().min(1),
+    pendingTasks: z.array(ReviewTask),
+    answers: z.record(z.string(), z.unknown()),
+    files: z.array(ReviewFile),
+    submittedAt: Timestamp,
+    /** The record's `review.answerBy` (contracts v1.3.1): past it, the view still serves the claim
+     *  but an answer is refused `409 REVIEW_EXPIRED`. */
+    answerBy: Timestamp.nullable(),
+    /** Whether the CALLER can answer (1.15.0): the console disables the form when it cannot. */
+    canAnswer: CanAnswer,
+    /** The record's `decision.erroredFacts` (1.20.0): which facts errored and why — omitted when
+     *  none did. */
+    erroredFacts: z.array(ErroredFact).min(1).optional(),
+    /** One per pending `unique:<ruleId>` task the engine detailed (1.24.0) — omitted when none. */
+    duplicates: z.array(ReviewDuplicate).min(1).optional(),
+});
+/** The engine's decision report in JSON (`Accept: application/json`), proxied as-is — LOOSE
+ *  because its body is the engine's to grow; only the keys a client joins on are pinned. */
+export const DecisionReport = z.looseObject({
+    claimId: RecordClaimId,
+    verdict: Verdict.nullable(),
+});
+// --- uploads (§4.2, §6.2) --------------------------------------------------------------------------
+/** `url` is a short-lived signed read (`/v1/api/files/:uploadId?exp=&sig=`) for a person to look at
+ *  the file, never a public object; a claim references the file by `uploadId`. */
+export const Upload = z.object({
+    /** Put this in `attachments[].uploadId`. */
+    uploadId: UploadId,
+    url: z.url(),
+    cid: z.string().min(1),
+    mediaType: z.string().min(1),
+    size: z.int().min(0).max(MAX_UPLOAD_BYTES),
+});
+/**
+ * v1.7: a one-use, signed `PUT` for a client that must not hold the API key (an AI app's sandboxed
+ * widget). `uploadUrl` is the whole credential — `PUT` the bytes to it with no `Authorization`
+ * before `expiresAt`, and the answer is the same `Upload` as `PUT /v1/api/uploads`, under this
+ * `uploadId`. `GET /v1/api/uploads/{uploadId}` reads it back once used.
+ */
+export const UploadLink = z.object({
+    uploadId: UploadId,
+    uploadUrl: z.url(),
+    expiresAt: Timestamp,
+});
+// --- protocols (§4.2) ------------------------------------------------------------------------------
+/** `price: null` — this oracle publishes no price for the protocol (contract v1.1.1): nothing is
+ *  offered for it, and the facilitator refuses any offer that names it. */
+export const ProtocolSummary = z.object({
+    protocolDid: ProtocolDid,
+    name: z.string().nullable(),
+    price: Price.nullable(),
+});
+export const ProtocolList = z.object({ items: z.array(ProtocolSummary) });
+export const FileQuestion = z.object({
+    question: z.string().min(1),
+    required: z.boolean(),
+    mediaTypes: z.array(z.string().min(1)),
+    maxBytes: z.int().min(1).max(MAX_UPLOAD_BYTES),
+});
+/**
+ * The work order a CALLER needs (§4.2): what to send, and what will happen to it. Facts are NAMES
+ * only — the engine's manifest carries endpoints, audiences and AI instructions that are the
+ * oracle's business, not the customer's.
+ */
+export const ProtocolWorkOrder = z.object({
+    protocolDid: ProtocolDid,
+    name: z.string().nullable(),
+    rubricId: z.string().min(1),
+    /** JSON Schema (2020-12) for `answers`, derived from the protocol's claim form. */
+    answers: z.record(z.string(), z.unknown()),
+    files: z.array(FileQuestion),
+    facts: z.object({
+        ext: z.array(z.string()),
+        ai: z.array(z.string()),
+        unique: z.boolean(),
+        frequency: z.boolean(),
+    }),
+    reviewTasks: z.array(ReviewTask),
+    /** Null when no price is published for the protocol (v1.1.1), as in `ProtocolSummary`. */
+    price: Price.nullable(),
+    example: SubmitClaimRequest,
+});
+// --- the source and its console (§3, §6.1, §12.2) ----------------------------------------------------
+/** One allowed protocol. The price is the oracle's published one (payments spec §3.1) — no
+ *  per-source prices (owner, v1.1): a partner who should not pay gets billing mode `none`. */
+export const AllowedProtocol = z.object({ protocolDid: ProtocolDid });
+export const Source = z.object({
+    sourceId: SourceId,
+    name: z.string().min(1),
+    /** The IXO account that created the source (a controller of its organisation then): the deed
+     *  whose PAY the facilitator reads (§11). Not a root — the organisation's controllers are. */
+    ownerDid: AccountDid,
+    status: SourceStatus,
+    /** Null exactly while `status` is `active`. */
+    pausedReason: SourcePausedReason.nullable(),
+    billingMode: BillingMode,
+    allowedProtocols: z.array(AllowedProtocol),
+    refillFloorCents: z.int().min(0).nullable(),
+    defaultWebhookUrl: z.url().nullable(),
+    contactEmail: z.email().nullable(),
+    /** v1.8 — the organisation (its on-chain entity) this source belongs to, from creation, never
+     *  null (D10): its current controllers administer the source. */
+    companyEntityDid: EntityDid,
+    /** v1.7 — the answer field the organisation's link names as a claim's payee when no `submitter`
+     *  is sent; null until the source is `active`. */
+    payeeField: z.string().nullable(),
+    createdAt: Timestamp,
+    /** 1.17.0 — when the company sync first made it `active` (set once, never cleared); null while it
+     *  has never been active, so a `pending-link` or `disputed` source with null never held claims. */
+    activatedAt: Timestamp.nullable(),
+});
+/** Sign-up (§12.3, D10): a current controller of `entityDid` adds this oracle to the organisation.
+ *  The source starts `pending-link`; the invoker pays (`ownerDid`) but holds no membership — as a
+ *  controller it is root already. */
+export const CreateSourceRequest = z.strictObject({
+    name: z.string().min(1).max(128),
+    contactEmail: z.email(),
+    /** v1.8 (D10): the organisation — the invoker must be a current controller of it. */
+    entityDid: EntityDid,
+});
+/**
+ * Where a member stands: `invited` (an email invite nobody has accepted), `accepted` (an account
+ * joined, no grant uploaded yet — it can call nothing), `active` (a live grant), `expired`,
+ * `revoked`. The owner is always `active`: the root needs no grant.
+ */
+export const MemberStatus = z.enum(["invited", "accepted", "active", "expired", "revoked"]);
+export const Member = z.object({
+    memberId: MemberId,
+    /** Null until an email invite is accepted by a signed-in IXO account. */
+    did: AccountDid.nullable(),
+    email: z.email().nullable(),
+    /** The preset the grant was made as (§3.4). */
+    role: MemberRole,
+    status: MemberStatus,
+    /** What the live grant allows — the role's preset; empty until a grant is uploaded. */
+    capabilities: z.array(Capability),
+    /** `nb.protocols` of the grant: the protocols its `claims/*` are narrowed to; null = all. */
+    protocols: z.array(ProtocolDid).nullable(),
+    expiresAt: Timestamp.nullable(),
+    /** The CID of the owner's signed delegation — what a revocation lists. */
+    delegationCid: z.string().nullable(),
+    revokedAt: Timestamp.nullable(),
+    /** The browser-generated key whose attestations this oracle accepts from this member (§10). */
+    reviewerDid: ReviewerDid.nullable(),
+    /** v1.7 — when the member's own `reviewerDid` delegation expires; null when none is uploaded. */
+    reviewerDelegationExpiresAt: Timestamp.nullable(),
+    /** The member's own switch for review emails (§10.1); the room follows its own mute. */
+    notifyReviews: z.boolean(),
+    invitedAt: Timestamp,
+    acceptedAt: Timestamp.nullable(),
+});
+export const MemberList = z.object({ items: z.array(Member) });
+/** Returned once, on create and on rotation — never on a read. */
+const WebhookSecret = z.string().regex(/^whsec_[0-9A-Za-z]{32,}$/);
+/** `webhookSecret` signs deliveries to a claim's own `webhookUrl` and the source's default URL
+ *  (§4.5) — shown here once; `POST /v1/api/source/webhook-secret` rotates it. */
+export const CreateSourceResponse = z.object({
+    source: Source,
+    webhookSecret: WebhookSecret,
+});
+/** The old secret keeps signing beside the new one until `previousExpiresAt` (24 h). */
+export const RotateWebhookSecretResponse = z.object({
+    webhookSecret: WebhookSecret,
+    previousExpiresAt: Timestamp,
+});
+/**
+ * `GET /v1/api/sources` — the signed-in account's sources on THIS oracle (the console asks every
+ * oracle it lists). `delegation` is the member's stored grant (base64 CAR), which the console
+ * attaches as its invocation's proof; null for the owner, and until a grant is uploaded.
+ */
+export const MySource = z.object({
+    source: Source,
+    memberId: MemberId,
+    role: MemberRole,
+    status: MemberStatus,
+    capabilities: z.array(Capability),
+    protocols: z.array(ProtocolDid).nullable(),
+    expiresAt: Timestamp.nullable(),
+    delegation: z.string().nullable(),
+    delegationCid: z.string().nullable(),
+});
+export const MySourceList = z.object({ items: z.array(MySource) });
+/**
+ * `GET /v1/api/organisations/{entityDid}/sources` query (1.17.0): the organisation's sources on this
+ * oracle in every state, keyset-paged (`SourcePage`), for a current controller of the entity only.
+ */
+export const ListOrganisationSourcesQuery = z.object({
+    limit: z.coerce.number().int().min(1).max(MAX_PAGE_LIMIT).default(100),
+    cursor: z.string().max(1024).optional(),
+});
+/**
+ * `POST /v1/api/sources/{sourceId}/company/sync` (v1.8): the source as mirrored from the engine's
+ * stored link for its organisation, and its members.
+ */
+export const CompanySyncResponse = z.object({ source: Source, members: z.array(Member) });
+/** An invite names the role the owner will grant; the grant itself is `PUT …/delegation`. An
+ *  invite by `did` is accepted at once (the account exists); by `email` it waits for `accept`.
+ *  `owner` here makes a CO-owner: a grant of `source/*`, revocable like any other — the source's
+ *  roots stay its organisation's current controllers (D10); `ownerDid`, the creator who pays, is
+ *  not one. */
+export const InviteMemberRequest = z
+    .strictObject({
+    email: z.email().optional(),
+    did: AccountDid.optional(),
+    role: MemberRole,
+})
+    .refine((b) => b.email !== undefined || b.did !== undefined, {
+    message: "an invite names an email or a did",
+});
+/** `inviteToken` is shown once (an email invite only); the console turns it into the link. */
+export const InviteMemberResponse = Member.extend({
+    inviteToken: z
+        .string()
+        .regex(/^inv_[0-9A-Za-z]{32,}$/)
+        .nullable(),
+});
+/** `POST /v1/api/members/accept` — the invoking account becomes that member. */
+export const AcceptInviteRequest = z.strictObject({
+    inviteToken: z.string().regex(/^inv_[0-9A-Za-z]{32,}$/),
+});
+/**
+ * `PUT /v1/api/members/:memberId/delegation` — the owner's signed grant (§3.4 step 3), base64 of
+ * the delegation CAR. Checked before it is stored: issued by the owner (or a co-owner holding
+ * `source/*` from the owner), to this member's DID, over this source's resource, capabilities
+ * EXACTLY the role's preset, not expired. Replacing a grant revokes the previous one.
+ */
+export const GrantMemberRequest = z.strictObject({
+    delegation: z
+        .string()
+        .min(16)
+        .max(65536)
+        .regex(/^[A-Za-z0-9+/_-]+={0,2}$/),
+    role: MemberRole,
+});
+/**
+ * A member's own settings: their reviewer key (§10) and their review-email switch (§10.1).
+ * Registering a key needs `reviewerProof`: a compact JWS signed by THAT did:key over `{ memberId,
+ * sourceId, reviewerDid, iat }` — proof of possession, so a stolen console session cannot enrol a
+ * key it does not hold (§14). Clearing it (`null`) needs none. A field left out is left alone. A
+ * role change is a revoke plus a new grant, never a PATCH.
+ */
+export const UpdateMemberRequest = z
+    .strictObject({
+    reviewerDid: ReviewerDid.nullable().optional(),
+    reviewerProof: CompactJws.optional(),
+    notifyReviews: z.boolean().optional(),
+})
+    .refine((b) => (typeof b.reviewerDid === "string") === (b.reviewerProof !== undefined), {
+    message: "reviewerProof is required with a reviewerDid, and only then",
+})
+    .refine((b) => b.reviewerDid !== undefined || b.notifyReviews !== undefined, {
+    message: "name a reviewerDid or notifyReviews",
+});
+/** A key as every read shows it: the prefix, never the secret (§3.3 — shown once, at create). */
+export const ApiKey = z.object({
+    prefix: KeyPrefix,
+    name: z.string().nullable(),
+    /** `eo_live_7f3a9c1d_…` — what the console prints. */
+    masked: z.string().regex(/^eo_(live|test)_[0-9a-z]{8}_\u2026$/),
+    environment: z.enum(["live", "test"]),
+    scopes: z.array(Scope).min(1),
+    maxSpendCentsPerDay: z.int().min(1).nullable(),
+    createdAt: Timestamp,
+    lastUsedAt: Timestamp.nullable(),
+    /** Future while a rotation's grace period runs (`DELETE …?graceDays=`); the key works until then. */
+    revokedAt: Timestamp.nullable(),
+});
+export const KeyList = z.object({ items: z.array(ApiKey) });
+export const CreateApiKeyRequest = z.strictObject({
+    name: z.string().min(1).max(64).optional(),
+    scopes: z.array(Scope).min(1).max(3),
+    maxSpendCentsPerDay: z.int().min(1).optional(),
+});
+/** `DELETE /v1/api/keys/:prefix` — `graceDays` > 0 lets a rotation overlap (§3.3: up to 30 days). */
+export const RevokeApiKeyQuery = z.object({
+    graceDays: z.coerce.number().int().min(0).max(30).default(0),
+});
+/** The only response that ever carries the full key. */
+export const CreateApiKeyResponse = ApiKey.extend({
+    key: z.string().regex(/^eo_(live|test)_[0-9a-z]{8}_[0-9A-Za-z]{32,}$/),
+});
+/** A source's settings (§12.2 Settings). The allow-list and the billing mode are the operator's
+ *  (`/v1/api/admin/sources/:id/…`), because they are commercial terms. */
+export const SourceSettings = z
+    .strictObject({
+    name: z.string().min(1).max(128).optional(),
+    defaultWebhookUrl: HttpsUrl.nullable().optional(),
+    contactEmail: z.email().optional(),
+    refillFloorCents: z.int().min(0).nullable().optional(),
+})
+    .refine((b) => Object.keys(b).length > 0, { message: "nothing to update" });
+export const AuditEntry = z.object({
+    id: AuditId,
+    /** Null for an action on no one source (an operator's cross-source change). */
+    sourceId: SourceId.nullable(),
+    /** Who: a member's DID, an API key's prefix, an operator's DID, or — `system` — the oracle's own
+     *  scheduled job as `system:<job>` (e.g. `system:link-recheck` dropping a linked collection).
+     *  `oauth` (1.4.6): a user (`id`, their DID) acting through an AI app connected to the oracle's
+     *  MCP server over OAuth — `clientId` and `clientName` name the app, as AuthHub registered it. */
+    actor: z.object({
+        kind: z.enum(["member", "key", "operator", "system", "oauth"]),
+        id: z.string().min(1),
+        clientId: z.string().optional(),
+        clientName: z.string().optional(),
+    }),
+    /** Dotted verb, e.g. `key.created`, `member.role_changed`, `claim.body_erased`. */
+    action: z.string().min(1),
+    target: z.string().nullable(),
+    at: Timestamp,
+    details: z.record(z.string(), z.unknown()).nullable(),
+});
+export const AuditPage = keysetPage(AuditEntry);
+// --- webhooks management (§4.5) ----------------------------------------------------------------------
+/** Appendix B. Declared here, not in webhooks.ts, because endpoints subscribe to them and the
+ *  envelope there carries `ClaimRecord` — one direction of import, no cycle. */
+export const WebhookEventType = z.enum([
+    "claim.accepted",
+    "claim.decided",
+    "claim.review_required",
+    "claim.folded",
+    "claim.unusable",
+    "claim.failed",
+    /** contracts v1.3.1: a paid claim's review closed unanswered at `review.answerBy` — unpaid. */
+    "claim.review_expired",
+    "source.paused",
+    "source.resumed",
+    "payment.settled",
+    "balance.low",
+]);
+/** An endpoint's subscriptions; `[]` = every event, including types added later. */
+const Subscriptions = z.array(WebhookEventType);
+export const WebhookEndpoint = z.object({
+    endpointId: EndpointId,
+    url: z.url(),
+    events: Subscriptions,
+    enabled: z.boolean(),
+    createdAt: Timestamp,
+});
+export const EndpointList = z.object({ items: z.array(WebhookEndpoint) });
+export const CreateWebhookEndpointRequest = z.strictObject({
+    url: HttpsUrl,
+    events: Subscriptions,
+});
+export const CreateWebhookEndpointResponse = WebhookEndpoint.extend({ secret: WebhookSecret });
+export const UpdateWebhookEndpointRequest = z
+    .strictObject({
+    url: HttpsUrl.optional(),
+    events: Subscriptions.optional(),
+    enabled: z.boolean().optional(),
+    /** Issue a new secret; the old one keeps verifying for 24 h so receivers can roll over. */
+    rotateSecret: z.literal(true).optional(),
+})
+    .refine((b) => Object.keys(b).length > 0, { message: "nothing to update" });
+/** `secret` present iff the PATCH rotated it. */
+export const UpdateWebhookEndpointResponse = WebhookEndpoint.extend({
+    secret: WebhookSecret.optional(),
+});
+export const WebhookDelivery = z.object({
+    id: DeliveryId,
+    eventId: EventId,
+    type: WebhookEventType,
+    status: DeliveryStatus,
+    attempts: z.int().min(0).max(8),
+    lastStatusCode: z.int().nullable(),
+    nextAttemptAt: Timestamp.nullable(),
+    createdAt: Timestamp,
+});
+export const DeliveryPage = keysetPage(WebhookDelivery);
+/**
+ * `GET /v1/api/webhooks/deliveries/:deliveryId` — one delivery with what was sent. Only the LAST
+ * attempt's outcome is kept (v1.1); the envelope is null once the claim's body retention erased it.
+ */
+export const WebhookDeliveryDetail = WebhookDelivery.extend({
+    /** Null for a claim's own `webhookUrl` or the source's default URL. */
+    endpointId: EndpointId.nullable(),
+    /** Where it was posted; null once the claim's body retention erased it (a webhook URL is
+     *  personal data, §6.3), like the envelope. */
+    targetUrl: z.url().nullable(),
+    request: z.object({ body: z.unknown().nullable() }),
+    lastError: z.string().nullable(),
+});
+// --- linked collections (S3 M6) ----------------------------------------------------------------------
+/** An on-chain claim collection id (a uint64, as the chain and Blocksync print it). */
+export const CollectionId = z.string().regex(/^[0-9]{1,20}$/);
+/**
+ * An on-chain collection the source has linked: its chain claims then read with the source's own.
+ * `linkedBy` is either a member who owns the collection entity on chain (company authority D9) —
+ * re-checked hourly; a link whose linker no longer owns it is dropped — or (1.21.0) the source's
+ * own `companyEntityDid`, for a link the oracle made at the collection's registration because the
+ * engine names that organisation as the collection's company — re-checked hourly against the
+ * engine, dropped when it no longer does. Only a drop hides a link (1.23.0): a re-check that cannot
+ * read the chain or the engine keeps it in the reads. Billing stays the collection owner's on-chain evaluation
+ * payment: never a 402 here.
+ */
+export const LinkedCollection = z.object({
+    collectionId: CollectionId,
+    protocolDid: ProtocolDid,
+    linkedBy: z.union([AccountDid, EntityDid]),
+    linkedAt: Timestamp,
+});
+export const LinkedCollectionList = z.object({ items: z.array(LinkedCollection) });
+export const LinkCollectionRequest = z.strictObject({ collectionId: CollectionId });
+// --- me (§4.2, §12.3) ------------------------------------------------------------------------------
+/**
+ * The source owner's balance — the deed of `ownerDid`, not of whichever live member paid a given
+ * offer — as the facilitator sees it (`GET /v1/balances`, payments spec §5.3), base units
+ * of `upay` (1 upay = 1 micro-USD): `balance` in the deed, `sendLimit` left on the send permission
+ * (null = no permission granted yet), `reserved` for claims awaiting their receipt, `settled` on a
+ * receipt and not yet transferred, `paying` in the transfer under way, `available` = what a new
+ * reservation may take (contracts v1.3; was `held` / `spent`).
+ */
+export const Credits = z.object({
+    asset: z.literal("upay"),
+    balance: BaseUnitAmount,
+    sendLimit: BaseUnitAmount.nullable(),
+    reserved: BaseUnitAmount,
+    settled: BaseUnitAmount,
+    paying: BaseUnitAmount,
+    available: BaseUnitAmount,
+});
+// --- review billing (1.22.0: per-review checker billing for chain claims) -------------------------
+/**
+ * A source's standing review-billing delegation (while IXO's plan lets the oracle bill reviews): the x402-ixo-pay
+ * payment delegation (base64 CAR, one `billing/pay` on `billing:decision-api` to the facilitator,
+ * `nb: { maxAmount, denom: "upay", oracles: [<this oracle's did:web>] }`, an `exp`, no proofs, no
+ * facts) its organisation's CURRENT chain owner signed. It pays for every review of the
+ * organisation's chain collections' claims, from the owner's subscription credits.
+ */
+export const SetReviewBillingRequest = z.strictObject({
+    delegation: z.string().min(1).max(16_384),
+});
+/**
+ * `active`; `expired` past its `exp`; `exhausted` when what is left of `maxAmount` covers no
+ * review; `payer_not_owner` when its signer is no longer the organisation's chain owner.
+ */
+export const ReviewBillingState = z.enum(["active", "expired", "exhausted", "payer_not_owner"]);
+/**
+ * Why a collection's reviews are paused: `payer-credits` — the payer's credits (or the send
+ * permission behind them) do not cover a review: top up; `payer-delegation` — no usable delegation
+ * (none, expired, used up, its signer no longer the owner): store a new one.
+ */
+export const PayerPausedReason = z.enum(["payer-credits", "payer-delegation"]);
+/**
+ * The stored delegation as the Console reads it — never the token. `spent` / `remaining` are this
+ * oracle's own count against `maxAmount` (the facilitator exposes none; the delegation is bound to
+ * this oracle alone, so the two agree); `credits` the payer's balance at the facilitator, null until
+ * it answers this oracle (after the first review is reserved).
+ */
+export const ReviewBilling = z.object({
+    sourceId: SourceId,
+    state: ReviewBillingState,
+    payer: AccountDid,
+    delegationCid: z.string().min(1),
+    maxAmount: BaseUnitAmount,
+    spent: BaseUnitAmount,
+    remaining: BaseUnitAmount,
+    expiresAt: Timestamp,
+    credits: Credits.nullable(),
+    pricePerReview: z.array(z.object({ protocolDid: ProtocolDid, amount: BaseUnitAmount, amountCents: z.int().min(0) })),
+    pausedCollections: z.array(z.object({ collectionId: CollectionId, reason: PayerPausedReason, since: Timestamp })),
+    createdBy: AccountDid,
+    createdAt: Timestamp,
+    updatedAt: Timestamp,
+});
+/** `DELETE`'s answer: whether a delegation was held, and what a full stop takes. */
+export const ReviewBillingDeleted = z.object({ deleted: z.boolean(), message: z.string() });
+export const Limits = z.object({
+    maxBodyBytes: z.int(),
+    maxUploadBytes: z.int(),
+    maxBatchClaims: z.int(),
+    maxWaitSeconds: z.int(),
+    maxConcurrentWaiters: z.int(),
+    maxPageLimit: z.int(),
+});
+/** Who is asking — the console resolves its API-developer role from this (§12.3). */
+export const Caller = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("key"), prefix: KeyPrefix, scopes: z.array(Scope) }),
+    z.object({
+        kind: z.literal("member"),
+        memberId: MemberId,
+        did: AccountDid,
+        role: MemberRole,
+        capabilities: z.array(Capability),
+        protocols: z.array(ProtocolDid).nullable(),
+    }),
+    /** v1.8 (D10) — a current controller of the source's organisation, invoking as root with no
+     *  membership: every capability. */
+    z.object({ kind: z.literal("controller"), did: AccountDid, capabilities: z.array(Capability) }),
+]);
+/**
+ * Least exposure (§14): `members` (emails, DIDs) only to a console member — never to an API key;
+ * `keys` to a key or a member with `keys/manage`; `webhookEndpoints` to a key with
+ * `webhooks:manage` or a member with `webhooks/manage`; `credits` to a key or a member with
+ * `spend/read`. `credits` is the source owner's balance (another live member who pays an offer
+ * has their own, not shown here); null when the source pays nothing here (billing mode `none`,
+ * payments off) or the facilitator could not be read.
+ */
+export const Me = z.object({
+    caller: Caller,
+    source: Source,
+    members: z.array(Member).optional(),
+    keys: z.array(ApiKey).optional(),
+    credits: Credits.nullable().optional(),
+    limits: Limits,
+    webhookEndpoints: z.array(WebhookEndpoint).optional(),
+    /** Why the caller can answer no review on this source (1.15.0, `ReviewBlock`); null when it can. */
+    reviewBlocked: ReviewBlock.nullable(),
+});
+// --- operator (§12.2 "operator view") ----------------------------------------------------------------
+export const SourcePage = keysetPage(Source);
+export const PauseSourceRequest = z.strictObject({ note: z.string().max(1024).optional() });
+/** Replaces the allow-list whole — a PUT, so the console's form is the truth. */
+export const SetSourceProtocolsRequest = z.strictObject({
+    protocols: z.array(z.strictObject({ protocolDid: ProtocolDid })),
+});
+/** `PUT /v1/api/admin/sources/:sourceId/billing-mode` — operators only, never the source's members. */
+export const SetBillingModeRequest = z.strictObject({ billingMode: BillingMode });
+/**
+ * `GET /v1/api/admin/facilitator-delegation` (contracts v1.4.1): S10's card facilitator
+ * (`ixo-pay-facilitator`) trusts this oracle's did:web as its root for operator actions, so an
+ * operator reaches it with a delegation the oracle signs — one capability per requested action
+ * (never `*`, never the retired `operators/manage`), no `nb`, to the operator's own did:ixo, at
+ * most an hour. Minted fresh every call (a nonce each), never cached.
+ */
+export const FACILITATOR_RESOURCE = "ixo:ixo-pay-facilitator";
+export const FACILITATOR_DELEGATION_MAX_TTL_SEC = 3600;
+/** The facilitator's operator actions (S10), in the order a delegation lists them. */
+export const FacilitatorAction = z.enum([
+    "operators/onboard",
+    "operators/read",
+    "operators/refund",
+    "operators/evidence",
+]);
+export const FacilitatorDelegationQuery = z.object({
+    /** Comma-separated, deduplicated, put in `FacilitatorAction` order; absent ⇒ all four. */
+    actions: z
+        .string()
+        .optional()
+        .transform((raw, ctx) => {
+        if (raw === undefined)
+            return [...FacilitatorAction.options];
+        const asked = new Set(raw.split(",").map((a) => a.trim()));
+        const unknown = [...asked].filter((a) => !FacilitatorAction.safeParse(a).success);
+        if (unknown.length > 0) {
+            // A `payouts/*` ask is a Console still on the retired payout grant (CA-M8): say where it went.
+            const payouts = unknown.some((a) => a.startsWith("payouts/"))
+                ? " Payout access is not granted here: the payouts facilitator's own team (its company's admins) grants it."
+                : "";
+            ctx.addIssue({
+                code: "custom",
+                message: `${unknown.map((a) => (a === "" ? "(empty)" : a)).join(", ")} is not a facilitator action. Ask for one or more of ${FacilitatorAction.options.join(", ")}, separated by commas.${payouts}`,
+            });
+            return z.NEVER;
+        }
+        return FacilitatorAction.options.filter((a) => asked.has(a));
+    }),
+    ttl: z.coerce.number().int().min(60).max(FACILITATOR_DELEGATION_MAX_TTL_SEC).default(3600),
+});
+export const FacilitatorCapability = z.object({
+    with: z.literal(FACILITATOR_RESOURCE),
+    can: FacilitatorAction,
+});
+export const FacilitatorDelegation = z.object({
+    /** A UCAN delegation as a base64 CAR — the same encoding as a console role grant. */
+    delegation: z.string().min(1),
+    /** `did:web:<ORACLE_HOSTNAME>`, signed with the key `/.well-known/did.json` publishes. */
+    issuer: z.string().startsWith("did:web:"),
+    /** The invoking operator's did:ixo. */
+    audience: AccountDid,
+    /** Exactly the delegation's `att`: one per requested action. */
+    capabilities: z.array(FacilitatorCapability).min(1),
+    expiresAt: Timestamp,
+});
+// --- export (§6.3) -----------------------------------------------------------------------------------
+/** The source's personal data (claim bodies, metadata, members, endpoints, the list of uploaded files,
+ *  the webhook delivery log, review answers) as one archive, behind a short-lived signed URL
+ *  — the export route §6.3 promises. */
+export const DataExport = z.object({ url: z.url(), expiresAt: Timestamp });
+//# sourceMappingURL=api.js.map