@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/lib/facts/stock/ext-source.js

@@ -0,0 +1,201 @@
+/**
+ * The external-source connector (§A.14) — the stock way a rubric's `ext.<name>` gets its value: a
+ * self-signed UCAN invocation minted to the source's did:web audience, the declared `send` payload
+ * (plus the whole claim body) POSTed under the retry budget, the strict §A.14.3 contract read, and
+ * the frozen transcript. Run as the stock `ext` lane (../tools.ts `stockLanes`) for every source in
+ * the work order; a provider's handler may wrap it (`tools.stock()`) or replace it per name.
+ *
+ * `sourceEndpointUrl` / `readSourceContract` are the engine's own (its editor "Test" harness shares
+ * them).
+ *
+ * What the oracle's key signs is ITS DEVELOPER's choice, never the rubric's. The rubric belongs to
+ * the protocol — written by its owner, shared by every oracle serving it — so it may say WHERE to
+ * call (endpoint + audience) and WHAT to send, never what this oracle's key grants: a rubric that
+ * could name the capability could mint itself a token for any service that trusts this oracle's
+ * did:web. So the stock lane signs `DEFAULT_CAPABILITY` only (a declared `capability` is logged
+ * and ignored), signs only for an audience that IS the endpoint's own did:web, and never an IXO
+ * service resource (`assertExternalCapability`). A developer who needs another capability sets it
+ * in their own handler: `tools.http.json(url, { ucan: { capability } })`, signed for that URL's host.
+ */
+import { AppError } from "../../errors.js";
+import { mintInvocation } from "../../ixo/ucan.js";
+import { callWithRetryBudget, isTruncated } from "./call.js";
+import { assertExternalCapability, DEFAULT_CAPABILITY, urlAudience } from "./capability.js";
+// 15s, not 5s: a compliant source may legitimately need seconds per call — a live CRM-lookup lane
+// measured ~4–4.6s end-to-end on a warehouse miss, which left a 5s attempt no headroom and read as
+// `unreachable: TimeoutError` after retries. Matches http/client.ts's default.
+const DEFAULT_TIMEOUT_MS = 15_000;
+/**
+ * Endpoint policy (§A.14.2): HTTPS everywhere, HTTP only in development. Throws a 400-shaped
+ * AppError — the caller turns it into the unreachable path.
+ */
+export function sourceEndpointUrl(config, endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw AppError.badRequest(`Source endpoint is not a valid URL: ${endpoint}`);
+    }
+    const httpsOnly = url.protocol === "https:";
+    const httpInDev = url.protocol === "http:" && config.ENVIRONMENT === "development";
+    if (!httpsOnly && !httpInDev) {
+        throw AppError.badRequest("Source endpoint must be https (http is allowed only in development)");
+    }
+    return url;
+}
+/**
+ * The strict §A.14.3 response contract. Extra keys are ignored (it's their API); a missing/wrong-typed
+ * declared field is a contract MISS — the unreachable path, never a `valid:false`.
+ */
+export function readSourceContract(expect, body) {
+    const reason = typeof body.reason === "string" ? body.reason : null;
+    if (expect === "boolean") {
+        if (typeof body.valid !== "boolean") {
+            return { ok: false, value: false, reason, detail: "expected a boolean `valid` field" };
+        }
+        return { ok: true, value: body.valid, reason, detail: "" };
+    }
+    const score = body.score;
+    if (typeof score !== "number" || !Number.isInteger(score) || score < 0 || score > 10000) {
+        return {
+            ok: false,
+            value: 0,
+            reason,
+            detail: "expected an integer `score` between 0 and 10000",
+        };
+    }
+    return { ok: true, value: score, reason, detail: "" };
+}
+/** One external source (§A.14): self-signed UCAN, idempotency key `{claimId}:{sourceName}`. */
+export async function resolveExtSource(input, deps) {
+    const { claim, name, source } = input;
+    const { onError } = source;
+    // The whole credentialSubject rides ALONGSIDE the declared `send` refs (reversing §A.14.2's
+    // "declared refs only"): a source needs the full body, not just
+    // what the rubric thought to name. `claimBody` is the reserved key — a `send` entry of the same
+    // name loses, so every source parses the same shape regardless of rubric. The TRACE records it
+    // verbatim too: "why did the engine decide this?" must show the literal payload the source saw.
+    const body = { ...input.payload, claimBody: claim.body };
+    // Endpoint policy (https in prod) — a policy violation is the unreachable path, not a verdict.
+    let url;
+    try {
+        url = sourceEndpointUrl(deps.config, source.endpoint);
+    }
+    catch (err) {
+        return {
+            status: "error",
+            onError,
+            detail: err instanceof Error ? err.message : String(err),
+            transcript: {
+                request: { url: source.endpoint, body, headers: {} },
+                response: null,
+                attempts: 0,
+                elapsedMs: 0,
+            },
+        };
+    }
+    // Audience bound to the endpoint: a token is only ever signed for the host it is POSTed to. A
+    // mismatch is the same deterministic outcome as a policy violation — nothing signed, nothing sent.
+    const expectedAudience = urlAudience(url);
+    if (source.audience !== expectedAudience) {
+        return {
+            status: "error",
+            onError,
+            detail: `the source's audience ${source.audience} must be the endpoint's own did:web (${expectedAudience}); nothing was signed or sent`,
+            transcript: {
+                request: { url: source.endpoint, body, headers: {} },
+                response: null,
+                attempts: 0,
+                elapsedMs: 0,
+            },
+        };
+    }
+    // The rubric's `capability` is never signed (header) — say so once per call, shape only.
+    if (source.capability)
+        deps.logger.warn("ext.source.capability-ignored", { source: name });
+    // Defensive: DEFAULT_CAPABILITY passes by construction; the check guards a future edit.
+    assertExternalCapability(DEFAULT_CAPABILITY);
+    let token;
+    try {
+        const minted = await mintInvocation(deps.config, {
+            audience: expectedAudience,
+            // The UCAN lib brands {can,with}; the constant is a plain literal — cast.
+            capability: DEFAULT_CAPABILITY,
+            ttlSec: 300,
+            unique: true,
+        });
+        token = minted.token;
+    }
+    catch (err) {
+        // Our signing/config fault — surface loudly (workflow retries), never a silent verdict.
+        throw err instanceof AppError
+            ? err
+            : AppError.internal("Failed to mint source invocation", err);
+    }
+    // Live-integration visibility while a source is being wired up — `info`, not `debug`, since
+    // deployed envs run at LOG_LEVEL=info. Never the claim body itself: `body` carries `claimBody`
+    // (submitter answers, possible PII) alongside `send`'s resolved values — the "answers never
+    // logged" posture that `UNIQUE_HMAC_KEY` exists for elsewhere. Only the `send` KEYS (the shape
+    // the rubric declared, not what it resolved to) are worth a log line here.
+    deps.logger.info("ext.source.request", {
+        source: name,
+        url: url.toString(),
+        sendKeys: Object.keys(input.payload),
+    });
+    const outcome = await callWithRetryBudget(deps, url.toString(), body, {
+        authorization: `Bearer ${token}`,
+        "x-auth-type": "ucan",
+        "idempotency-key": `${claim.claimId}:${name}`,
+    }, source.timeoutMs ?? DEFAULT_TIMEOUT_MS, (parsed) => {
+        const contract = readSourceContract(source.expect, parsed);
+        return contract.ok
+            ? {
+                ok: true,
+                value: { value: contract.value, reason: contract.reason },
+            }
+            : { ok: false, detail: contract.detail };
+    });
+    // The shape of the answer, never the answer: `value`/`reason` are a fact about the claim and the
+    // response body is an external service's raw words about it (observability spec §3). Both stay
+    // on the frozen transcript, which is where debugging a source reads them.
+    const response = outcome.transcript.response?.body;
+    deps.logger.info("ext.source", {
+        source: name,
+        ok: outcome.ok,
+        valueType: outcome.value ? typeof outcome.value.value : null,
+        hasReason: outcome.value?.reason != null,
+        detail: outcome.detail || null,
+        httpStatus: outcome.transcript.response?.status ?? null,
+        // A truncated body's own byte count — the digest stand-in's length says nothing (call.ts).
+        responseBytes: response == null
+            ? null
+            : isTruncated(response)
+                ? response.bytes
+                : JSON.stringify(response).length,
+        attempts: outcome.transcript.attempts,
+        elapsedMs: outcome.transcript.elapsedMs,
+    });
+    // Down is not "no" (P0-7): a network error, timeout, 5xx or 429 past the in-call budget THROWS
+    // so the workflow step retries (runner.ts lets `unavailable` out; on the step's LAST attempt it
+    // freezes the rubric's onError instead, so an outage never retries for ever). Only a definitive
+    // answer — a 4xx refusal, a malformed or off-contract body — becomes the error fact below.
+    if (!outcome.ok && outcome.transient) {
+        throw AppError.unavailable(`external source '${name}' ${outcome.detail}${outcome.retryAfterMs !== null ? ` (Retry-After ${outcome.retryAfterMs} ms)` : ""}`);
+    }
+    if (!outcome.ok || outcome.value === null) {
+        return {
+            status: "error",
+            onError,
+            detail: outcome.detail,
+            transcript: outcome.transcript,
+        };
+    }
+    return {
+        status: "ok",
+        value: outcome.value.value,
+        reason: outcome.value.reason,
+        transcript: outcome.transcript,
+    };
+}
+//# sourceMappingURL=ext-source.js.map

