@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/workflows/claim-ingest.js

@@ -0,0 +1,1020 @@
+/**
+ * Durable, idempotent claim ingestion (README "How a claim flows" steps 3–6). One instance per claim — the
+ * instance id is the claimId itself when Cloudflare accepts it, else its sha256 (see lib/ids.ts) —
+ * each step checkpointed and auto-retried, so a crash/redeploy/transient failure never re-does
+ * work or drops a claim.
+ *
+ * THE WORKFLOW OWNS ITS LEDGER ROW — one writer, whole lifecycle:
+ *   step "record-queued"   → upsert the `claim_ingests` row as `queued` (durable: the row exists
+ *                            iff the instance started, so nothing can ever strand a row)
+ *   step "evaluate"        → mark the row `processing` (so a later attempt knows one ran), then
+ *                            ONE pull (chain metadata + body + attachment descriptors), the facts
+ *                            lane over the same in-memory claim (`buildFacts`: read the engine's
+ *                            rubric manifest, run the producer, freeze the FactSet), and `POST /v1/decisions` on
+ *                            the eval engine with that FactSet and the claim's content (the
+ *                            pull's `claimContent`: a chain claim's CID-verified bytes, an API
+ *                            claim's stored content) → one `decisions` row
+ *                            (`onConflictDoNothing` — decided once, matching the engine's own
+ *                            evaluated-once mutex). ONE step on purpose, exactly as the engine
+ *                            folded its pull into `evaluate`: the
+ *                            claim body and the FactSet — which CONTAINS the answers — may never
+ *                            be a step result, so pull → facts → decide has to live and die
+ *                            inside one step; only the small decision summary leaves it. A claim
+ *                            the facts lane cannot build for (a rubric the engine's manifest cannot
+ *                            bind, facts that don't match the rubric's work order) gets its row
+ *                            WITHOUT a decide call — nothing to decide, nothing charged
+ *   step "act"             → act on a terminal verdict (chain-write under the AUTO_SIGN policy;
+ *                            workflows/steps.ts). Fail-soft: a delivery failure NEVER fails the
+ *                            ingest — the decision is recorded, and an operator rerun re-enters
+ *                            delivery idempotently. A `pending_review` decision waits for the
+ *                            review lane (routes/v1/reviews.ts → ReviewComplete) to act instead
+ *   step "mark-processed"  → row → `processed`
+ *   terminal catch         → row → `failed` (+ the message), instance shows Errored in the dashboard
+ * The cron (cron/) only discovers claims and creates instances; it never writes this table.
+ *
+ * The engine's answers that are not "here is the decision" (docs/ENGINE-CONTRACT.md "Errors")
+ * are routed, not retried blindly: not hired for the collection ⇒ pause it and stop; credits
+ * exhausted ⇒ pause EVERY watched collection, alert, and keep retrying this claim (cheap — the
+ * engine returns the stored row once decided); a rubric pin the chain has since re-anchored ⇒
+ * invalidate the cached manifest, re-read and rebuild once; a facts shape the engine refuses ⇒
+ * our producer's bug, fail loudly. And the "no" that is not an error: an UNUSABLE rubric — said
+ * by the engine's manifest before a producer runs (`rubric-unusable` from the builder: no `#rub`,
+ * swapped bytes, a drifted `#vct`, an unbindable ref), or by `decision.status = "unusable"` at
+ * decide time (fact coverage; the oracle never pre-binds, the engine's
+ * binder is the only validator of rubric ⇄ form ⇄ facts). Both are recorded (the engine's with its
+ * receipt) AND pause the collection: every claim of it would be refused the same way, so a broken
+ * catalog entry is paid for once — or, from the manifest, not at all. `POST
+ * /v1/collections/:id/resume` lifts it once `#rub`/`#vct` are fixed.
+ *
+ * Replay safety: a step's checkpointed result is returned verbatim on replay and the body of a
+ * completed step never re-runs, so a step may only depend on its own inputs, the DB, and the small
+ * results of earlier steps — never on in-memory state another step built. A retry that re-enters
+ * `evaluate` after its row landed reads the row and returns: no second pull, no second connector
+ * run (AI charges), no second ask. A retry that re-enters in the window BETWEEN the engine
+ * deciding and that row landing finds the row marked `processing` and asks `GET
+ * /v1/decisions/:claimId` first (docs/ENGINE-CONTRACT.md "Auth + preconditions"): decided-once on
+ * the engine plus one extra read on retry ⇒ the producer never runs twice for one claim, and no
+ * claim is stranded. A first attempt never pays that read.
+ *
+ * Self-contained BY DESIGN so operator recovery is just the dashboard: RERUN an errored instance
+ * (params are retained) and the ledger converges. Hand-creating a new instance also works with the
+ * claim CID as the id and no params (the id doubles as the claimId; the collection is resolved
+ * on-chain); only hash-mapped claims (rare non-CID ids) need `{"claimId": "…"}` as params.
+ *
+ * Two front doors, one workflow (Go Prod §7.1): `params.lane` picks the `ClaimSource`
+ * (workflows/claim-source.ts) — `chain` (absent: the cron's claims) or `api` (`startApiClaims`,
+ * whose body lives in D1 and whose decision is never acted on). The steps are the same for both.
+ *
+ * On the chain lane the claim body and attachment bytes are NOT persisted in D1 — attachments are Matrix CID
+ * references, and the `decisions` row stores only the engine's answer plus the FactSet digest. The
+ * one copy is the operator's opt-in answer archive (`ANSWERS_ARCHIVE`, lib/archive.ts), written to
+ * R2 from inside `evaluate` and never a step result.
+ *
+ * Per-review billing (IXO's plan for the oracle, payments/review-billing.ts): a chain claim of a
+ * collection registered with a paying source (`billingSourceId`) is never decided without a
+ * reservation. Inside `evaluate`, before the pull: a claim id the facilitator cannot key (not a
+ * base32 CIDv1) is recorded `skipped` (`unbillable-claim-id`) — no offer, no decide, no chain
+ * write, no pause — and who pays is resolved fresh (no usable delegation ⇒ pause
+ * `payer-delegation`). AFTER the facts lane built — so a facts-lane `unusable` / `invalid_facts`
+ * never spends the delegation's cap — the price is reserved (offer → verify); a refusal for want of
+ * credits pauses `payer-credits`. While a payer pause stands, a retry stops before the pull, like
+ * `engine-credits`. The decision settles on its receipt (an engine `unusable` included), a
+ * `pending_review` extends its hold, and a reserved claim that will never get a receipt (a rebuild
+ * that failed, an engine refusal, a run that gave up) is released.
+ */
+import { WorkflowEntrypoint } from "cloudflare:workers";
+import { NonRetryableError } from "cloudflare:workflows";
+import * as Sentry from "@sentry/cloudflare";
+import { and, eq, isNull } from "drizzle-orm";
+import { getDb } from "../db/client.js";
+import { apiCharges, apiClaims, claimIngests, decisions, watchedCollections, } from "../db/schema.js";
+import { claimErrorCode, FAILURE } from "../lib/api-lane/record.js";
+import { archiveAnswer } from "../lib/archive.js";
+import { createEngineClient } from "../lib/engine/client.js";
+import { EngineError, isManifestUnusable, } from "../lib/engine/types.js";
+import { AppError } from "../lib/errors.js";
+import { buildFacts, factDeps } from "../lib/facts/builder.js";
+import { factCacheDelete } from "../lib/facts/fact-cache.js";
+import { factsDigest } from "../lib/facts/factset.js";
+import { finalVerdictUpdate, registryVerdictToken, voidUndecidedUpdate, } from "../lib/facts/stock/unique-store.js";
+import { depsFromEnv } from "../lib/ixo/index.js";
+import { getClaimById } from "../lib/ixo/blocksync/index.js";
+import { peerCode, scopedStep, withMetrics } from "../lib/metrics.js";
+import { extendForReview } from "../lib/payments/extend.js";
+import { BILLING_PAUSES, CHAIN_CLAIM_ID, companyOf, planAllowsReviewBilling, releaseChainClaim, reserveChainClaim, resolvePayer, } from "../lib/payments/review-billing.js";
+import { settleClaim } from "../lib/payments/settle.js";
+import { payoutRequestFor } from "../lib/payouts.js";
+import { reportAlert, reportError } from "../lib/sentry.js";
+import { getOracle } from "../oracle.js";
+import { isChain, sourceFor } from "./claim-source.js";
+import { actStep, erroredFactsOf, pauseCollection, pauseForEngineCredits, pauseUnusable, RECEIPT_MISSING, reasonOf, requireReceipt, stepError, } from "./steps.js";
+// Light garbage guard for manually-created instances, NOT a format check: real chain claimIds are
+// CIDs *and* Matrix event ids (`$…`), so anything printable-ASCII of sane length is acceptable —
+// the chain lookup is the actual validation (unknown id → fail-closed 404).
+const CLAIM_ID_RE = /^[\x21-\x7e]{1,512}$/;
+/**
+ * How a review-billing trouble is told apart in the ledger's `error` (a run that gave up while its
+ * collection was paused for payment): the resume cron restarts exactly those.
+ */
+export const PAYER_BILLING = "payer-billing:";
+/** `evaluate`'s result for a claim a per-review collection cannot bill (see the header). */
+const UNBILLABLE = "unbillable";
+const isBillingPause = (reason) => BILLING_PAUSES.includes(reason ?? "");
+/** The facts lane's deterministic negatives → the `decisions.status` they are recorded as (schema.ts). */
+const BUILD_FAILURE_STATUS = {
+    "rubric-unusable": "unusable",
+    "invalid-facts": "invalid_facts",
+};
+/** The engine's refusals of the claim's content → the `decisions.status` they are recorded as. */
+const CONTENT_REFUSAL_STATUS = {
+    CONTENT_MISMATCH: "content_mismatch",
+    PAYLOAD_TOO_LARGE: "payload_too_large",
+};
+/**
+ * `403 NO_EVALUATE_GRANT` is retry-ONCE (docs/ENGINE-CONTRACT.md): the grant may have landed on
+ * chain seconds ago — the portal grants and registers in one flow — so wait about a block and ask
+ * again before calling it a real "not hired". In-step on purpose: the FactSet may not leave the
+ * step, so a step-level sleep would cost a full rebuild (connectors, AI charges). An object so a
+ * test can shorten it.
+ */
+export const GRANT_RETRY_DELAY = { ms: 30_000 };
+/** The evaluate step's retries (below) — its last attempt is the one that freezes outages (P0-7). */
+const EVALUATE_RETRY_LIMIT = 8;
+const resultOf = (row) => ({
+    status: row.status,
+    verdict: row.verdict,
+    resultDigest: row.resultDigest,
+    receiptCid: row.receiptCid,
+});
+export class ClaimIngest extends WorkflowEntrypoint {
+    async run(event, step) {
+        // Params may be absent when an operator hand-creates an instance whose id IS a claim CID; for
+        // hash-mapped ids params are required (see header).
+        const claimId = event.payload?.claimId ?? event.instanceId;
+        if (!CLAIM_ID_RE.test(claimId)) {
+            throw new NonRetryableError(`Invalid claimId ${JSON.stringify(claimId)}`);
+        }
+        // One traceId from accept (or the scan tick) through this run, the engine call and the
+        // webhook: the params carry the starter's trace (observability spec §3 "Correlation").
+        const deps = depsFromEnv(this.env, {
+            traceparent: event.payload?.traceparent,
+            requestId: event.payload?.requestId,
+            claimId,
+            instanceId: event.instanceId,
+            workflow: "claim-ingest",
+        });
+        // Ambient for the run AND inside every step callback (`scopedStep`), so the fetch client and
+        // the cache reads record into `deps.metrics`.
+        const scope = { metrics: deps.metrics, logger: deps.logger };
+        return withMetrics(scope, () => this.ingest(event, scopedStep(step, scope, "claim-ingest"), deps, claimId));
+    }
+    async ingest(event, step, deps, claimId) {
+        const lane = event.payload?.lane ?? "chain";
+        const source = sourceFor(lane, this.env, deps);
+        // `instrumentWorkflowWithSentry` auto-captures a throw out of any `step.do` — but with no tags,
+        // so that issue lands next to our explicit `reportError` one and is far less actionable. Tag the
+        // run's scope once here and BOTH carry the ids you need to chase a stuck claim.
+        Sentry.setTags({ claimId, instanceId: event.instanceId, workflow: "claim-ingest" });
+        // The ledger row never exists without its collection (schema.ts: NOT NULL) — known from the
+        // cron's params, or resolved on-chain for a hand-created instance inside `record-queued`.
+        let collectionId = event.payload?.collectionId;
+        try {
+            collectionId = await step.do("record-queued", async () => {
+                // An API claim's row was written at accept, scope id and all; a chain claim's collection
+                // is on-chain.
+                const resolved = collectionId ??
+                    (lane === "api"
+                        ? (await this.ledgerRow(claimId))?.collectionId
+                        : (await getClaimById(deps, claimId))?.collectionId);
+                if (!resolved)
+                    throw new NonRetryableError(`No ${lane} claim for id ${claimId}`);
+                await this.recordStatus(claimId, event, { status: "queued", collectionId: resolved, lane });
+                return resolved;
+            });
+            // The API lane's `accepted` (timeline + `claim.accepted`) — before the decision, off the
+            // submit's request path. Fail-soft like the notify step below.
+            if (!isChain(source)) {
+                await step
+                    .do("notify-accepted", {
+                    retries: { limit: 3, delay: "5 seconds", backoff: "exponential" },
+                    timeout: "1 minute",
+                }, () => source.after.notify(claimId))
+                    .catch((err) => {
+                    deps.logger.error("notify-accepted.failed", { claimId, detail: String(err) });
+                    reportError(err, { lane: "notify", step: "notify-accepted", claimId, collectionId });
+                });
+            }
+            // Pull + facts + decide in ONE step (see header). No decision ⇒ the ingest failed, so this
+            // step is NOT fail-soft — unlike `act` below. A deterministic negative (not watched, no
+            // claim, CID mismatch, a 4xx from the engine) is NonRetryable — don't burn retries on a real
+            // "no"; transient (503) falls through and the step retries.
+            const result = await step.do("evaluate", 
+            // Timeout: the pull (bot media ≤ 25 MB/file) + the ext/ai connector budgets (~30s each) +
+            // the engine round trip. Retries stretch over ~4 hours (1 min → 128 min doubling):
+            // exhausting them marks the ingest `failed` with NO re-queue from the cron, so the schedule
+            // must outlive a real Matrix/blocksync/engine outage, not just a blip. Hibernation between
+            // retries is free.
+            {
+                retries: { limit: EVALUATE_RETRY_LIMIT, delay: "1 minute", backoff: "exponential" },
+                timeout: "4 minutes",
+            }, 
+            // `ctx.attempt` is 1-indexed: attempt limit+1 is the last. On it an outage a handler (or a
+            // stock ext/AI lane) still reports freezes as the rubric's onError instead of retrying —
+            // bounded, so a claim is decided rather than failed for an outside service's outage.
+            async (ctx) => {
+                const finalAttempt = ctx !== undefined && ctx.attempt > (ctx.config?.retries?.limit ?? EVALUATE_RETRY_LIMIT);
+                try {
+                    return await this.evaluate(deps, source, claimId, finalAttempt);
+                }
+                catch (err) {
+                    throw stepError(err);
+                }
+            });
+            // Recorded `skipped` inside `evaluate`: nothing to act on, tell or mark.
+            if (result.status === UNBILLABLE)
+                return { claimId, ok: true, ...result };
+            // Only a `decided` row can act (chain-write.ts step 1); anything else would spend a step to
+            // log a skip. Off the checkpointed result, so a replay decides the same way.
+            if (source.after.act && result.status === "decided") {
+                await actStep(this.env, deps, step, {
+                    claimId,
+                    collectionId,
+                    instanceId: event.instanceId,
+                    workflow: "claim-ingest",
+                });
+            }
+            // The source's notify lane (chain: the Matrix review card) — its own step, NEVER inside
+            // `evaluate`: a step retry there would re-send. Self-contained and fail-soft like `act`
+            // above: the delivery has its own ledger (`matrix_deliveries`), and a dead receiver never
+            // fails an ingest. It no-ops when the claim's state has nothing to tell.
+            try {
+                await step.do("notify-review", {
+                    retries: { limit: 3, delay: "5 seconds", backoff: "exponential" },
+                    timeout: "1 minute",
+                }, () => source.after.notify(claimId));
+            }
+            catch (err) {
+                deps.logger.error("notify-review.failed", { claimId, detail: String(err) });
+                reportError(err, { lane: "notify", step: "notify-review", claimId, collectionId });
+            }
+            await step.do("mark-processed", async () => {
+                await this.recordStatus(claimId, event, {
+                    status: "processed",
+                    collectionId: collectionId,
+                });
+            });
+            return { claimId, ok: true, ...result };
+        }
+        catch (err) {
+            // Terminal failure — a deterministic negative or exhausted retries. Record it so the ledger
+            // never shows a dead claim as `queued`, then rethrow so the instance shows as Errored in the
+            // dashboard (where an operator can rerun it; see header). Best-effort: a DB hiccup here must
+            // not replace the real failure. No collection ⇒ `record-queued` itself failed and there is
+            // no row to mark.
+            if (collectionId) {
+                await this.recordStatus(claimId, event, {
+                    status: "failed",
+                    collectionId,
+                    error: err instanceof Error ? err.message : String(err),
+                }).catch(() => { });
+                // Dead, so the connector-result cache is gone too (fact-cache.ts) — best-effort, like the
+                // row above: a DB hiccup must not replace the real failure.
+                await factCacheDelete(getDb(this.env), claimId).catch(() => { });
+                // A review reserved for a claim that will now never get a receipt: free it (fail-soft).
+                if (isChain(source)) {
+                    await releaseChainClaim({ ...deps, db: getDb(this.env) }, claimId, "other");
+                }
+                // Never decided, so never evidence: its duplicate-registry rows stop blocking an honest
+                // resubmission of the same work (unique-store.ts `VOID_TOKEN`, P0-6). Best-effort too.
+                await voidUndecidedUpdate(getDb(this.env), { collectionId, claimId }).catch(() => { });
+                // The API lane owes the customer its `failed` (§5); the chain lane has no failure notice.
+                // Still best-effort — but a customer never hearing `failed` is worth an issue.
+                if (!isChain(source)) {
+                    await source.after.notify(claimId).catch((err) => {
+                        deps.logger.warn("notify-failed.failed", { claimId, detail: String(err) });
+                        // An issue, not a page (`reportAlert`): a notify failure is one claim's, and
+                        // Sentry's issue alert already fires when the lane as a whole starts failing.
+                        reportError(err, { lane: "notify", step: "notify-failed", claimId, collectionId });
+                    });
+                }
+            }
+            deps.metrics.count("ingest.terminal", 1, {
+                op: lane,
+                outcome: await this.failureClass(claimId, err),
+            });
+            reportError(err, {
+                lane: "ingest",
+                step: "terminal",
+                claimId,
+                collectionId,
+                instanceId: event.instanceId,
+            });
+            // The retries ran out with the engine still answering without a receipt: a final decision
+            // nobody can act on or pay out — a page, not an issue (steps.ts `requireReceipt`).
+            if (err instanceof Error && err.message.startsWith(RECEIPT_MISSING)) {
+                await reportAlert(deps, "engine.receipt-missing", { claimId, collectionId, code: RECEIPT_MISSING }, `engine.receipt-missing:${claimId}`);
+            }
+            throw err;
+        }
+    }
+    /**
+     * The evaluate step's body: pull → facts → decide → the `decisions` row. Reads the DB, not step
+     * results, so an operator rerun converges — and a retry that finds the row is done.
+     */
+    async evaluate(deps, source, claimId, finalAttempt = false) {
+        const db = getDb(this.env);
+        // In this order: what the ledger says about this step's history, then the `processing` mark
+        // for the NEXT attempt — written before anything is pulled or spent, so a crash anywhere below
+        // leaves it behind. (Not one `db.batch`: Drizzle's D1 batch throws on a relational read that
+        // finds no row.)
+        const ingest = await db.query.claimIngests.findFirst({
+            where: (t, { eq: eqOp }) => eqOp(t.claimId, claimId),
+        });
+        await db
+            .update(claimIngests)
+            .set({ status: "processing" })
+            .where(eq(claimIngests.claimId, claimId));
+        const existing = await db.query.decisions.findFirst({
+            where: (t, { eq: eqOp }) => eqOp(t.claimId, claimId),
+        });
+        if (existing)
+            return resultOf(existing);
+        const engine = createEngineClient({
+            config: deps.config,
+            logger: deps.logger,
+            trace: deps.trace,
+            cache: deps.cache,
+        });
+        // `processing` already set ⇒ a previous attempt of this step ran and died before its row
+        // landed — possibly AFTER the engine decided. Decided-once on the engine means a resend would
+        // only replay that stored row, so one read recovers it and the claim is never stranded: the
+        // engine is NOT asked to decide again below. A 404 means the engine never got that far: the
+        // normal path. A first attempt (`queued`) never pays the read.
+        if (ingest?.status === "processing") {
+            const recovered = await engine.getDecision(claimId);
+            if (recovered) {
+                deps.logger.info("evaluate.recovered", {
+                    claimId,
+                    collectionId: ingest.collectionId,
+                    status: recovered.decision.status,
+                    resultDigest: recovered.resultDigest,
+                    receiptCid: recovered.receipt?.cid ?? null,
+                });
+                if (!recovered.receipt && recovered.decision.status !== "pending_review") {
+                    // Since CA10 the GET mints a missing receipt or answers 503, so this is a contract
+                    // breach. Never recorded receipt-less (the receipt is the one credential act and the
+                    // payout spend), and never re-decided either: that would re-run the handlers' AI spend.
+                    // `requireReceipt` retries the step, whose next GET recovers it with its receipt.
+                    deps.logger.warn("evaluate.recovered-without-receipt", {
+                        claimId,
+                        collectionId: ingest.collectionId,
+                        status: recovered.decision.status,
+                    });
+                }
+                requireReceipt(recovered, "decision");
+                return this.recordRecovered(deps, source, db, engine, claimId, ingest.collectionId, recovered);
+            }
+        }
+        // Out of engine credits, every decide call 402s until the credits cron resumes the scope, so an
+        // attempt here would pull, build and PAY for its AI calls up to eight times only to be refused.
+        // One projected read instead, AFTER the two ledger reads above (a decided or recovered claim
+        // returns regardless): the step retries on its own backoff and spends nothing meanwhile.
+        const paused = ingest?.collectionId ? await source.pausedReason(ingest.collectionId) : null;
+        if (paused === "engine-credits") {
+            throw AppError.unavailable(`${source.lane === "chain" ? "collection" : "source"} paused for engine credits — not pulling ${claimId}`);
+        }
+        // The same for a review nobody can pay for yet: the payer's fix, resumed by the payer cron.
+        if (isBillingPause(paused)) {
+            throw AppError.unavailable(`${PAYER_BILLING} collection paused ${paused} — not pulling ${claimId}`);
+        }
+        const billing = isChain(source) && ingest?.collectionId
+            ? await this.billingFor(deps, source, db, claimId, ingest.collectionId)
+            : null;
+        if (billing === UNBILLABLE) {
+            await db
+                .update(claimIngests)
+                .set({ status: "skipped", error: "unbillable-claim-id" })
+                .where(eq(claimIngests.claimId, claimId));
+            deps.logger.warn("reserve.unbillable-claim-id", {
+                claimId,
+                collectionId: ingest?.collectionId,
+            });
+            return { status: UNBILLABLE, verdict: null, resultDigest: null, receiptCid: null };
+        }
+        return this.decideFresh(deps, source, db, engine, claimId, billing, finalAttempt);
+    }
+    /**
+     * Who pays for this chain claim's review (header): null when its collection pays by its
+     * evaluation leg (or the oracle no longer bills per review); `reserved` when a charge already
+     * holds it (a retry); else the payer, resolved fresh — never a guess: the engine's or the chain's
+     * trouble retries the step, and no usable delegation pauses the collection `payer-delegation`.
+     */
+    async billingFor(deps, source, db, claimId, collectionId) {
+        const watched = await deps.getWatched(collectionId);
+        if (!watched?.billingSourceId)
+            return null;
+        // Registered to be paid per review, it is never decided unpaid: a plan IXO no longer grants
+        // pauses it (re-register on the escrow gate), and a plan the engine cannot tell retries.
+        if (!(await planAllowsReviewBilling(deps))) {
+            await this.pausePayer(deps, db, collectionId, "oracle-plan", "plan does not allow it");
+            throw AppError.unavailable(`${PAYER_BILLING} the plan does not allow per-review billing`);
+        }
+        if (!CHAIN_CLAIM_ID.test(claimId))
+            return UNBILLABLE;
+        const charge = await db.query.apiCharges.findFirst({
+            columns: { status: true },
+            where: eq(apiCharges.claimId, claimId),
+        });
+        if (charge && ["reserved", "settled", "paid"].includes(charge.status))
+            return "reserved";
+        const billingDeps = { ...deps, db };
+        const payer = await resolvePayer(billingDeps, await companyOf(billingDeps, collectionId), await source.protocolDid(collectionId));
+        if (!payer.ok) {
+            await this.pausePayer(deps, db, collectionId, "payer-delegation", payer.detail);
+            if (payer.detail.startsWith("no published price")) {
+                // The operator's config, not the payer's: every claim of the protocol stops here.
+                await reportAlert(deps, "payments.review.no-price", { collectionId });
+            }
+            throw AppError.unavailable(`${PAYER_BILLING} no one pays for collection ${collectionId}`);
+        }
+        // The organisation now pays from another source (one deleted, one added): follow it.
+        if (payer.source.sourceId !== watched.billingSourceId) {
+            await db
+                .update(watchedCollections)
+                .set({ billingSourceId: payer.source.sourceId })
+                .where(eq(watchedCollections.collectionId, collectionId));
+        }
+        return payer;
+    }
+    /**
+     * A billing pause. The payer's two: the owner's notice, never a page (a customer's condition).
+     * `oracle-plan`: IXO's to fix — paged, no notice to the owner or the payer.
+     */
+    async pausePayer(deps, db, collectionId, reason, detail) {
+        if (reason === "oracle-plan") {
+            await db
+                .update(watchedCollections)
+                .set({ status: "paused", pausedReason: reason })
+                .where(eq(watchedCollections.collectionId, collectionId));
+            await reportAlert(deps, "payments.review.oracle-plan", { collectionId, code: peerCode(detail) }, "payments.review.oracle-plan");
+        }
+        else {
+            await pauseCollection(db, deps, collectionId, reason, undefined, false);
+        }
+        deps.logger.warn(`reserve.${reason}`, { collectionId, detail });
+        deps.metrics.count("review_billing.paused", 1, { outcome: reason });
+    }
+    /** The normal path: pull → build → (reserve) → decide → the `decisions` row. */
+    async decideFresh(deps, source, db, engine, claimId, billing = null, finalAttempt = false) {
+        // The one pull per claim: metadata + body + attachment descriptors (the source's store), and
+        // the content the engine binds the decision to — the engine's alone, so it is taken off here
+        // and no handler ever sees it. Like the body, it never leaves this step.
+        const { content, ...pulled } = await source.pull(claimId);
+        const { collectionId } = pulled;
+        const fdeps = { ...factDeps(deps, pulled.media, engine, db, this.env, source), finalAttempt };
+        // `subject.protocolDid` — where the engine reads `#rub`/`#vct` from, and what its manifest is
+        // keyed by, so it is resolved before the build (the manifest is the build's first read).
+        const protocolDid = await source.protocolDid(collectionId);
+        // The engine names the chain lane's subject `claim` (§8.1); the seam names lanes.
+        const kind = (await source.subject(claimId)).kind === "api" ? "api" : "claim";
+        // S16 — the payout block, beside the facts (never in them).
+        const payout = payoutRequestFor(protocolDid);
+        // RESOLVE + FREEZE (lib/facts/builder.ts). Nothing here is decided: a build that cannot
+        // complete is recorded as what it is, and the engine is never asked.
+        const built = await buildFacts(fdeps, { claim: pulled, protocolDid });
+        if (!built.ok) {
+            return this.buildFailure(deps, source, db, pulled, built);
+        }
+        // The claim WILL be decided: only now is a review reserved (never decide without one).
+        if (billing && billing !== "reserved") {
+            await this.reserve(deps, db, billing, { claimId, collectionId, protocolDid });
+        }
+        const request = (b) => ({
+            subject: { kind, claimId, collectionId, protocolDid },
+            rubric: { id: b.rubricId },
+            facts: b.facts,
+            ...(payout ? { payout } : {}),
+            claimContent: content,
+        });
+        let decided;
+        try {
+            decided = await this.decide(deps, engine, fdeps, pulled, protocolDid, built, request);
+        }
+        catch (err) {
+            // The re-anchored rubric is the one that cannot be built for — recorded exactly as a first
+            // build's failure would be (see `decide`), never decided.
+            if (err instanceof BuildFailure) {
+                return this.buildFailure(deps, source, db, pulled, err.result);
+            }
+            throw await this.engineFailure(deps, source, db, claimId, collectionId, err);
+        }
+        const { response } = decided;
+        requireReceipt(response, "decision");
+        // Both sides hash the same canonical JSON (factset.ts); a drift here means the engine is
+        // binding its decision to facts other than the ones we froze — worth knowing, never fatal.
+        const ours = await factsDigest(decided.built.facts);
+        if (ours !== response.factsDigest) {
+            deps.logger.warn("evaluate.facts-digest-drift", {
+                claimId,
+                ours,
+                theirs: response.factsDigest,
+            });
+        }
+        // Null on the engine only when the protocol has no `#rub` — impossible past our own resolve,
+        // but never store a null pin for a claim we KNOW the rubric of.
+        const rubricId = response.rubricId ?? decided.built.rubricId;
+        const result = await this.record(deps, source, db, pulled, response, rubricId, decided.built.facts);
+        // The answer archive (lib/archive.ts), here because the body is in hand only inside this step.
+        // Fail-soft and returns nothing: the body goes to R2, never into the step result.
+        if (this.env.ANSWERS_ARCHIVE) {
+            await archiveAnswer(this.env, deps, {
+                lane: source.lane,
+                claim: pulled,
+                content,
+                submitter: await source.submitterKey(pulled).catch(() => null),
+                response,
+                facts: { ext: decided.built.facts.ext, ai: decided.built.facts.ai },
+                hooks: getOracle().config.archive,
+            });
+        }
+        return result;
+    }
+    /** Reserve the review (payments/review-billing.ts), or say why not — a pause, a retry, a stop. */
+    async reserve(deps, db, payer, claim) {
+        const out = await reserveChainClaim({ ...deps, db }, payer, claim);
+        if (out.ok)
+            return;
+        if ("pause" in out) {
+            await this.pausePayer(deps, db, claim.collectionId, out.pause, out.detail);
+            throw AppError.unavailable(`${PAYER_BILLING} collection paused ${out.pause} (${out.detail})`);
+        }
+        if ("fail" in out)
+            throw new NonRetryableError(`${PAYER_BILLING} ${out.detail}`);
+        throw AppError.unavailable(`${PAYER_BILLING} reservation refused (${out.detail})`);
+    }
+    /**
+     * A decision recovered from the engine's store → its `decisions` row.
+     *
+     * It is FINAL for this claim — the engine will not judge it twice — so it outranks anything this
+     * attempt would have concluded, including a build that failed. What it lacks is the facts it was
+     * decided on: the attempt that produced them died before writing the row, and the engine keeps a
+     * trace, not a FactSet. So they are rebuilt here — and stand in for the originals only if the
+     * rebuild is PROVABLY the same one, which is exactly what the engine's `factsDigest` proves.
+     * Anything else (a non-deterministic fact, a re-anchored rubric, a failed rebuild) is written as
+     * a park with its reason, at write time: better an explicit blocked row naming the drift than a
+     * decided row the act lane refuses later without knowing why.
+     *
+     * The rebuild may not even be ATTEMPTABLE: the owner's delegation can expire while the claim
+     * sits between attempts, and then the pull fail-closes 403. A deterministic "no" there is NOT a
+     * reason to lose the decision — the ingest would be marked `failed` with no row at all, while
+     * the engine holds a final answer it will never issue again. So it is recorded parked, facts
+     * null, and the act lane refuses to sign it (src/act.ts reads those facts). Only a transient
+     * failure is rethrown, so the step still retries and a later attempt can record the real facts.
+     */
+    async recordRecovered(deps, source, db, engine, claimId, collectionId, recovered) {
+        let claim;
+        let built;
+        try {
+            // Nothing is sent here, so the content is dropped with the pull.
+            const { content: _content, ...rest } = await source.pull(claimId);
+            claim = rest;
+            const protocolDid = await source.protocolDid(claim.collectionId);
+            built = await buildFacts(factDeps(deps, claim.media, engine, db, this.env, source), {
+                claim,
+                protocolDid,
+            });
+        }
+        catch (err) {
+            // `stepError` is the retry/stop line the step itself is judged by (steps.ts) — reuse it so
+            // "deterministic" means the same thing here as it does there. Transient: rethrow untouched
+            // and let the step wrapper classify it, exactly as before.
+            if (!(stepError(err) instanceof NonRetryableError))
+                throw err;
+            const message = err instanceof Error ? err.message : String(err);
+            deps.logger.warn("evaluate.recovered-facts-unbuildable", {
+                claimId,
+                collectionId,
+                status: recovered.decision.status,
+                error: message,
+            });
+            return this.record(deps, source, db, { claimId, collectionId }, recovered, recovered.rubricId, null, `recovered decision; facts could not be rebuilt: ${message}`);
+        }
+        const rebuilt = built.ok && (await factsDigest(built.facts)) === recovered.factsDigest ? built.facts : null;
+        return this.record(deps, source, db, claim, recovered, recovered.rubricId, rebuilt, rebuilt
+            ? undefined
+            : "recovered decision's factsDigest does not match the facts rebuilt in this attempt");
+    }
+    /**
+     * The engine's answer → the `decisions` row, the collection's rubric pin and the `unusable`
+     * pause: ONE path whether the answer came from `POST /v1/decisions` just now or was recovered
+     * from the engine's store on a retry (see `evaluate`), so the two can never drift apart.
+     *
+     * `sent` is the FactSet this decision was made on — its `ext`/`ai` are frozen onto the row for
+     * the act policy to read at signing time (schema.ts `decisions.facts`), and nothing else of it
+     * is: `answers`/`attachments` are the claim's erasable surface and never persisted here. Null
+     * only on the recovery path when the rebuild could not be proven to be the same facts, which is
+     * what `park` says: the row is written `blocked` with that reason instead of `pending`, so the
+     * claim read explains itself and the act lane never has to guess.
+     */
+    async record(deps, source, db, claim, response, rubricId, sent, park) {
+        const { claimId, collectionId } = claim;
+        const row = {
+            claimId,
+            collectionId,
+            rubricId,
+            factsDigest: response.factsDigest,
+            verdict: response.decision.verdict,
+            status: response.decision.status,
+            resultDigest: response.resultDigest,
+            receiptCid: response.receipt?.cid ?? null,
+            receiptJws: response.receipt?.jws ?? null,
+            decision: response.decision,
+            explanation: response.explanation,
+            facts: sent ? { ext: sent.ext, ai: sent.ai } : null,
+            erroredFacts: erroredFactsOf(response),
+            // The review view's `duplicates` source (`{}` stores nothing, like an older engine's none).
+            pendingTaskDetails: Object.keys(response.pendingTaskDetails ?? {}).length > 0
+                ? (response.pendingTaskDetails ?? null)
+                : null,
+            // Nothing is ever acted on for a source without an act step (the API lane, §7.1).
+            chainStatus: !source.after.act
+                ? "skipped"
+                : park
+                    ? "blocked"
+                    : "pending",
+            chainError: source.after.act ? (park ?? null) : null,
+        };
+        // The decision and, when it is FINAL, its verdict denormalized onto the claim's duplicate
+        // registry rows (stock/unique-store.ts; a no-op for a rubric without `unique`) land in ONE
+        // batch: a retry that finds the row is done (the early return above), so the token can never
+        // be owed separately. `pending_review` stays NULL (= pending, blockable) until the fold.
+        // The claim's connector-result cache rows die in the same batch (fact-cache.ts) — decided,
+        // so nothing is left for a retry to reuse. So does the collection's rubric pin, first sight
+        // only (NULL only): the chain is the authority and the per-claim pin is the row's own
+        // `rubricId`; this one is the dashboard's "which rules govern this collection", never
+        // re-written by a later re-anchor. Inside the batch, or a crash after it would lose the pin for
+        // good (the retry returns early on the row). Chain lane only — an API scope has no
+        // `watched_collections` row.
+        const token = registryVerdictToken(row.status, row.verdict);
+        await db.batch([
+            db.insert(decisions).values(row).onConflictDoNothing(),
+            ...(token ? [finalVerdictUpdate(db, { collectionId, claimId, token })] : []),
+            factCacheDelete(db, claimId),
+            ...(isChain(source)
+                ? [
+                    db
+                        .update(watchedCollections)
+                        .set({ rubricId: row.rubricId })
+                        .where(and(eq(watchedCollections.collectionId, collectionId), isNull(watchedCollections.rubricId))),
+                ]
+                : []),
+        ]);
+        await this.decisionLatency(deps, source, db, claimId, response, sent);
+        // A payout scope whose claim names no payee: decided, its receipt without a payment binding
+        // (ENGINE-CONTRACT "Payee").
+        if (response.decisionToPayRefused) {
+            deps.logger.warn("payout.refused", {
+                claimId,
+                collectionId,
+                code: response.decisionToPayRefused,
+            });
+        }
+        // Settle on the receipt (payments spec §4 step 6): fail-soft, the reconcile re-settles a lost
+        // one; a claim with no charge (billing mode `none`, a chain claim its evaluation leg pays) is a
+        // no-op. An engine `unusable` is a decision with a receipt: settled, as on the API lane. A
+        // `pending_review` has no receipt until the fold: hold its reservation through the review
+        // instead (extend.ts).
+        if (deps.config.X402_FACILITATOR_URL) {
+            if (row.receiptJws)
+                await settleClaim({ ...deps, db }, claimId, row.receiptJws);
+            else if (row.status === "pending_review")
+                await extendForReview({ ...deps, db }, claimId);
+        }
+        // The engine could not bind the rubric to these facts (header): a real, receipted decision
+        // for THIS claim — and the same answer for every other claim of the collection.
+        if (response.decision.status === "unusable") {
+            await pauseUnusable(source, deps.logger, "evaluate", {
+                claimId,
+                collectionId,
+                rubricId: row.rubricId,
+                issues: response.decision.reasons,
+                receiptCid: row.receiptCid,
+            });
+        }
+        deps.logger.info("evaluate.done", {
+            claimId,
+            collectionId,
+            rubricId: row.rubricId,
+            status: response.decision.status,
+            verdict: response.decision.verdict,
+            pendingTasks: response.decision.pendingTasks,
+            resultDigest: response.resultDigest,
+            receiptCid: row.receiptCid,
+            traceId: response.traceId ?? null,
+        });
+        return resultOf(row);
+    }
+    /**
+     * `api.decision.latency` — accept → decision row, the SLO metric. Accepted is the API claim's
+     * `receivedAt`, or the chain claim's ledger `createdAt` (its first `record-queued`). `status` says
+     * whether the protocol's rubric runs AI checks: the frozen FactSet's `ai` keys are exactly the
+     * work order's (validate.ts holds them to the manifest), so no extra read; `-` only when a
+     * recovered decision's facts could not be rebuilt. Best-effort: a metric never fails the step.
+     */
+    async decisionLatency(deps, source, db, claimId, response, sent) {
+        try {
+            const acceptedAt = isChain(source)
+                ? (await db.query.claimIngests.findFirst({
+                    columns: { createdAt: true },
+                    where: eq(claimIngests.claimId, claimId),
+                }))?.createdAt
+                : (await db.query.apiClaims.findFirst({
+                    columns: { receivedAt: true },
+                    where: eq(apiClaims.claimId, claimId),
+                }))?.receivedAt;
+            if (!acceptedAt)
+                return;
+            const { protocolDid } = response.subject;
+            deps.metrics.timing("api.decision.latency", Date.now() - acceptedAt.getTime(), {
+                op: isChain(source) ? "chain" : "api",
+                status: sent ? (Object.keys(sent.ai).length > 0 ? "ai" : "no_ai") : null,
+                outcome: response.decision.verdict,
+                id: typeof protocolDid === "string" ? protocolDid : null,
+            });
+        }
+        catch (err) {
+            deps.logger.warn("metrics.decision-latency-failed", { claimId, detail: String(err) });
+        }
+    }
+    /**
+     * `POST /v1/decisions`, with the one recoverable refusal handled here: `RUBRIC_PIN_MISMATCH` —
+     * our pin ≠ the chain's `#rub` proof as the engine read it, i.e. `#rub` was re-anchored between
+     * our (KV-cached) manifest read and theirs. Invalidate and re-read the manifest ONCE: a changed
+     * pin is a new work order (new facts, so a rebuild — connectors run again; the fact cache is
+     * keyed by the pin, fact-cache.ts), the same pin means the engine and the chain disagree, which
+     * no retry of ours fixes. The manifest may also have turned `unusable` under the new anchor —
+     * then the rebuild records that, and never decides.
+     */
+    async decide(deps, engine, fdeps, pulled, protocolDid, built, request) {
+        try {
+            return { response: await this.ask(deps, engine, request(built)), built };
+        }
+        catch (err) {
+            if (!(err instanceof EngineError) || err.code !== "RUBRIC_PIN_MISMATCH")
+                throw err;
+            await engine.invalidateManifest(protocolDid);
+            const fresh = await engine.getManifest(protocolDid);
+            const repinned = isManifestUnusable(fresh) ? null : fresh.rubricId.toLowerCase();
+            if (repinned === built.rubricId) {
+                throw new NonRetryableError(`Rubric pin mismatch that re-reading the manifest did not fix: ${err.message}`);
+            }
+            deps.logger.warn("evaluate.rubric-repinned", {
+                claimId: pulled.claimId,
+                collectionId: pulled.collectionId,
+                from: built.rubricId,
+                to: repinned,
+            });
+            const rebuilt = await buildFacts(fdeps, { claim: pulled, protocolDid, manifest: fresh });
+            if (!rebuilt.ok) {
+                // The re-anchored rubric is the one that cannot be built for — record THAT, no engine call.
+                throw new BuildFailure(rebuilt);
+            }
+            return { response: await this.ask(deps, engine, request(rebuilt)), built: rebuilt };
+        }
+    }
+    /** One decide call, with the contract's retry-once on `NO_EVALUATE_GRANT` (see `GRANT_RETRY_DELAY`). */
+    async ask(deps, engine, req) {
+        try {
+            return await engine.decide(req);
+        }
+        catch (err) {
+            if (!(err instanceof EngineError) || err.code !== "NO_EVALUATE_GRANT")
+                throw err;
+            deps.logger.warn("evaluate.no-grant-yet", {
+                claimId: req.subject.claimId,
+                collectionId: req.subject.collectionId,
+                retryInMs: GRANT_RETRY_DELAY.ms,
+            });
+            await new Promise((resolve) => setTimeout(resolve, GRANT_RETRY_DELAY.ms));
+            return engine.decide(req);
+        }
+    }
+    /**
+     * The engine said no (docs/ENGINE-CONTRACT.md "Errors"): do what the table says, then hand back
+     * the error to throw — NonRetryable for a deterministic refusal, the original for a retryable
+     * one. Non-engine errors pass through for `stepError` to classify.
+     */
+    async engineFailure(deps, source, db, claimId, collectionId, err) {
+        if (!(err instanceof EngineError))
+            return err;
+        const scope = { claimId, collectionId, code: err.code, requestId: err.requestId ?? null };
+        switch (err.code) {
+            case "NO_EVALUATE_GRANT":
+                // Twice (see `ask`): not hired (any more) for this collection — no claim of it can be
+                // decided until the owner re-grants, so stop enqueuing and say why. The watched row stands.
+                // Only the chain lane's subject is grant-checked (§8.1); an API source never gets here.
+                if (isChain(source))
+                    await source.pause(collectionId, "engine-no-grant");
+                deps.logger.error("evaluate.not-hired", scope);
+                reportError(err, { lane: "evaluate", step: "evaluate", claimId, collectionId });
+                return new NonRetryableError(`Not hired for collection ${collectionId}: ${err.message}`);
+            case "INSUFFICIENT_CREDITS": {
+                // The oracle OWNER's credits are exhausted at the engine (an invoice bounced): EVERY
+                // collection pauses (the credits are the owner's, shared across every collection we watch
+                // for them, never this kit's own wallet), the operator is paged, and this claim keeps
+                // retrying. While the pause stands, the cron enqueues nothing new and every in-flight
+                // claim's retry stops at the pause check before its pull (`evaluate`), spending nothing;
+                // once the billing cron lifts it, the next retry pulls, builds and the engine answers.
+                await pauseForEngineCredits(db, deps);
+                deps.logger.error("evaluate.credits-exhausted", { ...scope, topUpUrl: err.topUpUrl });
+                reportError(err, { lane: "evaluate", step: "evaluate", claimId, collectionId });
+                return err;
+            }
+            case "VALIDATION":
+                // The engine refused the facts' SHAPE — our connectors' bug, never a claim outcome. The
+                // details are Zod paths and messages (identifiers), logged so the fix is one grep away.
+                deps.logger.error("evaluate.facts-rejected", { ...scope, details: err.details ?? null });
+                reportError(err, { lane: "evaluate", step: "evaluate", claimId, collectionId });
+                return new NonRetryableError(`${FAILURE.engineRejected}: ${err.message}`);
+            case "CONTENT_MISMATCH":
+            case "PAYLOAD_TOO_LARGE": {
+                // The engine would not bind the decision to the content we sent (company authority): the
+                // bytes, the answers, the attachments, the agent — or a body over its cap, which the client
+                // also says before sending. No resend changes the claim, so it is recorded like a build
+                // failure (`skipped`: nothing to act on), the ingest fails, and the operator is paged —
+                // `details.reason` names the check, never an answer value.
+                const status = CONTENT_REFUSAL_STATUS[err.code];
+                const reason = reasonOf(err.details);
+                await db.batch([
+                    db
+                        .insert(decisions)
+                        .values({
+                        claimId,
+                        collectionId,
+                        status,
+                        explanation: `${err.code}${reason ? ` (${reason})` : ""}: ${err.message}`,
+                        chainStatus: "skipped",
+                    })
+                        .onConflictDoNothing(),
+                    factCacheDelete(db, claimId),
+                ]);
+                deps.logger.error("evaluate.content-refused", { ...scope, reason });
+                await reportAlert(deps, `engine.${status.replaceAll("_", "-")}`, { claimId, collectionId, code: err.code, reason }, `engine.${status}:${claimId}`);
+                return new NonRetryableError(`${err.code}: ${reason ?? err.message}`);
+            }
+            case "CONFLICT":
+                // The engine holds this claim's decision under a different `kind` or `collectionId` than
+                // we just sent — the same claimId reached it through two lanes or scopes. Our bug, never a
+                // claim outcome, and no retry changes the stored row: stop, and page it.
+                deps.logger.error("evaluate.subject-conflict", scope);
+                reportError(err, { lane: "evaluate", step: "evaluate", claimId, collectionId });
+                return new NonRetryableError(`${FAILURE.engineConflict}: the engine holds this claim under another subject: ${err.message}`);
+            case "RATE_LIMITED":
+                // The engine's per-IP limiter said "not now" (a backlog burst): the step's own backoff
+                // (1 min doubling) already outlasts its 60 s window, so retry as-is — logged with the
+                // engine's `Retry-After` so a throttled backlog is visible, never a permanent failure.
+                deps.logger.warn("evaluate.throttled", {
+                    ...scope,
+                    retryAfterMs: err.retryAfterMs ?? null,
+                });
+                return err;
+            // The three refusals below all come out of the engine's OWN `POST /v1/oracles/register`
+            // (decision-engine spec §5/§9), surfacing HERE because `client.ts`'s `registered()` wrapper
+            // re-registers whenever its KV "registered" marker (REGISTERED_TTL_SEC, 30d) has expired —
+            // i.e. any `decide()` can hit one of these, not just a fresh boot. None pause a collection:
+            // unlike `engine-credits`, the engine's `/me` keeps answering `ok` here (billingStatus is a
+            // different gate), so `cron/billing.ts`'s auto-resume would never see the fix and un-pause —
+            // this is the owner's/operator's fix to make, not a chain-write concern.
+            case "NO_SUBSCRIPTION": {
+                // The owner has no IXO subscription, or it lapsed — the engine can't find a credit wallet
+                // to bill without one. `topUpUrl` is null for a bare "no subscription at all" (nothing to
+                // manage a URL for yet) — the kit's own PORTAL_BASE_URL still names somewhere to send them.
+                const topUpUrl = err.topUpUrl ?? deps.config.PORTAL_BASE_URL;
+                deps.logger.error("evaluate.owner-billing-refused", { ...scope, topUpUrl });
+                reportError(err, { lane: "evaluate", step: "evaluate", claimId, collectionId });
+                return new NonRetryableError(`Owner has no active IXO subscription: ${err.message}. Subscribe in the portal (${topUpUrl}), then register again.`);
+            }
+            case "DELEGATION_NOT_FOR_ORACLE":
+                // `OWNER_DELEGATION_CAR` is a real, unexpired CAR — just bound (`billing/pay with`) to a
+                // DIFFERENT oracle's did:web. Re-registering with the same file only fails the same way.
+                deps.logger.error("evaluate.owner-billing-refused", scope);
+                reportError(err, { lane: "evaluate", step: "evaluate", claimId, collectionId });
+                return new NonRetryableError(`Owner delegation is bound to a different oracle: ${err.message}. Re-mint the CAR for ` +
+                    "THIS oracle (decision-oracle delegation --for engine --oracle <this did:web>) and " +
+                    "set it as OWNER_DELEGATION_CAR.");
+            default: {
+                // A bad/expired CAR is a plain `400 BAD_REQUEST` (owner-delegation.ts's own checks — not a
+                // dedicated code), told apart from any other BAD_REQUEST only by its message naming the
+                // field this kit actually sends.
+                if (err.code === "BAD_REQUEST" && err.message.includes("ownerDelegation")) {
+                    deps.logger.error("evaluate.owner-billing-refused", scope);
+                    reportError(err, { lane: "evaluate", step: "evaluate", claimId, collectionId });
+                    return new NonRetryableError(`Owner delegation rejected: ${err.message}. Re-mint the CAR ` +
+                        "(decision-oracle delegation --for engine) and register again.");
+                }
+                return err.retryable ? err : new NonRetryableError(`${err.code}: ${err.message}`);
+            }
+        }
+    }
+    /**
+     * Facts that don't match the rubric's work order (lib/facts/validate.ts) — the producer's bug,
+     * never a claim outcome: the issue list is codes and paths (identifiers), logged and paged so the
+     * fix is one grep away, and the error to throw is NonRetryable (a retry would re-run the same
+     * producer). The row is already recorded by the caller.
+     */
+    invalidFacts(deps, claimId, collectionId, built) {
+        deps.logger.error("evaluate.facts-invalid", {
+            claimId,
+            collectionId,
+            rubricId: built.rubricId ?? null,
+            issues: built.issues,
+        });
+        const err = new NonRetryableError(`Facts do not match the rubric's work order: ${built.issues.map((i) => `${i.code} ${i.path}`).join(", ")}`);
+        reportError(err, { lane: "evaluate", step: "evaluate", claimId, collectionId });
+        return err;
+    }
+    /**
+     * A claim the facts lane could not build for — recorded WITHOUT a decide call (schema.ts
+     * `decisions`): `status` names the reason, `explanation` the issues, and nothing will ever be
+     * acted on, so `chainStatus` is `skipped` from the start. Then the reason's consequence:
+     * `rubric-unusable` is the engine's manifest saying the rubric cannot be bound — the same
+     * handling as its decide-time `unusable` (pause the collection; steps.ts), minus the receipt, and
+     * the ingest completes; `invalid-facts` is OUR (or the provider's) bug, never a claim outcome —
+     * recorded so the claim read says why, then failed loudly, like the engine's own `VALIDATION`
+     * refusal this check exists to catch first.
+     */
+    async buildFailure(deps, source, db, claim, built) {
+        const { claimId, collectionId } = claim;
+        const status = BUILD_FAILURE_STATUS[built.reason];
+        const rubricId = built.rubricId ?? null;
+        const explanation = built.issues.map((i) => `${i.code}: ${i.message} (${i.path})`).join("; ");
+        // A first build never cached anything, but a RUBRIC_PIN_MISMATCH rebuild lands here AFTER the
+        // first build's connectors ran — the cache dies with the outcome, same as `record`.
+        await db.batch([
+            db
+                .insert(decisions)
+                .values({ claimId, collectionId, rubricId, status, explanation, chainStatus: "skipped" })
+                .onConflictDoNothing(),
+            factCacheDelete(db, claimId),
+        ]);
+        // Only a re-pinned rebuild gets here with a review reserved (the first build is checked before
+        // reserving): no receipt will ever come, so it is freed — its cap back too.
+        if (isChain(source)) {
+            await releaseChainClaim({ ...deps, db }, claimId, built.reason === "invalid-facts" ? "facts_invalid" : "facts_unusable");
+        }
+        if (built.reason === "invalid-facts")
+            throw this.invalidFacts(deps, claimId, collectionId, built);
+        await pauseUnusable(source, deps.logger, "evaluate", {
+            claimId,
+            collectionId,
+            rubricId,
+            issues: built.issues,
+        });
+        return { status, verdict: null, resultDigest: null, receiptCid: null };
+    }
+    /**
+     * A terminal failure's class — the API lane's §5 code (lib/api-lane/record.ts `claimErrorCode`,
+     * read off the same message the ledger stores), for either lane. Best-effort like the rest of
+     * the terminal path.
+     */
+    async failureClass(claimId, err) {
+        const decided = await getDb(this.env)
+            .query.decisions.findFirst({
+            columns: { status: true },
+            where: eq(decisions.claimId, claimId),
+        })
+            .catch(() => undefined);
+        return claimErrorCode(err instanceof Error ? err.message : String(err), decided?.status ?? null);
+    }
+    ledgerRow(claimId) {
+        return getDb(this.env).query.claimIngests.findFirst({
+            where: (t, { eq: eqOp }) => eqOp(t.claimId, claimId),
+        });
+    }
+    /**
+     * Upsert this claim's ledger row. `error` is null unless `failed` (schema.ts), so a rerun that
+     * succeeds clears the old message.
+     */
+    async recordStatus(claimId, event, update) {
+        const fields = {
+            status: update.status,
+            collectionId: update.collectionId,
+            instanceId: event.instanceId,
+            error: update.error ?? null,
+        };
+        await getDb(this.env)
+            .insert(claimIngests)
+            .values({ claimId, lane: update.lane, ...fields })
+            .onConflictDoUpdate({ target: claimIngests.claimId, set: fields });
+    }
+}
+/** The re-anchored rubric could not be built for — carries the result to be recorded (see `decide`, `buildFailure`). */
+class BuildFailure extends Error {
+    result;
+    constructor(result) {
+        super(`facts lane: ${result.reason}`);
+        this.result = result;
+        this.name = "BuildFailure";
+    }
+}
+//# sourceMappingURL=claim-ingest.js.map