@ixo/decision-oracle 0.2.27 → 0.2.29

package/dist/workflows/claim-ingest.d.ts

@@ -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,6 +95,7 @@
 import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
 import type { ClaimLaneKind } from "../contracts/index.js";
 import type { OracleEnv } from "../env.js";
+export { type EvaluateResult, GRANT_RETRY_DELAY, PAYER_BILLING } from "./evaluate.js";
 export interface ClaimIngestParams {
     claimId: string;
     /** Known at cron discovery time; absent on manual runs (resolved on-chain in `record-queued`). */
@@ -104,28 +115,6 @@ export interface ClaimIngestParams {
     /** The accepting request's id, API lane only. */
     requestId?: string;
 }
-/** What leaves the evaluate step: small, log-safe, enough to reason about the run — never the facts. */
-export interface EvaluateResult {
-    status: string;
-    verdict: string | null;
-    resultDigest: string | null;
-    receiptCid: string | null;
-}
-/**
- * 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 declare const PAYER_BILLING = "payer-billing:";
-/**
- * `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 declare const GRANT_RETRY_DELAY: {
-    ms: number;
-};
 export declare class ClaimIngest extends WorkflowEntrypoint<OracleEnv, ClaimIngestParams> {
     run(event: WorkflowEvent<ClaimIngestParams>, step: WorkflowStep): Promise<{
         status: string;
@@ -136,104 +125,6 @@ export declare class ClaimIngest extends WorkflowEntrypoint<OracleEnv, ClaimInge
         ok: boolean;
     }>;
     private ingest;
-    /**
-     * 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.
-     */
-    private evaluate;
-    /**
-     * 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`.
-     */
-    private billingFor;
-    /**
-     * 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.
-     */
-    private pausePayer;
-    /** The normal path: pull → build → (reserve) → decide → the `decisions` row. */
-    private decideFresh;
-    /** Reserve the review (payments/review-billing.ts), or say why not — a pause, a retry, a stop. */
-    private reserve;
-    /**
-     * 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.
-     */
-    private recordRecovered;
-    /**
-     * 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.
-     */
-    private record;
-    /**
-     * `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.
-     */
-    private decisionLatency;
-    /**
-     * `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.
-     */
-    private decide;
-    /** One decide call, with the contract's retry-once on `NO_EVALUATE_GRANT` (see `GRANT_RETRY_DELAY`). */
-    private ask;
-    /**
-     * 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.
-     */
-    private engineFailure;
-    /**
-     * 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.
-     */
-    private invalidFacts;
-    /**
-     * 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.
-     */
-    private buildFailure;
     /**
      * 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
@@ -243,7 +134,10 @@ export declare class ClaimIngest extends WorkflowEntrypoint<OracleEnv, ClaimInge
     private ledgerRow;
     /**
      * 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.
      */
     private recordStatus;
 }

package/dist/workflows/claim-ingest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claim-ingest.d.ts","sourceRoot":"","sources":["../../src/workflows/claim-ingest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AAEH,OAAO,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAI/F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAUlD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAoDxC,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,kGAAkG;IAClG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wGAAwG;AACxG,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAOD;;;GAGG;AACH,eAAO,MAAM,aAAa,mBAAmB,CAAC;AAsB9C;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB;IAAK,EAAE;CAAU,CAAC;AAchD,qBAAa,WAAY,SAAQ,kBAAkB,CAAC,SAAS,EAAE,iBAAiB,CAAC;IAChE,GAAG,CAAC,KAAK,EAAE,aAAa,CAAC,iBAAiB,CAAC,EAAE,IAAI,EAAE,YAAY;gBA3DtE,MAAM;iBACL,MAAM,GAAG,IAAI;sBACR,MAAM,GAAG,IAAI;oBACf,MAAM,GAAG,IAAI;;;OA8ExB;YAEa,MAAM;IA+KpB;;;OAGG;YACW,QAAQ;IAkHtB;;;;;OAKG;YACW,UAAU;IA6CxB;;;OAGG;YACW,UAAU;IAyBxB,gFAAgF;YAClE,WAAW;IAyHzB,kGAAkG;YACpF,OAAO;IAgBrB;;;;;;;;;;;;;;;;;;OAkBG;YACW,eAAe;IA2D7B;;;;;;;;;;;OAWG;YACW,MAAM;IA0HpB;;;;;;OAMG;YACW,eAAe;IAmC7B;;;;;;;;OAQG;YACW,MAAM;IAoCpB,wGAAwG;YAC1F,GAAG;IAmBjB;;;;OAIG;YACW,aAAa;IAmI3B;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAmBpB;;;;;;;;;OASG;YACW,YAAY;IAwC1B;;;;OAIG;YACW,YAAY;IAa1B,OAAO,CAAC,SAAS;IAMjB;;;OAGG;YACW,YAAY;CA4B3B"}
+{"version":3,"file":"claim-ingest.d.ts","sourceRoot":"","sources":["../../src/workflows/claim-ingest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AAEH,OAAO,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAI/F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAGlD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAaxC,OAAO,EAAE,KAAK,cAAc,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEnF,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,kGAAkG;IAClG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAUD,qBAAa,WAAY,SAAQ,kBAAkB,CAAC,SAAS,EAAE,iBAAiB,CAAC;IAChE,GAAG,CAAC,KAAK,EAAE,aAAa,CAAC,iBAAiB,CAAC,EAAE,IAAI,EAAE,YAAY;;;;;;;OAsB7E;YAEa,MAAM;IA0LpB;;;;OAIG;YACW,YAAY;IAa1B,OAAO,CAAC,SAAS;IAMjB;;;;;;OAMG;YACW,YAAY;CA+B3B"}