@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/lib/facts/factset.js

@@ -0,0 +1,226 @@
+/**
+ * FactSet v1 — the WIRE shape this oracle asserts to the eval engine (`POST /v1/decisions`
+ * `facts`, README "How a claim flows" steps 4–5). Everything the engine's `decide()` needs from us: claim answers,
+ * attachment descriptors, the frozen ctx snapshot, and the ext/ai answers with their transcripts.
+ * After the builder returns it there is no network, no clock, and no AI anywhere in the decision —
+ * the boundary between resolve and decide is the determinism/replay guarantee (evaluator-spec §1),
+ * now drawn between two services: this oracle resolves + FREEZES, the engine decides.
+ *
+ * The engine accepts `facts` as a STRICT object (unknown keys ⇒ 400), so this schema is strict at
+ * every level and the TypeScript types are inferred from it — the two cannot drift. What is NOT on
+ * the wire, deliberately: `derived` and `formProof` (the engine computes both itself from the same
+ * chain-anchored `#rub`/`#vct`; the oracle computes neither — it never binds). `unique` and
+ * `frequency` ARE on it — optional, present iff the rubric declares the rule (duplicate detection
+ * is oracle-side) — validated here to exactly what the engine's `decide()`
+ * reads and LOOSE beyond that (the producer's forensic fields ride into the engine's trace).
+ * `frozenAt` IS `ctx.now`: one clock read per build, asserted below. Only `ext`, `ai`, `unique`
+ * and `frequency` are oracle-specific (producer.ts); every other key is plumbing the builder
+ * assembles.
+ *
+ * Facts are ASSERTED, not trusted (plan §9): the engine records `factsDigest` + this oracle's DID on
+ * its ledger and receipt, so the digest below is what a decision is bound to.
+ */
+import { z } from "zod";
+import { canonicalJson, sha256Hex } from "../hash.js";
+/** A CID reference — never bytes (§3: attachments are references, the files stay in their store). */
+export const AttachmentFact = z.strictObject({
+    question: z.string(),
+    name: z.string(),
+    mediaType: z.string(),
+    cid: z.string().nullable(),
+    /** Bytes, from the media response's content-length — null when unknown (null rule applies). */
+    size: z.number().int().nonnegative().nullable(),
+});
+/**
+ * The engine validates every wire date as `z.iso.datetime({ offset: true })` — it ACCEPTS an
+ * offset form (`+00:00`) since its Task 7 (docs/ENGINE-CONTRACT.md "Reconciled"). The kit stays
+ * stricter on purpose: Z-suffixed only, so one instant has one spelling and `factsDigest` cannot
+ * drift on formatting — lib/facts/ctx.ts normalizes what Blocksync hands over, and
+ * `toISOString()` output is exactly this.
+ */
+const Iso = z.iso.datetime();
+export const CtxFacts = z.strictObject({
+    /** The evaluation instant — ONE clock read, frozen. */
+    now: Iso,
+    collection: z.strictObject({
+        startDate: Iso.nullable(),
+        endDate: Iso.nullable(),
+    }),
+    claim: z.strictObject({
+        submitter: z.string().nullable(),
+        /** The claim's on-chain agentAddress — the payout target. */
+        submitterAddress: z.string().nullable(),
+        submissionDate: Iso.nullable(),
+        /**
+         * Escrow-governed payout (lib/ixo/payment.ts). Frozen here so the engine's S12 rule stays pure
+         * and a review fold — which replays the frozen facts VERBATIM — reads it unchanged.
+         */
+        useIntent: z.boolean().optional(),
+    }),
+});
+/**
+ * The oracle's policy for the ai/image lanes (the oracle config (`defineOracle`) `policies`) — recorded so every
+ * FactSet is self-explaining ("why didn't AI run?"). Gates resolve only, never decide.
+ */
+export const FactSettings = z.strictObject({
+    allowAiChecks: z.boolean(),
+    allowImageChecks: z.boolean(),
+});
+/** What a C2PA "Content Credentials" read established about one image (lib/facts/stock/c2pa.ts). */
+export const Provenance = z.strictObject({
+    vendor: z.enum(["google", "openai", "other", "unknown"]),
+    /** Meaningless unless `trusted` — anyone can self-sign a manifest naming any issuer. */
+    issuer: z.string().optional(),
+    /** OpenAI sets this ("gpt-image"); Google does not — never assume it's present. */
+    model: z.string().optional(),
+    modelVersion: z.string().optional(),
+    aiGenerated: z.boolean(),
+    watermarked: z.boolean(),
+    signedAt: z.string().optional(),
+    /** The cert chain verified against the trust list — the ONLY thing that makes the claim real. */
+    trusted: z.boolean(),
+    /** Validation failure codes (e.g. `signingCredential.untrusted`) — empty on a clean read. */
+    failures: z.array(z.string()),
+});
+/**
+ * The §A.14.1 "why did the engine decide this" record — frozen per call. Optional on the wire; the
+ * stock connectors always produce one, and the engine stores it in its trace.
+ */
+export const Transcript = z.strictObject({
+    request: z.strictObject({
+        url: z.string(),
+        /** What we sent (the declared payload / the composed prompt) — erasable PII surface. */
+        body: z.unknown(),
+        /** Safe subset only — never the authorization header. */
+        headers: z.record(z.string(), z.string()),
+    }),
+    /** null = no HTTP response at all (network error / timeout on every attempt). */
+    response: z.strictObject({ status: z.int(), body: z.unknown() }).nullable(),
+    // Integers on the engine (`z.int()`), so integers here — the stock connectors measure with
+    // `Date.now()` diffs; an override measuring with `performance.now()` must round.
+    attempts: z.int().nonnegative(),
+    /** Whole-budget wall time (backoffs included). */
+    elapsedMs: z.int().nonnegative(),
+    /** The last HTTP attempt's own latency (fetch → body read). */
+    latencyMs: z.int().nonnegative().optional(),
+    /** The provider's call id (ai checks): OpenRouter's generation id, or the AI Gateway log id. */
+    genId: z.string().nullable().optional(),
+    /** USD + tokens when the provider reports cost at call time (OpenRouter); null on the gateway — its USD is backfilled into `ai_calls`. */
+    usage: z
+        .strictObject({
+        promptTokens: z.number(),
+        completionTokens: z.number(),
+        /** Prompt tokens served from the provider's prompt cache (the static-prefix payoff). */
+        cachedTokens: z.number(),
+        /** USD charged for this generation, as reported by the provider. */
+        costUsd: z.number(),
+    })
+        .nullable()
+        .optional(),
+    /**
+     * C2PA screening record, one entry per image the provenance gate READ (ai checks, image lane) —
+     * inconclusive reads (`result: null`) are recorded too: "no hidden label found" is an outcome.
+     */
+    provenance: z
+        .array(z.strictObject({
+        key: z.string(),
+        cid: z.string().nullable(),
+        result: Provenance.nullable(),
+    }))
+        .optional(),
+});
+const OnError = z.enum(["review", "reject"]);
+/** Facts as probabilities, uniformly (plan §9): integer basis points. Optional — the stock connectors don't set it. */
+const Confidence = z.number().int().min(0).max(10000).optional();
+export const ExtFact = z.discriminatedUnion("status", [
+    z.strictObject({
+        status: z.literal("ok"),
+        value: z.union([z.boolean(), z.number()]),
+        reason: z.string().nullable(),
+        confidence: Confidence,
+        transcript: Transcript.optional(),
+    }),
+    z.strictObject({
+        status: z.literal("error"),
+        onError: OnError,
+        detail: z.string(),
+        transcript: Transcript.optional(),
+    }),
+]);
+export const AiFact = z.discriminatedUnion("status", [
+    z.strictObject({
+        status: z.literal("ok"),
+        /** DERIVED in code: no rule failed — the model's `valid` is ignored. */
+        value: z.boolean(),
+        /** Failed rules mapped back to their instruction texts ("Failed R2: …"); null when valid. */
+        reason: z.string().nullable(),
+        failedRules: z.array(z.string()),
+        /** The model's confidence in the verdict, clamped 0..100 (already ≥ the floor). */
+        score: z.number().int().min(0).max(100),
+        confidence: Confidence,
+        transcript: Transcript.optional(),
+    }),
+    z.strictObject({
+        status: z.literal("error"),
+        onError: OnError,
+        detail: z.string(),
+        transcript: Transcript.optional(),
+    }),
+]);
+/**
+ * The frozen duplicate-detection fact, validated to the exact shape of every field the engine's
+ * `decide()` reads (decision-engine `schemas.ts` @ 444aeae: `ruleId`, `digest`, `scoreBps`,
+ * `band`); everything else the producer freezes (winner, candidates, aiOutcome, aiPairs, …) rides
+ * through LOOSE into the engine's trace — the audit trail behind the receipt's `unique:<ruleId>`
+ * check. `band` is a closed enum: the engine branches on `band !== "pass"`, so a typo must fail
+ * here, never misroute there.
+ */
+export const UniqueFact = z.looseObject({
+    ruleId: z.string(),
+    digest: z.string(),
+    scoreBps: z.number().int().min(0).max(10000),
+    band: z.enum(["pass", "review", "reject"]),
+});
+/**
+ * The frozen submission-rate fact — `count`/`max` compose the engine's reason text, `breach` /
+ * `unresolved` are its branches (a Blocksync outage freezes `unresolved`, which the engine fails
+ * closed); `per` and the window bounds are wording, typed when present. Loose beyond that.
+ */
+export const FrequencyFact = z.looseObject({
+    ruleId: z.string(),
+    count: z.int(),
+    max: z.int(),
+    per: z.enum(["day", "week", "month", "year"]).optional(),
+    windowStartISO: Iso.nullable().optional(),
+    windowEndISO: Iso.nullable().optional(),
+    breach: z.boolean(),
+    unresolved: z.literal(true).optional(),
+});
+/** The wire contract — exactly what `POST /v1/decisions` receives as `facts`, nothing else. */
+export const FactSetV1 = z
+    .strictObject({
+    version: z.literal(1),
+    /** The one clock read of the build — identical to `ctx.now`. */
+    frozenAt: Iso,
+    /** credentialSubject — needed by the rules, never persisted by the engine (trace = facts − answers). */
+    answers: z.record(z.string(), z.unknown()),
+    attachments: z.array(AttachmentFact),
+    ctx: CtxFacts,
+    ext: z.record(z.string(), ExtFact),
+    ai: z.record(z.string(), AiFact),
+    /** Present iff the rubric declares the rule (producer.ts) — the engine decides on them. */
+    unique: UniqueFact.optional(),
+    frequency: FrequencyFact.optional(),
+    /** The policy in effect for this build — recorded, self-explaining. */
+    settings: FactSettings,
+})
+    .refine((f) => f.frozenAt === f.ctx.now, "frozenAt must equal ctx.now — one clock read per build");
+/**
+ * `sha256(canonicalJson(facts))` — what the engine records as `factsDigest` and what a decision is
+ * bound to. Canonical JSON (sorted keys, no whitespace) makes it independent of key order, so a
+ * FactSet that round-trips through JSON digests identically on both sides.
+ */
+export function factsDigest(facts) {
+    return sha256Hex(canonicalJson(facts));
+}
+//# sourceMappingURL=factset.js.map

