@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/lib/facts/tools.js

@@ -0,0 +1,325 @@
+/**
+ * `FactTools` — the kit's machinery handed to every handler, built per fact — plus the stock lanes
+ * and the ONE wiring both the stock producer and a provider's `defineFacts({...})` run through
+ * (`producerOf`). This is where the runner's abstract deps meet the runtime: it is the only module
+ * that turns a `FactTarget` into real HTTP, a real UCAN signature, a real model call.
+ *
+ * WORKERS-ONLY, deliberately: it reaches the UCAN signer, the C2PA WASM, the D1 registries and the
+ * engine client, none of which load in plain node. The `./facts` subpath (src/facts/*) and the
+ * runner must never import it — they take `tools` and `stock` as deps for exactly that reason, and
+ * `bun run test:node` is the tripwire. The import direction is: stock/index.ts, define-oracle.ts
+ * and builder.ts import THIS; nothing here imports them back.
+ *
+ * The tools are built per fact so `stock()` can mean "the stock lane for THIS fact": a handler
+ * wraps its own source or check (`const base = await tools.stock()`), falls back to it, or ignores
+ * it. Everything else is target-independent — the same batteries whichever fact is asking.
+ */
+import { defineFacts, isFactsConfig } from "../../facts/fact.js";
+import { AppError } from "../errors.js";
+import { assertPublicHttpUrl } from "../http/client.js";
+import { fetchAttachmentBytes, fetchAttachmentSize } from "../ixo/attachments.js";
+import { getClaimIntent, getEntityLinkedResources } from "../ixo/blocksync/index.js";
+import { getQueryClient } from "../ixo/chain.js";
+import { mintInvocation } from "../ixo/ucan.js";
+import { buildAiInput, buildExtInput, factInputBase, normalizeAi, normalizeExt, runHandlers, } from "./runner.js";
+import { judgeWithModel, MAX_AI_ATTACHMENT_BYTES, resolveAiCheck } from "./stock/ai-check.js";
+import { readImageProvenance } from "./stock/c2pa.js";
+import { jsonRequest, redactHeaders, redactUrl } from "./stock/call.js";
+import { assertExternalCapability, DEFAULT_CAPABILITY, urlAudience } from "./stock/capability.js";
+import { resolveExtSource } from "./stock/ext-source.js";
+import { resolveFrequency } from "./stock/frequency.js";
+import { aiEntries, resolveSendPayload } from "./stock/send.js";
+import { resolveUnique } from "./stock/unique.js";
+/** `tools.http.json` defaults — the ext connector's timeout and the shared 3-attempt budget. */
+const HTTP_TIMEOUT_MS = 15_000;
+const HTTP_ATTEMPTS = 3;
+/** Single-use, short-lived: a handler's invocation is minted per call, never cached. */
+const UCAN_TTL_SEC = 300;
+/** The refusal for a `send` map these lanes cannot resolve — carries the rubric's onError. */
+function derivedUnsupported(deps, kind, name, refs, onError) {
+    deps.logger.warn("stock.derived-unsupported", { kind, name, refs });
+    return {
+        status: "error",
+        onError,
+        detail: `derived refs unsupported by the stock producer: ${refs.join(", ")}`,
+    };
+}
+/**
+ * The four stock lanes as handlers — thin adapters from the runner's input to each connector
+ * (stock/). `~derived` refs are the one thing they cannot answer: the ENGINE computes derived
+ * values, so a source or check naming one is an `error` fact, never a guess. A custom handler gets
+ * the refs as `input.unresolved` and may compute them from `manifest.derived`.
+ */
+export function stockLanes(pdeps) {
+    return {
+        ext: (input) => input.unresolved.length > 0
+            ? derivedUnsupported(pdeps, "ext", input.name, input.unresolved, input.expected.onError)
+            : resolveExtSource({ claim: input.claim, name: input.name, source: input.expected, payload: input.send }, pdeps),
+        ai: (input) => input.unresolved.length > 0
+            ? derivedUnsupported(pdeps, "ai", input.name, input.unresolved, input.check.onError)
+            : resolveAiCheck({ claim: input.claim, name: input.name, check: input.check, entries: input.inputs }, pdeps),
+        // The source names the submitter (an API claim has no agentAddress, but a `submitter`), so
+        // the same courier claiming the same order again is a same-agent match on both lanes.
+        unique: async (input) => resolveUnique(pdeps, {
+            rule: input.rule,
+            collectionId: input.claim.collectionId,
+            claimId: input.claim.claimId,
+            agentAddress: pdeps.scope
+                ? await pdeps.scope.submitterKey(input.claim)
+                : input.claim.metadata.agentAddress,
+            body: input.claim.body,
+            attachments: input.claim.attachments,
+        }),
+        frequency: (input) => {
+            // The runner never routes a rule-less declaration here (it warns `stock.frequency-unrunnable`
+            // and omits the key); only a custom handler is handed one.
+            if (!input.rule)
+                throw AppError.internal("stock frequency lane reached without max/per");
+            // The source counts (Go Prod §7.1) — but only a claim that can have a submitter: a chain
+            // claim without an agent keeps the window-less `unresolved` fact it has always frozen (the
+            // factsDigest must not move); an API claim's submitter is the source's to find.
+            const { scope } = pdeps;
+            const { claim } = input;
+            return resolveFrequency(pdeps, {
+                rule: input.rule,
+                collectionId: claim.collectionId,
+                agentAddress: claim.metadata.agentAddress,
+                submissionDateISO: claim.metadata.submissionDate,
+                count: scope && (claim.metadata.agentAddress || claim.lane === "api")
+                    ? (from, to) => scope.countSubmissions(claim, from, to)
+                    : undefined,
+            });
+        },
+    };
+}
+/**
+ * What to call the fact being answered, in a log line and in the AI idempotency key. A group is
+ * named by the names it answers, so two groups over one claim never share a key.
+ */
+function factTargetName(target) {
+    if (target.kind === "ext" || target.kind === "ai")
+        return target.name;
+    if (target.kind === "group")
+        return `group:${target.names.join("+")}`;
+    return target.kind;
+}
+/** The tools for ONE fact — `stock()` is that fact's lane; the rest is the kit's machinery. */
+export function realTools(target, claim, manifest, pdeps, stock, 
+/** The build's shared agreement read (`producerOf`). Omitted ⇒ this fact's own, for a caller
+ *  building tools outside a producer run. */
+agreements = new Map()) {
+    const base = factInputBase(claim, manifest, pdeps);
+    /** The fact being answered — the AI idempotency key and every log line's `check`. */
+    const targetName = factTargetName(target);
+    // One line per fact, not per call: a handler that reads the agreement in a loop says it once.
+    let agreementWarned = false;
+    // Judgments are numbered per fact: OpenRouter's idempotency key is `${claimId}:${name}`, so two
+    // `judge()` calls under one name would collide on it and the second could be served the first's
+    // completion. The counter restarts with the tools, so a step retry replays the same keys.
+    let judgeCalls = 0;
+    /**
+     * One self-signed invocation for an external call. The developer's own capability — but never an
+     * IXO service's (stock/capability.ts): this token leaves for a third party, and those services
+     * take this did:web's word as the oracle's.
+     */
+    const signFor = async (audience, capability = DEFAULT_CAPABILITY) => {
+        assertExternalCapability(capability);
+        const { token } = await mintInvocation(pdeps.config, {
+            audience,
+            // Zod widens {can,with} to string; the UCAN lib brands them — cast, as the connectors do.
+            capability: capability,
+            ttlSec: UCAN_TTL_SEC,
+            unique: true,
+        });
+        return { authorization: `Bearer ${token}`, "x-auth-type": "ucan" };
+    };
+    const tools = {
+        async stock() {
+            if (target.kind === "ext") {
+                const input = buildExtInput(base, target.name, target.expected);
+                return normalizeExt(await stock.ext(input, tools), target.expected.onError);
+            }
+            if (target.kind === "ai") {
+                const input = buildAiInput(base, target.name, target.check);
+                // The ONE narrowing in this file: `tools` is built once per fact and its `stock()` returns
+                // whichever lane the TARGET selects, which the base type can only spell as the union. Here
+                // the target is known to be `ai`, so these tools ARE `AiTools` — what an ai handler (stock
+                // or custom) is declared to take.
+                return normalizeAi(await stock.ai(input, tools), target.check.onError);
+            }
+            // A group answers several names at once, so `stock()` inside one could only mean "the stock
+            // lane for WHICH of them" — an ambiguity that would silently buy the wrong call. A grouped
+            // name's own lane is the group; leave a name out of the group to keep its stock lane.
+            if (target.kind === "group") {
+                throw AppError.internal(`tools.stock() has no answer inside ${factTargetName(target)}: a group replaces the stock lane for every name it answers, and stock() here names none of them`);
+            }
+            // The dup/rate lanes answer their own fact shape, not an ext/ai one — and a custom
+            // unique/frequency handler REPLACES its lane wholesale (the runner's `deps.stock.unique` /
+            // `deps.stock.frequency` are those lanes), so there is nothing here to wrap.
+            throw AppError.internal(`tools.stock() has no answer for the ${target.kind} rule: that lane's fact is not an ext/ai fact, and a custom ${target.kind} handler replaces the stock lane wholesale`);
+        },
+        http: {
+            async json(url, init = {}) {
+                let headers = init.headers ?? {};
+                try {
+                    // A handler's URL often comes from a claim answer, so it gets the submitter-controlled
+                    // treatment (http/client.ts): a refusal is an OUTCOME — the same shape an unreachable
+                    // host produces — never a throw that costs the fact its own error handling.
+                    assertPublicHttpUrl(url);
+                }
+                catch {
+                    return {
+                        ok: false,
+                        status: null,
+                        body: null,
+                        transcript: {
+                            request: {
+                                url: redactUrl(url),
+                                body: init.method === "POST" ? (init.body ?? null) : null,
+                                headers: redactHeaders(headers),
+                            },
+                            response: null,
+                            attempts: 0,
+                            elapsedMs: 0,
+                        },
+                    };
+                }
+                if (init.ucan) {
+                    // Bound to the URL actually fetched: the audience is never the caller's to name here.
+                    const cap = init.ucan === true ? undefined : init.ucan.capability;
+                    headers = { ...headers, ...(await signFor(urlAudience(url), cap)) };
+                }
+                const outcome = await jsonRequest(pdeps, {
+                    url,
+                    method: init.method ?? "GET",
+                    headers,
+                    body: init.body,
+                    timeoutMs: init.timeoutMs ?? HTTP_TIMEOUT_MS,
+                    attempts: init.attempts ?? HTTP_ATTEMPTS,
+                });
+                return { ...outcome, body: outcome.body };
+            },
+            ucanHeaders: (audience, capability) => signFor(audience, capability),
+        },
+        ai: {
+            judge: (instructions, inputs, opts = {}) => judgeWithModel({
+                claim,
+                name: `${targetName}#${++judgeCalls}`,
+                instructions,
+                // A handler answering an AI check inherits that check's fallback; anywhere else the
+                // safe default applies — a judgment that could not be made is never an approve.
+                onError: target.kind === "ai" ? target.check.onError : "review",
+                entries: inputs,
+                ...(opts.model ? { model: opts.model } : {}),
+            }, pdeps),
+            inputsFor: (check) => aiEntries(claim, check, resolveSendPayload(check.send, claim.body, pdeps.ctx)),
+        },
+        attachments: {
+            on: (question) => claim.attachments.filter((att) => att.question === question),
+            bytes: (att, opts = {}) => fetchAttachmentBytes(pdeps, pdeps.media, att.url, 
+            // The AI lane's own cap by default (ai-check.ts) — a handler asks for more explicitly.
+            opts.maxBytes ?? MAX_AI_ATTACHMENT_BYTES, opts.timeoutMs),
+            // No media lane (the cellnode claims) means nothing to probe — the null rule decides.
+            size: async (att) => fetchAttachmentSize(pdeps, pdeps.media, att.url),
+        },
+        c2pa: {
+            // `settings.allowImageChecks` gates the STOCK ai lane's provenance short-circuit, not this:
+            // a handler that screens an image is asking for the read, and gets it.
+            screen: (bytes, mediaType) => readImageProvenance({ logger: pdeps.logger, trace: pdeps.trace, cache: pdeps.cache }, bytes, mediaType),
+        },
+        chain: {
+            // The same blocksync read the kit's own lanes use, over the same retrying transport — so a
+            // handler gets the parsed shape and the loud drift/outage behaviour for free instead of
+            // POSTing GraphQL at `config.BLOCKSYNC_GRAPHQL_URL` itself (deep imports are blocked).
+            linkedResources: (entityDid) => getEntityLinkedResources(pdeps, entityDid),
+            // One filtered query, never a scan (blocksync/queries.ts CLAIM_INTENT) — which is the whole
+            // reason this lives here and not in a handler.
+            claimIntent: (params) => getClaimIntent(pdeps, params),
+            // Memoised per isolate inside chain.ts, behind the SDK's lazy import: a handler that never
+            // asks never loads the protos.
+            query: () => getQueryClient(pdeps.config),
+        },
+        // Deliberately NO try/catch around the engine read: `engine.getAgreement` already returns
+        // `null` for a real 404 (client.ts) — a genuine "no agreement on file" answer — so anything
+        // that reaches here as a THROW is trouble reading the engine, not an answer from it. Left to
+        // propagate, that lands in the runner's `detailForThrow` (facts/runner.ts), which rethrows a
+        // retryable `EngineError` (5xx / `UNAVAILABLE` / `RATE_LIMITED`) as `unavailable` so the
+        // workflow step retries instead of freezing an error fact (task-14, 2026-09-14 — the incident
+        // this fixed: a transient engine 5xx was frozen as `fact.error(...)` and held a claim for
+        // review it could never be re-run for, since claims are decided once). Wrapping this in a
+        // catch — even a well-meaning `catch { return null }` — would reintroduce exactly that bug, so
+        // don't.
+        async agreement(counterparty) {
+            if (!pdeps.engine) {
+                if (!agreementWarned) {
+                    agreementWarned = true;
+                    pdeps.logger.warn("facts.agreement-no-engine", { fact: targetName });
+                }
+                return null;
+            }
+            // OMITTED ⇒ the claim's own agent (the buyer statement's `counterparty`). An explicit
+            // `null` is a different question — the collection's own terms, no counterparty — and the
+            // engine client sends no `?counterparty=` for it, so it must not collapse into the default:
+            // the resolved value IS the cache key, so the two never share an entry.
+            const who = counterparty === undefined ? claim.metadata.agentAddress : counterparty;
+            const engine = pdeps.engine;
+            // The ONE read of the build, even when it fails: a rejected promise is memoized here just
+            // like a resolved one, so a second handler needing the same counterparty shares the SAME
+            // rejection (one engine ask, not a retry-storm inside the build) rather than re-asking — the
+            // workflow step retry is what re-asks, with a fresh build and a fresh map.
+            let read = agreements.get(who);
+            if (!read) {
+                read = engine.getAgreement(claim.collectionId, who);
+                agreements.set(who, read);
+            }
+            return read;
+        },
+        logger: pdeps.logger,
+        config: pdeps.config,
+        get env() {
+            // Absent only in tests and dry runs (producer.ts). Loud beats a handler reading a binding
+            // off `undefined` three lines later.
+            if (!pdeps.env)
+                throw AppError.internal("tools.env: this build carries no worker env");
+            return pdeps.env;
+        },
+    };
+    return tools;
+}
+/**
+ * The ONE producer wiring: a `defineFacts({...})` table (or nothing at all) becomes a producer that
+ * runs the runner with the real tools and the stock lanes as every unlisted name's default; a
+ * whole-producer function is returned untouched. Both `defineOracle({ facts })` (define-oracle.ts)
+ * and the stock producer (stock/index.ts) come through here, which is what makes the runner's
+ * guarantees identical for a provider's handler and for the stock lane.
+ */
+export function producerOf(facts, 
+/**
+ * Per-lane replacements for the STOCK defaults — what an unlisted name (and `tools.stock()`) runs
+ * instead. The oracle itself never passes any; the CLI's dry run (`facts run`) does, for the one
+ * lane it cannot honestly run off a laptop: `unique` reads this oracle's D1 registries. A
+ * whole-producer function ignores them — it owns its own wiring.
+ */
+stockOverrides) {
+    if (facts && !isFactsConfig(facts))
+        return facts;
+    const config = facts ?? defineFacts({});
+    return (claim, expected, pdeps) => {
+        const lanes = { ...stockLanes(pdeps), ...stockOverrides };
+        // One per BUILD, so every handler in it shares the agreement read (see `AgreementCache`).
+        const agreements = new Map();
+        return runHandlers(config, claim, expected, {
+            logger: pdeps.logger,
+            metrics: pdeps.metrics,
+            span: pdeps.span,
+            protocolDid: pdeps.protocolDid,
+            finalAttempt: pdeps.finalAttempt,
+            ctx: pdeps.ctx,
+            settings: pdeps.settings,
+            factCache: pdeps.factCache,
+            stock: lanes,
+            tools: (target) => realTools(target, claim, expected, pdeps, lanes, agreements),
+        });
+    };
+}
+//# sourceMappingURL=tools.js.map

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

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

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