package/dist/lib/facts/stock/ext-source.js.map

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

package/dist/lib/facts/stock/frequency-fact.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The frequency rule's PURE half (spec §13, "X claims per period per submitter"): calendar-window
+ * math and the frozen-fact constructors — no I/O and no clock, the window derives from the claim's
+ * own on-chain `submissionDate` (§13.2: the chain's clock, never evaluation time).
+ *
+ * Split out of frequency.ts, which reaches Blocksync for the one count it freezes: the testing
+ * subpath's default frequency lane (src/testing/index.ts) needs `unresolvedFrequencyFact` and must
+ * stay loadable in plain node. frequency.ts re-exports everything here, so its importers are
+ * unchanged — the same move `flattenCtx` made into send.ts.
+ */
+import type { FrequencyPeriod } from "./rule-defaults.js";
+export type { FrequencyPeriod } from "./rule-defaults.js";
+/**
+ * Blocksync returns `submissionDate` WITHOUT a zone suffix (`…T16:57:29.774`) and means
+ * UTC — but bare `new Date(...)` parses a suffix-less datetime as LOCAL time, which would shift
+ * boundary claims into the wrong window depending on where the isolate runs. So a datetime with no
+ * declared zone gets pinned to UTC before any window math.
+ */
+export declare const HAS_ZONE: RegExp;
+/** Calendar window (UTC) containing `submissionDateISO`. Weeks are ISO weeks (Monday 00:00 UTC). */
+export declare function windowOf(submissionDateISO: string, per: FrequencyPeriod): {
+    startISO: string;
+    endISO: string;
+};
+/**
+ * What freezes into the FactSet for one frequency rule — the engine's `decide()` reads this and
+ * nothing else. A `type` (not an `interface`) for the same assignability reason as
+ * unique-score.ts's `UniqueFact`: the wire shape in factset.ts is loose.
+ */
+export type FrequencyFact = {
+    ruleId: string;
+    count: number;
+    max: number;
+    per: FrequencyPeriod;
+    /** null only on an `unresolved` fact whose window could not even be derived (no submitter or
+     *  no usable on-chain submissionDate) — decide never reads the window, only the trace shows it. */
+    windowStartISO: string | null;
+    windowEndISO: string | null;
+    /** count > max — the count INCLUDES the claim itself (it's on chain by evaluation time). */
+    breach: boolean;
+    /** No countable window (no submitter, no usable chain timestamp) — the engine routes this to a
+     *  fail-closed reject (§13.5). Never an outage: a failed count throws and the step retries. */
+    unresolved?: true;
+};
+/** The fail-closed fact for a window that never derived (§13.5): no submitter, no chain
+ *  timestamp, or a garbage one — never a pass, never a breach, and never a throw. */
+export declare function unresolvedFrequencyFact(params: {
+    ruleId: string;
+    max: number;
+    per: FrequencyPeriod;
+}): FrequencyFact;
+export declare function frequencyFactOf(params: {
+    ruleId: string;
+    max: number;
+    per: FrequencyPeriod;
+    submissionDateISO: string;
+    count: number | null;
+}): FrequencyFact;
+//# sourceMappingURL=frequency-fact.d.ts.map

package/dist/lib/facts/stock/frequency-fact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frequency-fact.d.ts","sourceRoot":"","sources":["../../../../src/lib/facts/stock/frequency-fact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,QAA6B,CAAC;AAcnD,oGAAoG;AACpG,wBAAgB,QAAQ,CACtB,iBAAiB,EAAE,MAAM,EACzB,GAAG,EAAE,eAAe,GACnB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA2BtC;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,eAAe,CAAC;IACrB;uGACmG;IACnG,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4FAA4F;IAC5F,MAAM,EAAE,OAAO,CAAC;IAChB;mGAC+F;IAC/F,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB,CAAC;AAEF;qFACqF;AACrF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,eAAe,CAAC;CACtB,GAAG,aAAa,CAWhB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,eAAe,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,GAAG,aAAa,CAahB"}

package/dist/lib/facts/stock/frequency-fact.js

@@ -0,0 +1,86 @@
+/**
+ * The frequency rule's PURE half (spec §13, "X claims per period per submitter"): calendar-window
+ * math and the frozen-fact constructors — no I/O and no clock, the window derives from the claim's
+ * own on-chain `submissionDate` (§13.2: the chain's clock, never evaluation time).
+ *
+ * Split out of frequency.ts, which reaches Blocksync for the one count it freezes: the testing
+ * subpath's default frequency lane (src/testing/index.ts) needs `unresolvedFrequencyFact` and must
+ * stay loadable in plain node. frequency.ts re-exports everything here, so its importers are
+ * unchanged — the same move `flattenCtx` made into send.ts.
+ */
+/**
+ * Blocksync returns `submissionDate` WITHOUT a zone suffix (`…T16:57:29.774`) and means
+ * UTC — but bare `new Date(...)` parses a suffix-less datetime as LOCAL time, which would shift
+ * boundary claims into the wrong window depending on where the isolate runs. So a datetime with no
+ * declared zone gets pinned to UTC before any window math.
+ */
+export const HAS_ZONE = /(?:Z|[+-]\d{2}:?\d{2})$/i;
+function parseUtc(submissionDateISO) {
+    const pinned = submissionDateISO.includes("T") && !HAS_ZONE.test(submissionDateISO)
+        ? `${submissionDateISO}Z`
+        : submissionDateISO;
+    const at = new Date(pinned);
+    if (Number.isNaN(at.getTime())) {
+        throw new Error(`frequency: unparseable submission date "${submissionDateISO}"`);
+    }
+    return at;
+}
+/** Calendar window (UTC) containing `submissionDateISO`. Weeks are ISO weeks (Monday 00:00 UTC). */
+export function windowOf(submissionDateISO, per) {
+    const at = parseUtc(submissionDateISO);
+    const [y, m, d] = [at.getUTCFullYear(), at.getUTCMonth(), at.getUTCDate()];
+    let start;
+    let end;
+    switch (per) {
+        case "day":
+            start = Date.UTC(y, m, d);
+            end = Date.UTC(y, m, d + 1); // Date.UTC rolls overflow forward — month/year ends included.
+            break;
+        case "week": {
+            // getUTCDay() is 0=Sunday; ISO weeks start Monday, so shift to days-since-Monday first.
+            const sinceMonday = (at.getUTCDay() + 6) % 7;
+            start = Date.UTC(y, m, d - sinceMonday);
+            end = Date.UTC(y, m, d - sinceMonday + 7);
+            break;
+        }
+        case "month":
+            start = Date.UTC(y, m, 1);
+            end = Date.UTC(y, m + 1, 1);
+            break;
+        case "year":
+            start = Date.UTC(y, 0, 1);
+            end = Date.UTC(y + 1, 0, 1);
+            break;
+    }
+    return { startISO: new Date(start).toISOString(), endISO: new Date(end).toISOString() };
+}
+/** The fail-closed fact for a window that never derived (§13.5): no submitter, no chain
+ *  timestamp, or a garbage one — never a pass, never a breach, and never a throw. */
+export function unresolvedFrequencyFact(params) {
+    return {
+        ruleId: params.ruleId,
+        count: 0,
+        max: params.max,
+        per: params.per,
+        windowStartISO: null,
+        windowEndISO: null,
+        breach: false,
+        unresolved: true,
+    };
+}
+export function frequencyFactOf(params) {
+    const { startISO, endISO } = windowOf(params.submissionDateISO, params.per);
+    const shared = {
+        ruleId: params.ruleId,
+        max: params.max,
+        per: params.per,
+        windowStartISO: startISO,
+        windowEndISO: endISO,
+    };
+    // §13.5 fail closed: an uncountable window (a claim source with no submitter to count) is never
+    // a pass and never a breach — `unresolved` is its own state, never read as headroom.
+    if (params.count === null)
+        return { ...shared, count: 0, breach: false, unresolved: true };
+    return { ...shared, count: params.count, breach: params.count > params.max };
+}
+//# sourceMappingURL=frequency-fact.js.map

package/dist/lib/facts/stock/frequency-fact.js.map

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

package/dist/lib/facts/stock/frequency.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The frequency rule (spec §13, "X claims per period per submitter") — the stock producer's
+ * `frequency` fact. The pure half (calendar-window math and the frozen-fact constructors) lives in
+ * frequency-fact.ts and is re-exported here, so this module's importers see one thing; the resolve
+ * half is below: ONE Blocksync count (`countAgentClaimsInWindow`) freezes into the fact, so the
+ * ENGINE's `decide()` compares two integers and stays pure (§13.6 — its `frequencyFlagOf`). Ported
+ * Frequency counting is oracle-side.
+ */
+import { type BlocksyncDeps } from "../../ixo/blocksync/index.js";
+import { type FrequencyFact } from "./frequency-fact.js";
+import type { FrequencyRule } from "./rule-defaults.js";
+export type { FrequencyFact, FrequencyPeriod } from "./frequency-fact.js";
+export { frequencyFactOf, HAS_ZONE, unresolvedFrequencyFact, windowOf } from "./frequency-fact.js";
+/**
+ * The frequency resolver (spec §13): the claim's own on-chain `submissionDate` picks the calendar
+ * window (§13.2 — the chain's clock, never evaluation time), and ONE Blocksync count freezes into
+ * the fact. Only the DETERMINISTIC uncountables — no submitter, no/garbage chain timestamp — freeze
+ * `unresolved` (the engine fails that closed, §13.5). Blocksync down is not one of them: the count
+ * throws `unavailable` and the workflow step retries (P0-2), because `unresolved` is a final reject
+ * and an outage is not evidence of anything.
+ *
+ * `count` is the claim source's (Go Prod §7.1 `countSubmissions`, bound to this claim): given, it
+ * replaces the Blocksync read, and the caller has already settled that there is a submitter.
+ */
+export declare function resolveFrequency(deps: BlocksyncDeps, input: {
+    rule: Pick<FrequencyRule, "id" | "max" | "per">;
+    collectionId: string;
+    agentAddress: string | null;
+    submissionDateISO: string | null;
+    count?: (from: Date, to: Date) => Promise<number | null>;
+}): Promise<FrequencyFact>;
+//# sourceMappingURL=frequency.d.ts.map

package/dist/lib/facts/stock/frequency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frequency.d.ts","sourceRoot":"","sources":["../../../../src/lib/facts/stock/frequency.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,aAAa,EAA4B,MAAM,qBAAqB,CAAC;AACnF,OAAO,EACL,KAAK,aAAa,EAInB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,uBAAuB,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEhG;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE;IACL,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,KAAK,GAAG,KAAK,CAAC,CAAC;IAChD,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D,GACA,OAAO,CAAC,aAAa,CAAC,CAqBxB"}

package/dist/lib/facts/stock/frequency.js

@@ -0,0 +1,48 @@
+/**
+ * The frequency rule (spec §13, "X claims per period per submitter") — the stock producer's
+ * `frequency` fact. The pure half (calendar-window math and the frozen-fact constructors) lives in
+ * frequency-fact.ts and is re-exported here, so this module's importers see one thing; the resolve
+ * half is below: ONE Blocksync count (`countAgentClaimsInWindow`) freezes into the fact, so the
+ * ENGINE's `decide()` compares two integers and stays pure (§13.6 — its `frequencyFlagOf`). Ported
+ * Frequency counting is oracle-side.
+ */
+import { countAgentClaimsInWindow } from "../../ixo/blocksync/index.js";
+import { frequencyFactOf, unresolvedFrequencyFact, windowOf, } from "./frequency-fact.js";
+export { frequencyFactOf, HAS_ZONE, unresolvedFrequencyFact, windowOf } from "./frequency-fact.js";
+/**
+ * The frequency resolver (spec §13): the claim's own on-chain `submissionDate` picks the calendar
+ * window (§13.2 — the chain's clock, never evaluation time), and ONE Blocksync count freezes into
+ * the fact. Only the DETERMINISTIC uncountables — no submitter, no/garbage chain timestamp — freeze
+ * `unresolved` (the engine fails that closed, §13.5). Blocksync down is not one of them: the count
+ * throws `unavailable` and the workflow step retries (P0-2), because `unresolved` is a final reject
+ * and an outage is not evidence of anything.
+ *
+ * `count` is the claim source's (Go Prod §7.1 `countSubmissions`, bound to this claim): given, it
+ * replaces the Blocksync read, and the caller has already settled that there is a submitter.
+ */
+export async function resolveFrequency(deps, input) {
+    const { rule } = input;
+    const shared = { ruleId: rule.id, max: rule.max, per: rule.per };
+    if (!input.submissionDateISO)
+        return unresolvedFrequencyFact(shared);
+    if (!input.count && !input.agentAddress)
+        return unresolvedFrequencyFact(shared);
+    let window;
+    try {
+        window = windowOf(input.submissionDateISO, rule.per);
+    }
+    catch {
+        // A garbage chain timestamp is deterministic — a retried step can't fix it (§13.5).
+        return unresolvedFrequencyFact(shared);
+    }
+    const count = input.count
+        ? await input.count(new Date(window.startISO), new Date(window.endISO))
+        : await countAgentClaimsInWindow(deps, {
+            collectionId: input.collectionId,
+            agentAddress: input.agentAddress,
+            fromISO: window.startISO,
+            toISO: window.endISO,
+        });
+    return frequencyFactOf({ ...shared, submissionDateISO: input.submissionDateISO, count });
+}
+//# sourceMappingURL=frequency.js.map

package/dist/lib/facts/stock/frequency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frequency.js","sourceRoot":"","sources":["../../../../src/lib/facts/stock/frequency.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAsB,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAEL,eAAe,EACf,uBAAuB,EACvB,QAAQ,GACT,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,uBAAuB,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEhG;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAmB,EACnB,KAMC;IAED,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IACvB,MAAM,MAAM,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;IACjE,IAAI,CAAC,KAAK,CAAC,iBAAiB;QAAE,OAAO,uBAAuB,CAAC,MAAM,CAAC,CAAC;IACrE,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,YAAY;QAAE,OAAO,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAChF,IAAI,MAA4C,CAAC;IACjD,IAAI,CAAC;QACH,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,iBAAiB,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,oFAAoF;QACpF,OAAO,uBAAuB,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK;QACvB,CAAC,CAAC,MAAM,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACvE,CAAC,CAAC,MAAM,wBAAwB,CAAC,IAAI,EAAE;YACnC,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,YAAY,EAAE,KAAK,CAAC,YAAsB;YAC1C,OAAO,EAAE,MAAM,CAAC,QAAQ;YACxB,KAAK,EAAE,MAAM,CAAC,MAAM;SACrB,CAAC,CAAC;IACP,OAAO,eAAe,CAAC,EAAE,GAAG,MAAM,EAAE,iBAAiB,EAAE,KAAK,CAAC,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC;AAC3F,CAAC"}

package/dist/lib/facts/stock/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The batteries-included lanes — what runs for every name a provider did NOT list in
+ * `defineFacts({...})`, and therefore for every name at all when the oracle config declares no
+ * `facts`: every `ext` source through the self-signed UCAN HTTP connector (ext-source.ts), every
+ * `ai` check through OpenRouter (ai-check.ts — the ai-inputs.ts lanes, archive.ts ZIP expansion,
+ * the c2pa.ts provenance short-circuit), the `unique` fact through the duplicate lane (unique.ts —
+ * this oracle's D1 registries, the pHash + near-text lanes, the gray-zone judge) and the
+ * `frequency` fact through ONE Blocksync count (frequency.ts) — the last two iff the manifest
+ * declares the rule (duplicate detection is oracle-side). The oracle's
+ * `settings.allowAiChecks` / `allowImageChecks` gates live inside the AI connector and the judge,
+ * so a disabled lane still yields its `error` fact with the rubric's `onError` (or a judge-skipped
+ * fact) — never an approve.
+ *
+ * This module is now just the connectors' front door: the lanes themselves are adapted in
+ * ../tools.ts (`stockLanes`), the fan-out/cache/normalization/fail-closed discipline belongs to
+ * ../runner.ts, and the stock producer is `producerOf` with an EMPTY handler table — literally the
+ * same wiring a provider's `defineFacts({...})` runs through, which is what makes the guarantees
+ * identical for both.
+ */
+import type { FactsProducer } from "../producer.js";
+export { resolveAiCheck } from "./ai-check.js";
+export { resolveExtSource } from "./ext-source.js";
+export { resolveFrequency } from "./frequency.js";
+export { resolveUnique } from "./unique.js";
+/** The stock producer: no custom handlers at all, so every declared name runs its stock lane. */
+export declare const stockProducer: FactsProducer;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/facts/stock/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/facts/stock/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,iGAAiG;AACjG,eAAO,MAAM,aAAa,EAAE,aAA2C,CAAC"}

package/dist/lib/facts/stock/index.js

@@ -0,0 +1,28 @@
+/**
+ * The batteries-included lanes — what runs for every name a provider did NOT list in
+ * `defineFacts({...})`, and therefore for every name at all when the oracle config declares no
+ * `facts`: every `ext` source through the self-signed UCAN HTTP connector (ext-source.ts), every
+ * `ai` check through OpenRouter (ai-check.ts — the ai-inputs.ts lanes, archive.ts ZIP expansion,
+ * the c2pa.ts provenance short-circuit), the `unique` fact through the duplicate lane (unique.ts —
+ * this oracle's D1 registries, the pHash + near-text lanes, the gray-zone judge) and the
+ * `frequency` fact through ONE Blocksync count (frequency.ts) — the last two iff the manifest
+ * declares the rule (duplicate detection is oracle-side). The oracle's
+ * `settings.allowAiChecks` / `allowImageChecks` gates live inside the AI connector and the judge,
+ * so a disabled lane still yields its `error` fact with the rubric's `onError` (or a judge-skipped
+ * fact) — never an approve.
+ *
+ * This module is now just the connectors' front door: the lanes themselves are adapted in
+ * ../tools.ts (`stockLanes`), the fan-out/cache/normalization/fail-closed discipline belongs to
+ * ../runner.ts, and the stock producer is `producerOf` with an EMPTY handler table — literally the
+ * same wiring a provider's `defineFacts({...})` runs through, which is what makes the guarantees
+ * identical for both.
+ */
+import { defineFacts } from "../../../facts/fact.js";
+import { producerOf } from "../tools.js";
+export { resolveAiCheck } from "./ai-check.js";
+export { resolveExtSource } from "./ext-source.js";
+export { resolveFrequency } from "./frequency.js";
+export { resolveUnique } from "./unique.js";
+/** The stock producer: no custom handlers at all, so every declared name runs its stock lane. */
+export const stockProducer = producerOf(defineFacts({}));
+//# sourceMappingURL=index.js.map

package/dist/lib/facts/stock/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/facts/stock/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,iGAAiG;AACjG,MAAM,CAAC,MAAM,aAAa,GAAkB,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC"}

package/dist/lib/facts/stock/normalize.d.ts

@@ -0,0 +1,45 @@
+/**
+ * §4.1 canonicalization — the anti-sneak pipeline behind the duplicate-detection body digest
+ * (duplicate-claim spec §4 L1). Applied per LEAF value; `canonicalBody` walks the claim body.
+ *
+ * Pure module: no I/O, no clock, no bindings — it runs inside the resolve phase (unique.ts) but everything
+ * here is deterministic compute, so review-replay re-derives identical output from the same body.
+ *
+ * Pipeline order is normative (spec §4.1): 1 NFKC → 2 casefold → 3 strip Cf → 4 confusable fold
+ * → 5 collapse whitespace → 6 strip separators → 7 date/number canonical forms. Steps 6–7
+ * interlock: the date and number branches read the PRE-strip form, because step 6 destroys
+ * exactly the structure (hyphens, decimal dot) those branches canonicalize — a value that is
+ * neither gets the plain separator strip. `test/unique-normalize.test.ts` pins the equivalences.
+ */
+/**
+ * §4.1 step 4 — pinned TR39-style confusable tables. VERSIONED DATA: any edit shifts every
+ * registered digest, so it is a format change — bump the version, expect re-registration.
+ * Keys are the CASE-FOLDED forms (the fold runs after step 2), hence lowercase Cyrillic/Greek.
+ */
+export declare const CONFUSABLES_VERSION = 1;
+/**
+ * Normalize one leaf value per §4.1. `granularity` only applies when the value IS a date —
+ * it comes from the rule's `by` entry (`{ ref, granularity }`), whole-body mode never sets it.
+ */
+export declare function normalizeScalar(v: unknown, opts?: {
+    granularity?: "day" | "month" | "year";
+}): string;
+/**
+ * Canonicalize a pulled claim body (spec §3 step 1): drop the top-level `credentials` block
+ * (VC/proof noise — never part of what was claimed), deep-sort object keys, normalize every
+ * leaf. Arrays keep their order — position is meaning in SurveyJS answers.
+ *
+ * `normalizedText` is every normalized leaf joined with "" in traversal order — the trigram
+ * lane's input (L3), erasable PII where the digest is not.
+ */
+export declare function canonicalBody(body: Record<string, unknown>): {
+    canonical: Record<string, unknown>;
+    normalizedText: string;
+};
+/**
+ * Keyed digest for the registry (spec §4 L1): HMAC-SHA256 hex over `parts.join("")`. Keyed
+ * because answers are low-entropy PII — a plain hash is dictionary-reversible; the keyed digest
+ * is what lets `claim_body_digests` outlive lawful erasure of `normalizedText`.
+ */
+export declare function hmacDigest(key: string, parts: string[]): Promise<string>;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/lib/facts/stock/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../../../src/lib/facts/stock/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAkDrC;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,CAAC,EAAE,OAAO,EACV,IAAI,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,CAAA;CAAE,GAChD,MAAM,CA8BR;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC5D,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,cAAc,EAAE,MAAM,CAAC;CACxB,CAoBA;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAW9E"}