package/dist/lib/facts/factset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factset.js","sourceRoot":"","sources":["../../../src/lib/facts/factset.ts"],"names":[],"mappings":"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"}

package/dist/lib/facts/producer.d.ts

@@ -0,0 +1,190 @@
+/**
+ * The whole-producer seam: each oracle produces its facts ITS OWN WAY.
+ * The kit hands a producer the pulled claim and the rubric's work order (expected.ts — the engine's
+ * manifest) and gets back
+ * `ext` / `ai` — the only oracle-specific content of a FactSet. Everything else (`answers`, `ctx`,
+ * `attachments`, `settings`, `frozenAt`) is plumbing the kit assembles around it (builder.ts), and
+ * validate.ts holds what comes back to the work order before anything is sent.
+ *
+ * Deliberately one function, not a registry: the oracle config (`defineOracle`) `facts` is either absent (the
+ * stock producer in stock/ runs every declared source and check) or a function in this shape. Wrap
+ * the stock producer to replace one fact, or ignore it entirely — the kit doesn't care how a value
+ * was made, only that every declared name comes back as an ok/error fact of the declared type.
+ */
+import type { Config } from "../../config.js";
+import type { ClaimSource } from "../../contracts/index.js";
+import type { Database } from "../../db/client.js";
+import type { OracleEnv } from "../../env.js";
+import type { EngineClient } from "../engine/client.js";
+import type { PulledClaim } from "../ixo/index.js";
+import type { Logger } from "../logger.js";
+import type { Metrics } from "../metrics.js";
+import type { TraceContext } from "../tracing.js";
+import type { ExpectedFacts } from "./expected.js";
+import type { AiFact, CtxFacts, ExtFact, FactSettings, FrequencyFact, UniqueFact } from "./factset.js";
+import type { SameEventJudgement } from "./stock/ai-unique.js";
+/** What a producer returns — frozen verbatim into the FactSet once validate.ts has passed it. */
+export interface ProducedFacts {
+    ext: Record<string, ExtFact>;
+    ai: Record<string, AiFact>;
+    /**
+     * The duplicate-detection fact — REQUIRED iff the manifest declares `unique` (detection is
+     * oracle-side; docs/ENGINE-CONTRACT.md "Fact coverage + manifest"), refused otherwise.
+     * The engine reads `band` (and `aiOutcome`); the stock producer's full forensic shape
+     * (stock/unique-score.ts) rides through loose into its trace. A custom producer may detect
+     * duplicates any way it likes — a vendor registry, its own store — and return the minimum.
+     */
+    unique?: UniqueFact;
+    /** The submission-rate fact — REQUIRED iff the manifest declares `frequency` (with `max`/`per`). */
+    frequency?: FrequencyFact;
+}
+/**
+ * The connector-result cache (db/schema.ts `fact_cache`; lib/facts/fact-cache.ts): resolved
+ * `ext`/`ai` facts a PRIOR crashed attempt of this same build already paid for, consulted before a
+ * connector runs so a workflow-step retry never re-buys an AI/ext call that already answered.
+ * `unique`/`frequency` must never go through it — registry state and calendar windows have to be
+ * fresh per attempt (the one cached piece of the duplicate lane is the judge's per-pair verdict,
+ * `unique-judge`, never the candidate set). Both sides are fail-soft by contract: the cache is an optimization, so a read
+ * error means "no cache" and a write error means "not cached" — never a failed fact.
+ */
+export interface FactCache {
+    /** Every cached row for the claim — ONE read per build, before any connector runs. */
+    read(claimId: string): Promise<FactCacheEntry[]>;
+    /** One resolved row as it lands. Fail-soft: a cache write error never fails the fact. */
+    write<K extends FactCacheEntry["kind"]>(claimId: string, kind: K, name: string, fact: Extract<FactCacheEntry, {
+        kind: K;
+    }>["fact"]): Promise<void>;
+}
+/**
+ * One `fact_cache` row (db/schema.ts): a connector's fact, or one same-event judge verdict per
+ * candidate (stock/unique.ts `judgePairs` — the duplicate lane's only cached part).
+ */
+export type FactCacheEntry = {
+    kind: "ext";
+    name: string;
+    fact: ExtFact;
+} | {
+    kind: "ai";
+    name: string;
+    fact: AiFact;
+} | {
+    kind: "unique-judge";
+    name: string;
+    fact: SameEventJudgement;
+};
+/**
+ * Where the claim came from, as far as the facts lane cares (Go Prod §7.1): the ctx window and the
+ * frequency lane's count. The workflow hands over its `ClaimSource`; absent (tests, the CLI) ⇒ the
+ * chain lane's own Blocksync reads.
+ */
+export type ClaimScope = Pick<ClaimSource, "window" | "countSubmissions" | "submitterKey">;
+/** Runs `fn` inside a named trace span — on Workers, lib/spans.ts's `inSpan`. Attributes are
+ *  metric labels only. */
+export type SpanFn = <T>(name: string, attrs: Record<string, string | undefined>, fn: () => Promise<T>) => Promise<T>;
+/** Model → what this build spent on it. */
+export type AiSpend = Map<string, 
+/** `microUsd` null ⇒ the provider reports no cost at call time (the gateway — backfilled). */
+{
+    promptTokens: number;
+    completionTokens: number;
+    microUsd: number | null;
+}>;
+/** One AI Gateway call awaiting its USD (cron/ai-cost.ts) — written once by builder.ts into `ai_calls`. */
+export interface AiCall {
+    callId: string;
+    fact: string;
+    model: string;
+    promptTokens: number | null;
+    completionTokens: number | null;
+    cachedTokens: number | null;
+}
+/** What every producer (stock or custom) gets to work with. */
+export interface ProducerDeps {
+    config: Config;
+    logger: Logger;
+    trace: TraceContext;
+    /**
+     * The claim's media store for on-demand attachment reads (size probes, AI-check bytes) — never
+     * logged, never persisted. Null on the cellnode lane (those claims carry no file answers).
+     */
+    media: PulledClaim["media"];
+    /** Reused CACHE_KV — the C2PA trust list. Optional: absent in tests. */
+    cache?: KVNamespace;
+    /**
+     * What the facts lane may READ from the eval engine — today the buyer statement
+     * (`getAgreement`, docs/ENGINE-CONTRACT.md "Agreements"): a producer answering agreement facts
+     * (`priceMatchesAgreement`, `serviceWasAgreed`, …) calls
+     * `deps.engine.getAgreement(claim.collectionId, claim.metadata.agentAddress)` right BEFORE
+     * returning its fact — the engine records the snapshot current at decision time on its receipt,
+     * so reading it last is what makes the receipt name the version the facts used. The FactSet
+     * itself is unchanged: the agreement never rides the wire, only the facts read off it.
+     * Optional: absent in tests and producer dry runs.
+     */
+    engine?: Pick<EngineClient, "getAgreement">;
+    /**
+     * This oracle's D1 (`getDb(env)`) — the stock `unique` lane's duplicate registries
+     * (stock/unique-store.ts) live there. Optional: absent in tests and producer dry runs; the
+     * stock lane fails loudly the moment a rule needs it. A custom producer may use it for its own
+     * tables or ignore it.
+     */
+    db?: Database;
+    /**
+     * The connector-result cache over that D1 (wired by builder.ts `factDeps`) — see `FactCache`.
+     * Optional: absent in tests and producer dry runs; a custom producer may use it the same way the
+     * stock one does, or ignore it.
+     */
+    factCache?: FactCache;
+    /**
+     * The step's worker env — bindings and vars as wrangler hands them over, so a handler reaching
+     * for its OWN binding (a provider's KV, a queue, an AI binding) has one. Reaches a handler as
+     * `tools.env`. Optional: absent in tests and producer dry runs, where reading it is loud.
+     */
+    env?: OracleEnv;
+    /** The claim's scope reads (`ClaimScope`) — optional: absent ⇒ Blocksync, as before the seam. */
+    scope?: ClaimScope;
+    /**
+     * The step's metrics (`facts.handler`) — injected, never imported, so this lane stays node-safe.
+     * Optional: absent in tests and dry runs ⇒ nothing recorded.
+     */
+    metrics?: Metrics;
+    /**
+     * The step's trace span around each handler call (`facts.handler`, observability spec §4) —
+     * injected like `metrics`, since a Workers Traces span needs `cloudflare:workers`. Optional:
+     * absent ⇒ the call runs bare.
+     */
+    span?: SpanFn;
+    /**
+     * The build's model spend, summed per model by the judge (stock/ai-check.ts) and written once by
+     * builder.ts as `ai.tokens` / `ai.cost_micro_usd` — one set of points per model, not per check.
+     */
+    aiSpend?: AiSpend;
+    /** The build's AI Gateway calls (stock/ai-provider.ts `recordSpend`) — builder.ts writes them once. */
+    aiCalls?: AiCall[];
+    /** The protocol the work order is for — the metrics' `id` label. Optional, like `metrics`. */
+    protocolDid?: string;
+    /**
+     * The evaluate step's LAST attempt (claim-ingest.ts): transient trouble a handler throws is frozen
+     * as the rubric's `onError` instead of retried (runner.ts `detailForThrow`), so an outage that
+     * outlives the step's retries ends as the fallback, never as a dead ingest or a retry for ever.
+     */
+    finalAttempt?: boolean;
+    /** The oracle's policy for the ai/image lanes (the oracle config (`defineOracle`) `policies`) — recorded in the FactSet. */
+    settings: FactSettings;
+    /**
+     * The kit's `ctx` — the build's ONE clock read (`ctx.now` = `frozenAt`), the collection window
+     * and the claim's chain plane, resolved by builder.ts BEFORE the producer runs and handed over
+     * read-only: a producer never reads the clock or Blocksync for ctx, so what a `send` payload
+     * quotes (`ctx.now`, the window) is byte-for-byte what the engine's rules will read. Producers
+     * may of course timestamp their own transcripts.
+     */
+    ctx: CtxFacts;
+}
+/**
+ * `(claim, expected, deps) => { ext, ai, unique?, frequency? }` — produce every name in
+ * `expected.ext` / `expected.ai`, the `unique`/`frequency` fact iff the manifest declares the rule,
+ * and nothing else. An unreachable source is `status: "error"` with the rubric's `onError` — never
+ * an approve; a value comes from what actually happened; a transcript (optional on the wire, the
+ * engine keeps it as the "why") says what was sent and received and never carries a secret.
+ */
+export type FactsProducer = (claim: PulledClaim, expected: ExpectedFacts, deps: ProducerDeps) => Promise<ProducedFacts>;
+//# sourceMappingURL=producer.d.ts.map