@@ -0,0 +1,33 @@
+/**
+ * Hold a producer's answer to the work order (expected.ts — the engine's manifest) BEFORE it is
+ * frozen or sent. Mirrors
+ * the engine's fact-coverage check exactly — the engine would answer
+ * `unusable` (billed zero) to the same faults, but on our side each one is a producer bug worth
+ * surfacing loudly, so the kit refuses first: every declared name present as an `ok`/`error` fact,
+ * an `ok` value of the declared type (`boolean` ⇒ a JS boolean; `score` ⇒ an INTEGER 0..10000,
+ * never clamped), an `error` carrying the rubric's own `onError`, the wire shape itself, and NO
+ * undeclared names — the engine ignores an extra name, but a rule can never read it, so here it is
+ * a bug. The same rule for the oracle-side dup/rate facts: `unique` /
+ * `frequency` present iff the manifest declares the rule, of the wire shape the engine validates,
+ * naming the declared rule — a `frequency` declaration the manifest sent without `max`/`per`
+ * cannot be run by anyone, so its absence is refused with that message (our/the engine's bug).
+ *
+ * Issue codes match the engine's reason codes (`FACT_MISSING`, `FACT_KIND`) where both sides check
+ * the same thing, so logs read the same on both; the rest are ours. Pure.
+ */
+import type { ExpectedFacts } from "./expected.js";
+import type { ProducedFacts } from "./producer.js";
+export interface FactIssue {
+    code: "FACT_MISSING" | "FACT_EXTRA" | "FACT_KIND" | "FACT_ON_ERROR" | "FACT_SHAPE";
+    /** `/facts/ext/<name>` · `/facts/ai/<name>` · `/facts/unique` · `/facts/frequency` — the engine's own path convention. */
+    path: string;
+    message: string;
+}
+export type ValidateResult = {
+    ok: true;
+} | {
+    ok: false;
+    issues: FactIssue[];
+};
+export declare function validateFacts(produced: ProducedFacts, expected: ExpectedFacts): ValidateResult;
+//# sourceMappingURL=validate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/lib/facts/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,eAAe,GAAG,YAAY,CAAC;IACnF,0HAA0H;IAC1H,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC;AAM/E,wBAAgB,aAAa,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,aAAa,GAAG,cAAc,CA4I9F"}

