@ixo/decision-oracle 0.2.28 → 0.2.30

package/dist/workflows/claim-ingest.js

@@ -4,10 +4,16 @@
  * 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:
+ * THE WORKFLOW OWNS ITS LEDGER ROW for its whole lifecycle — the one other writer is the API
+ * lane's inline run (`evaluateInline`, workflows/evaluate.ts), the same `evaluate` body run by the
+ * accepting request for a caller that waits; it takes the row only from `queued` (writing its lease,
+ * `inlineUntil`, in the same statement), and the steps below find what it wrote:
  *   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
+ *                            iff the instance started, so nothing can ever strand a row) — never
+ *                            over a row already `processing` / `processed`, which an inline run
+ *                            (or an earlier run of this instance) wrote and a rerun must not undo
+ *   step "evaluate"        → (workflows/evaluate.ts) a recorded decision is returned as is; else
+ *                            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
@@ -28,7 +34,11 @@
  *                            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`
+ *   step "mark-processed"  → row → `processed` — right after the decision (and the act), so the
+ *                            ledger reads `processed` beside it without waiting on a receiver;
+ *                            AFTER the notify for a `pending_review`, whose record reads its
+ *                            tasks off the `review_required` event the notify writes
+ *   step "notify-review"   → the source's notify lane (fail-soft, its own delivery ledger)
  *   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.
  *
@@ -85,68 +95,27 @@
 import { WorkflowEntrypoint } from "cloudflare:workers";
 import { NonRetryableError } from "cloudflare:workflows";
 import * as Sentry from "@sentry/cloudflare";
-import { and, eq, isNull, ne } from "drizzle-orm";
+import { eq, ne, notInArray } 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 { claimIngests, decisions } from "../db/schema.js";
+import { claimErrorCode } from "../lib/api-lane/record.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 { 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 { reviewerNoteEnabled, writeReviewerNote } from "../lib/review/reviewer-note.js";
+import { scopedStep, withMetrics } from "../lib/metrics.js";
+import { releaseChainClaim } from "../lib/payments/review-billing.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";
+import { ClaimEvaluator, UNBILLABLE } from "./evaluate.js";
+import { actStep, RECEIPT_MISSING, stepError } from "./steps.js";
+export { GRANT_RETRY_DELAY, PAYER_BILLING } from "./evaluate.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
@@ -225,7 +194,9 @@ export class ClaimIngest extends WorkflowEntrypoint {
             async (ctx) => {
                 const finalAttempt = ctx !== undefined && ctx.attempt > (ctx.config?.retries?.limit ?? EVALUATE_RETRY_LIMIT);
                 try {
-                    return await this.evaluate(deps, source, claimId, finalAttempt);
+                    return await new ClaimEvaluator(this.env).evaluate(deps, source, claimId, {
+                        finalAttempt,
+                    });
                 }
                 catch (err) {
                     throw stepError(err);
@@ -244,6 +215,20 @@ export class ClaimIngest extends WorkflowEntrypoint {
                     workflow: "claim-ingest",
                 });
             }
+            // `processed` as soon as the decision (and its act) is in: nothing after it can fail the
+            // ingest — the notify is fail-soft — so the ledger never makes a waiting caller sit through a
+            // receiver's webhook round trip to read `processed` beside its decision. Except a claim that
+            // waits for review: its record reads the tasks off the `review_required` event the notify
+            // writes, so `processed` follows it there and no answer shows placeholder tasks.
+            const markProcessed = () => step.do("mark-processed", async () => {
+                await this.recordStatus(claimId, event, {
+                    status: "processed",
+                    collectionId: collectionId,
+                });
+            });
+            const reviewFirst = result.status === "pending_review";
+            if (!reviewFirst)
+                await markProcessed();
             // 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
@@ -258,12 +243,8 @@ export class ClaimIngest extends WorkflowEntrypoint {
                 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,
-                });
-            });
+            if (reviewFirst)
+                await markProcessed();
             return { claimId, ok: true, ...result };
         }
         catch (err) {
@@ -318,700 +299,6 @@ export class ClaimIngest extends WorkflowEntrypoint {
             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.) A `processed` row is never re-marked: it has its decision (the early return
-        // below), and an orphaned attempt must not walk it back (see `recordStatus`).
-        const ingest = await db.query.claimIngests.findFirst({
-            where: (t, { eq: eqOp }) => eqOp(t.claimId, claimId),
-        });
-        await db
-            .update(claimIngests)
-            .set({ status: "processing" })
-            .where(and(eq(claimIngests.claimId, claimId), ne(claimIngests.status, "processed")));
-        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.
-        // The chain lane off (config.ts `CHAIN_LANE`): a chain run started before the switch, still
-        // retrying, or restarted by hand must not pull, spend AI or ask the engine to decide on the
-        // owner's credits. Retried like the pause below, never recorded `skipped` — the scan would then
-        // count the claim as seen for good — so the run carries on once the lane is back on (within the
-        // step's ~4 h of retries; past them it ends `failed`, rerun like any failed claim).
-        if (isChain(source) && !deps.config.CHAIN_LANE) {
-            throw AppError.unavailable(`chain lane off (CHAIN_LANE=false) — not pulling ${claimId}`);
-        }
-        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,
-            });
-        }
-        // The reviewer note (lib/review/reviewer-note.ts): only for a claim held for a person, and
-        // here for the same reason — the answers are in hand only inside this step. Fail-soft and
-        // returns nothing; outside the decision, so it can never move a verdict.
-        if (response.decision.status === "pending_review" && reviewerNoteEnabled()) {
-            const facts = decided.built.facts;
-            await writeReviewerNote({
-                config: deps.config,
-                logger: deps.logger,
-                trace: deps.trace,
-                env: this.env,
-                cache: deps.cache,
-                db,
-                engine,
-            }, {
-                claimId,
-                protocolDid,
-                pendingTasks: response.decision.pendingTasks,
-                answers: facts.answers,
-                attachments: facts.attachments,
-                facts: { ext: facts.ext, ai: facts.ai },
-            });
-        }
-        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;
-        // What the act lane could ever sign (chain-write.ts step 1): a `decided` 1/2 now, or a
-        // `pending_review` once its fold makes it final (the fold writes `pending` itself). Anything
-        // else — an engine `unusable`, a `decided` review (5) — is a recorded non-action, so it is
-        // `skipped` from the start rather than `pending` for ever.
-        const { status, evaluationStatus } = response.decision;
-        const actable = !!source.after.act &&
-            (status === "pending_review" ||
-                (status === "decided" && (evaluationStatus === 1 || evaluationStatus === 2)));
-        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: !actable
-                ? "skipped"
-                : park
-                    ? "blocked"
-                    : "pending",
-            chainError: actable ? (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
@@ -1033,7 +320,10 @@ export class ClaimIngest extends WorkflowEntrypoint {
     }
     /**
      * Upsert this claim's ledger row. `error` is null unless `failed` (schema.ts), so a rerun that
-     * succeeds clears the old message.
+     * succeeds clears the old message. `queued` never lands on a row already `processing` or
+     * `processed`: the inline run (or an earlier run of this instance) got that far, and moving it
+     * back would hide an inline run in flight from `evaluate` (two runs, the handlers paid twice) and
+     * show a decided claim as `queued` until the run caught up.
      */
     async recordStatus(claimId, event, update) {
         const fields = {
@@ -1048,19 +338,13 @@ export class ClaimIngest extends WorkflowEntrypoint {
             .onConflictDoUpdate({
             target: claimIngests.claimId,
             set: fields,
+            ...(update.status === "queued"
+                ? { setWhere: notInArray(claimIngests.status, ["processing", "processed"]) }
+                : {}),
             // A `failed` never overwrites a `processed`: an orphaned attempt of a claim another run
             // already finished (seen on mainnet) would otherwise mark a decided claim dead.
             ...(update.status === "failed" ? { setWhere: ne(claimIngests.status, "processed") } : {}),
         });
     }
 }
-/** 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