package/dist/lib/facts/producer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"producer.d.ts","sourceRoot":"","sources":["../../../src/lib/facts/producer.ts"],"names":[],"mappings":"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"}

package/dist/lib/facts/producer.js

@@ -0,0 +1,15 @@
+/**
+ * The whole-producer seam: each oracle produces its facts ITS OWN WAY.
+ * The kit hands a producer the pulled claim and the rubric's work order (expected.ts — the engine's
+ * manifest) and gets back
+ * `ext` / `ai` — the only oracle-specific content of a FactSet. Everything else (`answers`, `ctx`,
+ * `attachments`, `settings`, `frozenAt`) is plumbing the kit assembles around it (builder.ts), and
+ * validate.ts holds what comes back to the work order before anything is sent.
+ *
+ * Deliberately one function, not a registry: the oracle config (`defineOracle`) `facts` is either absent (the
+ * stock producer in stock/ runs every declared source and check) or a function in this shape. Wrap
+ * the stock producer to replace one fact, or ignore it entirely — the kit doesn't care how a value
+ * was made, only that every declared name comes back as an ok/error fact of the declared type.
+ */
+export {};
+//# sourceMappingURL=producer.js.map

package/dist/lib/facts/producer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"producer.js","sourceRoot":"","sources":["../../../src/lib/facts/producer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/lib/facts/runner.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The facts runner — ONE place that runs a handler, whoever wrote it (spec §3.4). The stock
+ * producer is this with an empty handler table; a provider's `defineFacts({ ext, ai, … })` is the
+ * same run with some names routed elsewhere. That is the point: the guarantees below hold
+ * identically for both, because there is only one code path.
+ *
+ * What the runner guarantees around every handler:
+ *  - **Normalization** — a plain `true` / `8200` becomes an `ok` fact; a `fact.error(...)` draft
+ *    becomes a full error fact.
+ *  - **Fail closed** — an error fact carries the MANIFEST's `onError`, stamped here, overriding
+ *    whatever the handler put there. A THROW is the same thing: an error fact, never an approve,
+ *    never a lost claim. A handler cannot upgrade its own failure.
+ *  - **One retry signal** — `fact.retryLater()`, the kit's own loud `AppError`s, and a retryable
+ *    `EngineError` (the eval engine's own 5xx / `UNAVAILABLE` / `RATE_LIMITED`, e.g.
+ *    `tools.agreement()`'s read) all get out, as `unavailable`, so the workflow step retries
+ *    instead of freezing a verdict — the stock ext and AI lanes throw the same way for an outage.
+ *    BOUNDED: on the step's last attempt (`finalAttempt`) the transient ones freeze as the
+ *    rubric's `onError` instead, so an outage that outlives the retries still ends as a fact. The rule (task-14, 2026-09-14): a deterministic failure is a
+ *    fact; a transient one is a retry — claims are decided once, so a claim held for review over
+ *    trouble the engine never actually judged can never be re-run. A NON-retryable `EngineError`
+ *    (a real 404 / wrong-shaped document / counterparty mismatch) is still a fact: that IS the
+ *    engine's answer.
+ *  - **The fact cache** — a prior crashed attempt's paid answer is returned verbatim and the
+ *    handler never runs (producer.ts `FactCache`; `unique`/`frequency` never go through it).
+ *  - **The fan-out cap** — at most `MAX_CONCURRENT_CONNECTORS` ext/ai handlers in flight.
+ *
+ * NODE-SAFE by construction: this module is what `@ixo/decision-oracle/facts` and a provider's test
+ * suite pull in, so it imports only types, the pure `send.ts` / `rule-defaults.ts` readers, the
+ * `fact` helpers and `AppError`. Nothing here may reach `cloudflare:*`, a `.wasm`, D1 or KV — the
+ * stock lanes arrive as `deps.stock`, already built by whoever has a runtime.
+ */
+import type { AiHandler, AiInput, AiResult, ExtHandler, ExtInput, ExtResult, FactInputBase, FactsConfig, FactTools, FrequencyHandler, UniqueHandler } from "../../facts/types.js";
+import { type Manifest, type ManifestAi, type ManifestExt } from "../engine/types.js";
+import type { PulledClaim } from "../ixo/index.js";
+import type { Logger } from "../logger.js";
+import type { Metrics } from "../metrics.js";
+import type { AiFact, CtxFacts, ExtFact, FactSettings } from "./factset.js";
+import type { FactCache, ProducedFacts, SpanFn } from "./producer.js";
+/** The default lane per kind — what an unlisted name runs (lib/facts/tools.ts wires the real ones). */
+export interface StockLanes {
+    ext: ExtHandler;
+    ai: AiHandler;
+    unique: UniqueHandler;
+    frequency: FrequencyHandler;
+}
+/** Which fact a `tools` instance is for — `tools.stock()` runs THAT fact's stock lane. */
+export type FactTarget = {
+    kind: "ext";
+    name: string;
+    expected: ManifestExt;
+} | {
+    kind: "ai";
+    name: string;
+    check: ManifestAi;
+}
+/** A grouped handler — several sources at once, so there is no single lane for `stock()` to run. */
+ | {
+    kind: "group";
+    names: string[];
+} | {
+    kind: "unique";
+} | {
+    kind: "frequency";
+};
+export interface RunnerDeps {
+    logger: Logger;
+    /** The build's frozen ctx — resolved by the builder before any handler runs. */
+    ctx: CtxFacts;
+    settings: FactSettings;
+    /** Per-fact tools (the target says which stock lane `tools.stock()` runs). */
+    tools: (target: FactTarget) => FactTools;
+    stock: StockLanes;
+    factCache?: FactCache;
+    /** Injected by whoever has a runtime (tools.ts) — this module stays node-safe. Absent ⇒ no metric. */
+    metrics?: Metrics;
+    /** Injected the same way (lib/spans.ts on Workers). Absent ⇒ no span. */
+    span?: SpanFn;
+    /** The metrics' `id` label. */
+    protocolDid?: string;
+    /** The step's last attempt (producer.ts `finalAttempt`): a retry signal freezes as onError. */
+    finalAttempt?: boolean;
+}
+/**
+ * Connector fan-out cap over the ext+ai lanes: a rubric declaring 30 AI checks must not open 30
+ * model calls at once — the isolate allows 6 simultaneous outbound connections, OpenRouter
+ * throttles bursts, and a misauthored rubric should degrade to "slower", never to a socket/429
+ * storm. 4 keeps a typical rubric fully parallel; results are keyed by name, so order never
+ * matters. `unique`/`frequency` run beside the pool — one registry/count read each, not fan-out.
+ */
+export declare const MAX_CONCURRENT_CONNECTORS = 4;
+/**
+ * The basics every handler input is built from — one object, built once per run, spread into each
+ * ext/ai/unique/frequency input. Exported because `tools.stock()` (lib/facts/tools.ts) has to hand
+ * a stock lane the SAME input the runner would have: two builders would drift.
+ */
+export declare function factInputBase(claim: PulledClaim, manifest: Manifest, deps: Pick<RunnerDeps, "ctx" | "settings">): FactInputBase;
+/** One declared source's input: the `send` map resolved, the `~derived` refs reported. */
+export declare function buildExtInput(base: FactInputBase, name: string, expected: ManifestExt): ExtInput;
+/** One declared check's input — plus the `send` map as the model's typed, ordered inputs. */
+export declare function buildAiInput(base: FactInputBase, name: string, check: ManifestAi): AiInput;
+/** A plain return becomes an `ok` fact; anything that failed carries the manifest's `onError`. */
+export declare function normalizeExt(result: ExtResult, onError: "review" | "reject"): ExtFact;
+/** Same, for an AI check: a bare `true`/`false` is a verdict nothing failed under. */
+export declare function normalizeAi(result: AiResult, onError: "review" | "reject"): AiFact;
+/**
+ * Produce every fact the work order names: `facts.<kind>[name]` if the provider listed it, the
+ * stock lane otherwise. The result is exactly what a `FactsProducer` returns — validate.ts holds
+ * it to the order before anything is frozen.
+ */
+export declare function runHandlers(facts: FactsConfig, claim: PulledClaim, manifest: Manifest, deps: RunnerDeps): Promise<ProducedFacts>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/lib/facts/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/lib/facts/runner.ts"],"names":[],"mappings":"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"}