package/dist/lib/facts/validate.js

@@ -0,0 +1,137 @@
+/**
+ * Hold a producer's answer to the work order (expected.ts — the engine's manifest) BEFORE it is
+ * frozen or sent. Mirrors
+ * the engine's fact-coverage check exactly — the engine would answer
+ * `unusable` (billed zero) to the same faults, but on our side each one is a producer bug worth
+ * surfacing loudly, so the kit refuses first: every declared name present as an `ok`/`error` fact,
+ * an `ok` value of the declared type (`boolean` ⇒ a JS boolean; `score` ⇒ an INTEGER 0..10000,
+ * never clamped), an `error` carrying the rubric's own `onError`, the wire shape itself, and NO
+ * undeclared names — the engine ignores an extra name, but a rule can never read it, so here it is
+ * a bug. The same rule for the oracle-side dup/rate facts: `unique` /
+ * `frequency` present iff the manifest declares the rule, of the wire shape the engine validates,
+ * naming the declared rule — a `frequency` declaration the manifest sent without `max`/`per`
+ * cannot be run by anyone, so its absence is refused with that message (our/the engine's bug).
+ *
+ * Issue codes match the engine's reason codes (`FACT_MISSING`, `FACT_KIND`) where both sides check
+ * the same thing, so logs read the same on both; the rest are ours. Pure.
+ */
+import { AiFact, ExtFact, FrequencyFact, UniqueFact } from "./factset.js";
+/** A Zod failure as one line — paths and messages only (identifiers, never values). */
+const zodDetail = (issues) => issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+export function validateFacts(produced, expected) {
+    const issues = [];
+    const issue = (code, path, message) => {
+        issues.push({ code, path, message });
+    };
+    // A custom producer is untyped at runtime — a missing/non-object lane is a shape fault, not a crash.
+    const lane = (kind) => {
+        const value = produced?.[kind];
+        if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+            return value;
+        }
+        issue("FACT_SHAPE", `/facts/${kind}`, `expected an object of facts, got ${typeof value}`);
+        return {};
+    };
+    const ext = lane("ext");
+    const ai = lane("ai");
+    for (const [name, source] of Object.entries(expected.ext)) {
+        const path = `/facts/ext/${name}`;
+        if (!(name in ext)) {
+            issue("FACT_MISSING", path, `declared source '${name}' was not produced`);
+            continue;
+        }
+        const parsed = ExtFact.safeParse(ext[name]);
+        if (!parsed.success) {
+            issue("FACT_SHAPE", path, zodDetail(parsed.error.issues));
+            continue;
+        }
+        const fact = parsed.data;
+        if (fact.status === "error") {
+            if (fact.onError !== source.onError) {
+                issue("FACT_ON_ERROR", path, `error fact carries onError '${fact.onError}', the rubric declares '${source.onError}'`);
+            }
+            continue;
+        }
+        if (source.expect === "boolean" && typeof fact.value !== "boolean") {
+            issue("FACT_KIND", path, `expected a boolean value, got ${typeof fact.value}`);
+        }
+        else if (source.expect === "score" &&
+            (typeof fact.value !== "number" ||
+                !Number.isInteger(fact.value) ||
+                fact.value < 0 ||
+                fact.value > 10000)) {
+            issue("FACT_KIND", path, "expected an integer score between 0 and 10000");
+        }
+    }
+    for (const [name, check] of Object.entries(expected.ai)) {
+        const path = `/facts/ai/${name}`;
+        if (!(name in ai)) {
+            issue("FACT_MISSING", path, `declared AI check '${name}' was not produced`);
+            continue;
+        }
+        const parsed = AiFact.safeParse(ai[name]);
+        if (!parsed.success) {
+            issue("FACT_SHAPE", path, zodDetail(parsed.error.issues));
+            continue;
+        }
+        const fact = parsed.data;
+        if (fact.status === "error" && fact.onError !== check.onError) {
+            issue("FACT_ON_ERROR", path, `error fact carries onError '${fact.onError}', the rubric declares '${check.onError}'`);
+        }
+        // `expect` is boolean-only for AI checks and `AiFact` already types `value` as one.
+    }
+    for (const name of Object.keys(ext)) {
+        if (!(name in expected.ext)) {
+            issue("FACT_EXTRA", `/facts/ext/${name}`, `'${name}' is not a source the rubric declares`);
+        }
+    }
+    for (const name of Object.keys(ai)) {
+        if (!(name in expected.ai)) {
+            issue("FACT_EXTRA", `/facts/ai/${name}`, `'${name}' is not an AI check the rubric declares`);
+        }
+    }
+    // The dup/rate facts: one each, iff declared. `produced` is untyped at runtime (a custom
+    // producer), so both are read as unknown and parsed to the engine's wire shape.
+    const singles = produced;
+    if (expected.unique) {
+        const path = "/facts/unique";
+        const fact = singles.unique;
+        if (fact === undefined) {
+            issue("FACT_MISSING", path, `declared unique rule '${expected.unique.ruleId}' was not produced`);
+        }
+        else {
+            const parsed = UniqueFact.safeParse(fact);
+            if (!parsed.success)
+                issue("FACT_SHAPE", path, zodDetail(parsed.error.issues));
+            else if (parsed.data.ruleId !== expected.unique.ruleId) {
+                issue("FACT_KIND", path, `unique fact names rule '${parsed.data.ruleId}', the manifest declares '${expected.unique.ruleId}'`);
+            }
+        }
+    }
+    else if (singles.unique !== undefined) {
+        issue("FACT_EXTRA", "/facts/unique", "the rubric declares no unique rule");
+    }
+    if (expected.frequency) {
+        const path = "/facts/frequency";
+        const fact = singles.frequency;
+        const { ruleId, max, per } = expected.frequency;
+        if (fact === undefined) {
+            issue("FACT_MISSING", path, max === undefined || per === undefined
+                ? "manifest lacks max/per"
+                : `declared frequency rule '${ruleId}' was not produced`);
+        }
+        else {
+            const parsed = FrequencyFact.safeParse(fact);
+            if (!parsed.success)
+                issue("FACT_SHAPE", path, zodDetail(parsed.error.issues));
+            else if (parsed.data.ruleId !== ruleId) {
+                issue("FACT_KIND", path, `frequency fact names rule '${parsed.data.ruleId}', the manifest declares '${ruleId}'`);
+            }
+        }
+    }
+    else if (singles.frequency !== undefined) {
+        issue("FACT_EXTRA", "/facts/frequency", "the rubric declares no frequency rule");
+    }
+    return issues.length === 0 ? { ok: true } : { ok: false, issues };
+}
+//# sourceMappingURL=validate.js.map

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

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

package/dist/lib/hash.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Generic content hashing. `sha256Hex` is the one primitive several unrelated corners share —
+ * rubric ids (§A.10), UCAN token cache keys, claim workflow ids — so it lives in a neutral home
+ * rather than inside any one of them (e.g. rubric resolution should not reach into `ixo/ucan` for
+ * a hash). `cidForBytes` is the claim lane's content address, kept beside it for the same reason.
+ */
+import type { ApiClaimContent } from "./engine/types.js";
+/** Hex SHA-256 of a string or raw bytes (cache keys, rubric ids — never for secrets in logs). */
+export declare function sha256Hex(input: Uint8Array | string): Promise<string>;
+/**
+ * Canonical JSON: recursively sorted keys, no whitespace — so the same value always serializes to
+ * the same bytes. Feeds `resultDigest = sha256(canonicalJson(decision + trace))` (evaluator §9),
+ * the same convention the editor uses to make a rubric's id stable.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * The Decision API claim's content id (contract "The claim content and `contentDigest`"): the SAME
+ * function the engine and the client SDK run, held to `test/fixtures/content-digest-vectors.json`.
+ * Not the idempotency `requestDigest` — that one covers the transport too. Key order is JavaScript's
+ * (integer-like keys first, ascending; then the rest by UTF-16 code unit): a non-JS implementation
+ * must reproduce it — the vectors pin it.
+ */
+export declare function contentDigest(content: ApiClaimContent): Promise<string>;
+/**
+ * The claim lane's content address — CIDv1, `raw` codec (0x55), sha2-256, base32 (`bafkrei…`).
+ * A claim's id IS this CID of its stored body: `ixo-oracles-cli/src/utils/createCIDFromBase64.ts`
+ * builds exactly `CID.create(1, 0x55, sha256(bytes))`, and the Matrix claim bot's `generateCid`
+ * (`ipfs-only-hash` with `cidVersion:1, rawLeaves:true, leafType:'raw'`) produces the identical
+ * string up to its 256 KiB chunk size (beyond it the importer builds a dag-pb root, so a larger body
+ * never matches — ENGINE-CONTRACT treats it as unverifiable). The cellnode lane verifies a body against its claim id with
+ * this (ixo/cellnode.ts) — so it must be byte-identical to the fleet's, hence `multiformats`
+ * rather than a hand-rolled base32: a subtle encoder bug would only surface as every cellnode
+ * claim failing closed.
+ *
+ * NOT the rubric convention: the portal's `publicUploadToMatrix` returns a bare hex sha256 it
+ * calls a "simplified CID", which is why `rubricId` is hex.
+ */
+export declare function cidForBytes(bytes: Uint8Array): Promise<string>;
+/** The same CID from a sha2-256 digest already computed — for bytes hashed incrementally as they
+ *  stream (the data export, `routes/v1/api/export.ts`), never held whole. */
+export declare function cidForSha256(digest: Uint8Array): string;
+/** Chunked btoa — platform-native base64 without blowing the stack on a large attachment. */
+export declare function base64Of(bytes: Uint8Array): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/lib/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/lib/hash.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,iGAAiG;AACjG,wBAAsB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAI3E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAeD;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAE7E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAGpE;AAED;6EAC6E;AAC7E,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAEvD;AAED,6FAA6F;AAC7F,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAOlD"}