@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/lib/errors.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Typed application errors.
+ *
+ * Throw `AppError` (or one of its factories) anywhere in your logic. The global
+ * error handler maps it to a consistent JSON envelope, decides what is safe to
+ * expose to the client, and logs the rest. Unknown/unexpected throws are treated
+ * as 500s with their details hidden from clients.
+ */
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+export type ErrorCode = "BAD_REQUEST" | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "PAYMENT_REQUIRED" | "VALIDATION" | "RATE_LIMITED" | "INTERNAL" | "UNAVAILABLE" | "ATTESTATION_INVALID"
+/** The issuer publishes no such key — including a DID document that resolved and named no usable
+ *  Ed25519 method. Deterministic: retrying cannot change it. */
+ | "ATTESTATION_KEY_UNKNOWN" | "ATTESTATION_ISSUER_MISMATCH" | "ATTESTATION_MISMATCH"
+/** The reviewer's DID could not be RESOLVED (the source was unreachable) — transient, retryable. */
+ | "ATTESTATION_UNRESOLVABLE"
+/** A review arrived with no `attestation`. Every review is a signed statement (owner ruling),
+ *  so this is a malformed request, not a policy — there is no unsigned path to fall back to. */
+ | "ATTESTATION_REQUIRED"
+/** Absent, malformed, mis-signed, out of its window, over 30 days, or the wrong resource/capability. */
+ | "REVIEWER_GRANT_INVALID"
+/** Signed and well-formed, but its root is no current controller, it was revoked, or an oracle or
+ *  an evaluator is in it. */
+ | "REVIEWER_NOT_AUTHORIZED";
+export interface AppErrorOptions {
+    /** Machine-readable code returned to the client. */
+    code?: ErrorCode;
+    /** HTTP status. */
+    status?: ContentfulStatusCode;
+    /** Safe to return the message to the client? Defaults to true for <500. */
+    expose?: boolean;
+    /** Structured extra context (returned to client only when `expose`). */
+    details?: unknown;
+    /** Underlying error, preserved for logs. */
+    cause?: unknown;
+    /**
+     * An EXPECTED negative (e.g. the dashboard polling a claim the engine hasn't ingested yet):
+     * the response is unchanged, but the error handler logs at debug — silent in deployed envs
+     * (LOG_LEVEL info), still a breadcrumb in local dev. Routine states are not rejections.
+     */
+    expected?: boolean;
+}
+export declare class AppError extends Error {
+    readonly code: ErrorCode;
+    readonly status: ContentfulStatusCode;
+    readonly expose: boolean;
+    readonly expected: boolean;
+    readonly details?: unknown;
+    constructor(message: string, options?: AppErrorOptions);
+    static badRequest(message?: string, details?: unknown): AppError;
+    static unauthorized(message?: string): AppError;
+    static forbidden(message?: string): AppError;
+    static notFound(message?: string, options?: Pick<AppErrorOptions, "expected">): AppError;
+    static conflict(message?: string, details?: unknown): AppError;
+    /** The caller must pay (or pay more) before the request can be honored — a register-time gate. */
+    static paymentRequired(message?: string, details?: unknown): AppError;
+    static validation(message?: string, details?: unknown): AppError;
+    static rateLimited(message?: string): AppError;
+    static internal(message?: string, cause?: unknown): AppError;
+    static unavailable(message?: string, cause?: unknown): AppError;
+}
+/** Wire-format error body. Stable shape across every error response. */
+export interface ErrorBody {
+    error: {
+        code: ErrorCode;
+        message: string;
+        requestId: string;
+        details?: unknown;
+    };
+}
+/** The message of every request-schema refusal; `details.issues` names each field. */
+export declare const VALIDATION_FAILED = "Some fields in the request are missing or invalid \u2014 details.issues lists each one.";
+export declare function toErrorBody(err: AppError, requestId: string): ErrorBody;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEnE,MAAM,MAAM,SAAS,GACjB,aAAa,GACb,cAAc,GACd,WAAW,GACX,WAAW,GACX,UAAU,GACV,kBAAkB,GAClB,YAAY,GACZ,cAAc,GACd,UAAU,GACV,aAAa,GAGb,qBAAqB;AACvB;gEACgE;GAC9D,yBAAyB,GACzB,6BAA6B,GAC7B,sBAAsB;AACxB,oGAAoG;GAClG,0BAA0B;AAC5B;gGACgG;GAC9F,sBAAsB;AAExB,wGAAwG;GACtG,wBAAwB;AAC1B;6BAC6B;GAC3B,yBAAyB,CAAC;AAE9B,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,mBAAmB;IACnB,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAwBD,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAE3B,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,EAQzD;IAED,MAAM,CAAC,UAAU,CAAC,OAAO,SAAgB,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ,CAEtE;IAED,MAAM,CAAC,YAAY,CAAC,OAAO,SAAiB,GAAG,QAAQ,CAEtD;IAED,MAAM,CAAC,SAAS,CAAC,OAAO,SAAc,GAAG,QAAQ,CAEhD;IAED,MAAM,CAAC,QAAQ,CACb,OAAO,SAAc,EACrB,OAAO,GAAE,IAAI,CAAC,eAAe,EAAE,UAAU,CAAM,GAC9C,QAAQ,CAEV;IAED,MAAM,CAAC,QAAQ,CAAC,OAAO,SAAa,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ,CAEjE;IAED,kGAAkG;IAClG,MAAM,CAAC,eAAe,CAAC,OAAO,SAAqB,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ,CAEhF;IAED,MAAM,CAAC,UAAU,CAAC,OAAO,SAAsB,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ,CAE5E;IAED,MAAM,CAAC,WAAW,CAAC,OAAO,SAAsB,GAAG,QAAQ,CAE1D;IAED,MAAM,CAAC,QAAQ,CAAC,OAAO,SAA0B,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,CAE5E;IAED,MAAM,CAAC,WAAW,CAAC,OAAO,SAAwB,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,CAE7E;CACF;AAED,wEAAwE;AACxE,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE;QACL,IAAI,EAAE,SAAS,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;CACH;AAED,sFAAsF;AACtF,eAAO,MAAM,iBAAiB,4FACwD,CAAC;AASvF,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,CASvE"}

package/dist/lib/errors.js

@@ -0,0 +1,96 @@
+/**
+ * Typed application errors.
+ *
+ * Throw `AppError` (or one of its factories) anywhere in your logic. The global
+ * error handler maps it to a consistent JSON envelope, decides what is safe to
+ * expose to the client, and logs the rest. Unknown/unexpected throws are treated
+ * as 500s with their details hidden from clients.
+ */
+const DEFAULT_STATUS = {
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    CONFLICT: 409,
+    PAYMENT_REQUIRED: 402,
+    VALIDATION: 400,
+    RATE_LIMITED: 429,
+    INTERNAL: 500,
+    UNAVAILABLE: 503,
+    ATTESTATION_INVALID: 400,
+    ATTESTATION_KEY_UNKNOWN: 400,
+    ATTESTATION_ISSUER_MISMATCH: 403,
+    ATTESTATION_MISMATCH: 400,
+    // Transient: the reviewer's DID could not be resolved. Retryable, never a pass.
+    ATTESTATION_UNRESOLVABLE: 503,
+    ATTESTATION_REQUIRED: 400,
+    REVIEWER_GRANT_INVALID: 400,
+    REVIEWER_NOT_AUTHORIZED: 403,
+};
+export class AppError extends Error {
+    code;
+    status;
+    expose;
+    expected;
+    details;
+    constructor(message, options = {}) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "AppError";
+        this.code = options.code ?? "INTERNAL";
+        this.status = options.status ?? DEFAULT_STATUS[this.code];
+        this.expose = options.expose ?? this.status < 500;
+        this.expected = options.expected ?? false;
+        if (options.details !== undefined)
+            this.details = options.details;
+    }
+    static badRequest(message = "Bad request", details) {
+        return new AppError(message, { code: "BAD_REQUEST", details });
+    }
+    static unauthorized(message = "Unauthorized") {
+        return new AppError(message, { code: "UNAUTHORIZED" });
+    }
+    static forbidden(message = "Forbidden") {
+        return new AppError(message, { code: "FORBIDDEN" });
+    }
+    static notFound(message = "Not found", options = {}) {
+        return new AppError(message, { code: "NOT_FOUND", ...options });
+    }
+    static conflict(message = "Conflict", details) {
+        return new AppError(message, { code: "CONFLICT", details });
+    }
+    /** The caller must pay (or pay more) before the request can be honored — a register-time gate. */
+    static paymentRequired(message = "Payment required", details) {
+        return new AppError(message, { code: "PAYMENT_REQUIRED", details });
+    }
+    static validation(message = "Validation failed", details) {
+        return new AppError(message, { code: "VALIDATION", details });
+    }
+    static rateLimited(message = "Too many requests") {
+        return new AppError(message, { code: "RATE_LIMITED" });
+    }
+    static internal(message = "Internal server error", cause) {
+        return new AppError(message, { code: "INTERNAL", expose: false, cause });
+    }
+    static unavailable(message = "Service unavailable", cause) {
+        return new AppError(message, { code: "UNAVAILABLE", expose: false, cause });
+    }
+}
+/** The message of every request-schema refusal; `details.issues` names each field. */
+export const VALIDATION_FAILED = "Some fields in the request are missing or invalid — details.issues lists each one.";
+/** What a 5xx whose details are hidden says instead: a person can act on it, never a leak. */
+function hiddenMessage(status) {
+    return status === 503
+        ? "This service is temporarily unavailable. Nothing was lost — retry in a moment."
+        : "Something went wrong on our side. It has been logged; retry in a moment, and quote the requestId if it keeps happening.";
+}
+export function toErrorBody(err, requestId) {
+    return {
+        error: {
+            code: err.code,
+            message: err.expose ? err.message : hiddenMessage(err.status),
+            requestId,
+            ...(err.expose && err.details !== undefined ? { details: err.details } : {}),
+        },
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAsDH,MAAM,cAAc,GAA4C;IAC9D,WAAW,EAAE,GAAG;IAChB,YAAY,EAAE,GAAG;IACjB,SAAS,EAAE,GAAG;IACd,SAAS,EAAE,GAAG;IACd,QAAQ,EAAE,GAAG;IACb,gBAAgB,EAAE,GAAG;IACrB,UAAU,EAAE,GAAG;IACf,YAAY,EAAE,GAAG;IACjB,QAAQ,EAAE,GAAG;IACb,WAAW,EAAE,GAAG;IAChB,mBAAmB,EAAE,GAAG;IACxB,uBAAuB,EAAE,GAAG;IAC5B,2BAA2B,EAAE,GAAG;IAChC,oBAAoB,EAAE,GAAG;IACzB,gFAAgF;IAChF,wBAAwB,EAAE,GAAG;IAC7B,oBAAoB,EAAE,GAAG;IACzB,sBAAsB,EAAE,GAAG;IAC3B,uBAAuB,EAAE,GAAG;CAC7B,CAAC;AAEF,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAY;IAChB,MAAM,CAAuB;IAC7B,MAAM,CAAU;IAChB,QAAQ,CAAU;IAClB,OAAO,CAAW;IAE3B,YAAY,OAAe,EAAE,OAAO,GAAoB,EAAE;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,UAAU,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1D,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC;QAClD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,KAAK,CAAC;QAC1C,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACpE,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,OAAO,GAAG,aAAa,EAAE,OAAiB;QAC1D,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,CAAC,YAAY,CAAC,OAAO,GAAG,cAAc;QAC1C,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,MAAM,CAAC,SAAS,CAAC,OAAO,GAAG,WAAW;QACpC,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,CAAC,QAAQ,CACb,OAAO,GAAG,WAAW,EACrB,OAAO,GAAsC,EAAE;QAE/C,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAClE,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,OAAO,GAAG,UAAU,EAAE,OAAiB;QACrD,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,kGAAkG;IAClG,MAAM,CAAC,eAAe,CAAC,OAAO,GAAG,kBAAkB,EAAE,OAAiB;QACpE,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,OAAO,GAAG,mBAAmB,EAAE,OAAiB;QAChE,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,CAAC,WAAW,CAAC,OAAO,GAAG,mBAAmB;QAC9C,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,OAAO,GAAG,uBAAuB,EAAE,KAAe;QAChE,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,CAAC,WAAW,CAAC,OAAO,GAAG,qBAAqB,EAAE,KAAe;QACjE,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9E,CAAC;CACF;AAYD,sFAAsF;AACtF,MAAM,CAAC,MAAM,iBAAiB,GAC5B,oFAAoF,CAAC;AAEvF,8FAA8F;AAC9F,SAAS,aAAa,CAAC,MAAc;IACnC,OAAO,MAAM,KAAK,GAAG;QACnB,CAAC,CAAC,gFAAgF;QAClF,CAAC,CAAC,yHAAyH,CAAC;AAChI,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAa,EAAE,SAAiB;IAC1D,OAAO;QACL,KAAK,EAAE;YACL,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC;YAC7D,SAAS;YACT,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7E;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,88 @@
+/**
+ * The facts builder — this oracle's resolve + FREEZE phase (README "How a claim flows" step 4). The rubric is the
+ * WORK ORDER, and the work order is the engine's MANIFEST (expected.ts): it names the `ext.<name>`
+ * / `ai.<name>` facts a producer must return, and the `unique` / `frequency` facts when it declares
+ * those rules — the ONLY oracle-specific content of a FactSet — and this module assembles
+ * everything else (`answers` = the claim body verbatim, `ctx` = one clock read, the attachment
+ * descriptors, `settings`) around that answer, holds it to the work order (validate.ts), and
+ * freezes a strict FactSet v1. It never decides — `POST /v1/decisions` on the
+ * engine does — and it never reads a rubric: the engine's binder resolves `#rub`
+ * + `#vct` and republishes what the rules want, so a rubric it cannot bind is `unusable` HERE,
+ * before a single source is called, and the workflow pauses the collection so a broken catalog
+ * entry costs nothing per claim.
+ *
+ * Order: manifest (engine, KV-cached) → ctx → producer (the oracle config's `facts`, else
+ * stock/) → validate → attachment size probes → FREEZE. After `buildFacts` returns there is no
+ * network, no clock, and no AI anywhere downstream — that boundary is the determinism/replay
+ * guarantee (evaluator-spec §1).
+ *
+ * Fail closed: a deterministic negative (an unusable manifest, facts that don't match the work
+ * order) is a recorded outcome; a transient failure (the engine's 503, Blocksync, media) THROWS so
+ * the workflow step retries. Never half-built.
+ */
+import type { Database } from "../../db/client.js";
+import type { EngineClient } from "../engine/client.js";
+import { type Manifest, type ManifestUnusable } from "../engine/types.js";
+import type { PulledClaim } from "../ixo/index.js";
+import { FactSetV1 } from "./factset.js";
+import type { AiCall, ClaimScope, FactCache, FactsProducer, ProducerDeps } from "./producer.js";
+/** A build's deps: the producer's, minus `ctx` (resolved here), plus the engine (the manifest read) and the producer itself (absent ⇒ stock). */
+export interface BuildDeps extends Omit<ProducerDeps, "ctx" | "engine" | "factCache"> {
+    /** The engine client the step holds: the manifest is read here, the buyer statement by a producer. */
+    engine: Pick<EngineClient, "getManifest" | "getAgreement">;
+    /**
+     * The connector-result cache, opened per work order once the manifest names its `rubricId`
+     * (fact-cache.ts): a re-anchored rubric never reads the old one's answers.
+     */
+    factCache?: (rubricId: string) => FactCache;
+    produceFacts?: FactsProducer;
+}
+/**
+ * BuildDeps for a workflow step: the deps the pull lane already built, this claim's media auth, the
+ * engine client the step already holds, the step's D1 (the stock duplicate registries), the
+ * claim source's scope reads (window, frequency count), and the oracle's OWN policy + producer
+ * (`defineOracle`). Tests build BuildDeps by hand instead.
+ */
+export declare function factDeps(base: Pick<BuildDeps, "config" | "logger" | "trace" | "cache" | "metrics">, media: BuildDeps["media"], engine: BuildDeps["engine"], db: BuildDeps["db"], env: BuildDeps["env"], scope?: ClaimScope): BuildDeps;
+export interface BuildInput {
+    claim: PulledClaim;
+    /** `collection.protocol` on Blocksync — the manifest is keyed by it (the workflow resolves it). */
+    protocolDid: string;
+    /** Already read (the re-pin path, workflows/claim-ingest.ts) — skips the engine read. */
+    manifest?: Manifest | ManifestUnusable;
+}
+export type BuildResult = {
+    ok: true;
+    rubricId: string;
+    /** The wire facts — what `POST /v1/decisions` receives, verbatim. */
+    facts: FactSetV1;
+} | {
+    ok: false;
+    /**
+     * `rubric-unusable` — the engine cannot resolve or bind the protocol's rubric (no `#rub`,
+     *   swapped bytes, a drifted `#vct`, …): its `issues` verbatim; recorded, never retried.
+     * `invalid-facts` — the producer's answer doesn't match the work order (validate.ts): our or
+     *   the provider's bug, recorded AND surfaced loudly, never sent.
+     */
+    reason: "rubric-unusable" | "invalid-facts";
+    /** Known once the manifest resolved — what the outcome is recorded against. */
+    rubricId?: string;
+    /** Codes, paths and messages only — the engine's bind issues or validate.ts's fact issues. */
+    issues: {
+        code: string;
+        path: string;
+        message: string;
+    }[];
+};
+/**
+ * manifest → ctx → produce → validate → FREEZE, for one pulled claim. Transient failures (the
+ * engine, blocksync, media) throw `unavailable` for the workflow to retry; everything
+ * deterministic comes back as a result the caller records.
+ */
+export declare function buildFacts(deps: BuildDeps, input: BuildInput): Promise<BuildResult>;
+/**
+ * The build's AI Gateway calls → `ai_calls`, one batch. Fail-soft: the ledger is analytics, so
+ * a D1 blip here is a warning, never the reason a claim's evaluation retries.
+ */
+export declare function persistAiCalls(db: Database, claimId: string, calls: AiCall[], logger: ProducerDeps["logger"]): Promise<void>;
+//# sourceMappingURL=builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../../src/lib/facts/builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAGhD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAsB,KAAK,QAAQ,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE3F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAK1C,OAAO,EAAuB,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,KAAK,EACV,MAAM,EAEN,UAAU,EACV,SAAS,EACT,aAAa,EAEb,YAAY,EACb,MAAM,YAAY,CAAC;AAKpB,iJAAiJ;AACjJ,MAAM,WAAW,SAAU,SAAQ,IAAI,CAAC,YAAY,EAAE,KAAK,GAAG,QAAQ,GAAG,WAAW,CAAC;IACnF,sGAAsG;IACtG,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,aAAa,GAAG,cAAc,CAAC,CAAC;IAC3D;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,SAAS,CAAC;IAC5C,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC,EAC1E,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,EACzB,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC3B,EAAE,EAAE,SAAS,CAAC,IAAI,CAAC,EACnB,GAAG,EAAE,SAAS,CAAC,KAAK,CAAC,EACrB,KAAK,CAAC,EAAE,UAAU,GACjB,SAAS,CAqBX;AAoBD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,WAAW,CAAC;IACnB,mGAAmG;IACnG,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,QAAQ,CAAC,EAAE,QAAQ,GAAG,gBAAgB,CAAC;CACxC;AAED,MAAM,MAAM,WAAW,GACnB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,KAAK,EAAE,SAAS,CAAC;CAClB,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV;;;;;OAKG;IACH,MAAM,EAAE,iBAAiB,GAAG,eAAe,CAAC;IAC5C,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8FAA8F;IAC9F,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3D,CAAC;AAEN;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CA2HzF;AAID;;;GAGG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,QAAQ,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC,CAuBf"}

package/dist/lib/facts/builder.js

@@ -0,0 +1,239 @@
+/**
+ * The facts builder — this oracle's resolve + FREEZE phase (README "How a claim flows" step 4). The rubric is the
+ * WORK ORDER, and the work order is the engine's MANIFEST (expected.ts): it names the `ext.<name>`
+ * / `ai.<name>` facts a producer must return, and the `unique` / `frequency` facts when it declares
+ * those rules — the ONLY oracle-specific content of a FactSet — and this module assembles
+ * everything else (`answers` = the claim body verbatim, `ctx` = one clock read, the attachment
+ * descriptors, `settings`) around that answer, holds it to the work order (validate.ts), and
+ * freezes a strict FactSet v1. It never decides — `POST /v1/decisions` on the
+ * engine does — and it never reads a rubric: the engine's binder resolves `#rub`
+ * + `#vct` and republishes what the rules want, so a rubric it cannot bind is `unusable` HERE,
+ * before a single source is called, and the workflow pauses the collection so a broken catalog
+ * entry costs nothing per claim.
+ *
+ * Order: manifest (engine, KV-cached) → ctx → producer (the oracle config's `facts`, else
+ * stock/) → validate → attachment size probes → FREEZE. After `buildFacts` returns there is no
+ * network, no clock, and no AI anywhere downstream — that boundary is the determinism/replay
+ * guarantee (evaluator-spec §1).
+ *
+ * Fail closed: a deterministic negative (an unusable manifest, facts that don't match the work
+ * order) is a recorded outcome; a transient failure (the engine's 503, Blocksync, media) THROWS so
+ * the workflow step retries. Never half-built.
+ */
+import { aiCalls as aiCallsTable } from "../../db/schema.js";
+import { getOracle } from "../../oracle.js";
+import { isManifestUnusable } from "../engine/types.js";
+import { AppError } from "../errors.js";
+import { fetchAttachmentSize } from "../ixo/attachments.js";
+import { inSpan } from "../spans.js";
+import { resolveCtx } from "./ctx.js";
+import { dbFactCache } from "./fact-cache.js";
+import { FactSetV1 } from "./factset.js";
+import { stockProducer } from "./stock/index.js";
+import { rootQuestionName } from "./stock/send.js";
+import { validateFacts } from "./validate.js";
+/**
+ * BuildDeps for a workflow step: the deps the pull lane already built, this claim's media auth, the
+ * engine client the step already holds, the step's D1 (the stock duplicate registries), the
+ * claim source's scope reads (window, frequency count), and the oracle's OWN policy + producer
+ * (`defineOracle`). Tests build BuildDeps by hand instead.
+ */
+export function factDeps(base, media, engine, db, env, scope) {
+    const { allowAiChecks, allowImageChecks } = getOracle().config.policies;
+    return {
+        config: base.config,
+        logger: base.logger,
+        metrics: base.metrics,
+        span: inSpan,
+        trace: base.trace,
+        cache: base.cache,
+        media,
+        settings: { allowAiChecks, allowImageChecks },
+        produceFacts: getOracle().producer,
+        engine,
+        db,
+        // A provider's handler may reach for its own bindings (`tools.env`) — the step's env is the
+        // only place they exist.
+        env,
+        // The connector-result cache rides the same D1 — a crashed attempt's paid answers survive it.
+        factCache: db ? (rubricId) => dbFactCache(db, base.logger, rubricId) : undefined,
+        scope,
+    };
+}
+/**
+ * Root questions whose attachments need a byte size. The engine's `sizeProbes` (T10) names exactly
+ * the roots a `maxSizeMB` rule reads — BARE question names, what `attachments[].question` carries
+ * — so only those are probed. An older engine sends no `sizeProbes`: then every `file`-kind path
+ * the rubric reads at all is the bound (a size is probed wherever a rule could read it). An
+ * unprobeable size stays null either way, and the engine's null rule decides.
+ */
+function sizeProbeQuestions(manifest) {
+    if (manifest.sizeProbes)
+        return new Set(manifest.sizeProbes.map((p) => p.path));
+    const roots = new Set();
+    for (const field of manifest.fields) {
+        if (field.kind !== "file")
+            continue;
+        const root = rootQuestionName(field.path);
+        if (root)
+            roots.add(root);
+    }
+    return roots;
+}
+/**
+ * manifest → ctx → produce → validate → FREEZE, for one pulled claim. Transient failures (the
+ * engine, blocksync, media) throw `unavailable` for the workflow to retry; everything
+ * deterministic comes back as a result the caller records.
+ */
+export async function buildFacts(deps, input) {
+    const { claim, protocolDid } = input;
+    const ids = { claimId: claim.claimId, collectionId: claim.collectionId };
+    // The work order, before anything is spent: the engine's binder has already resolved `#rub`,
+    // `#vct` and every ref, so a rubric it cannot bind is the outcome — not a producer run and not
+    // a decide call. The engine's 503 throws `unavailable` out of the client for the step to retry.
+    const manifest = input.manifest ?? (await deps.engine.getManifest(protocolDid));
+    if (isManifestUnusable(manifest)) {
+        deps.logger.warn("facts.rubric-unusable", { ...ids, protocolDid, issues: manifest.issues });
+        return { ok: false, reason: "rubric-unusable", issues: manifest.issues };
+    }
+    // Canonical lowercase (`^[0-9a-f]{64}$` is what the engine's `rubric.id` accepts): the engine
+    // lowercases on parse already; asserted here so the pin we send is the pin we compare against.
+    const rubricId = manifest.rubricId.toLowerCase();
+    deps.logger.info("facts.expected", {
+        ...ids,
+        rubricId,
+        ext: Object.keys(manifest.ext),
+        ai: Object.keys(manifest.ai),
+        formDrifted: manifest.formProof.drifted,
+    });
+    // ctx FIRST — the build's one clock read (`frozenAt`) and the collection window, resolved before
+    // the producer so a transient Blocksync blip retries the step for free (no AI spent yet) and the
+    // producer's `send` payloads quote exactly the ctx the engine's rules will read (producer.ts).
+    const ctx = await resolveCtx(deps, {
+        collectionId: claim.collectionId,
+        submitter: claim.metadata.agentDid,
+        submitterAddress: claim.metadata.agentAddress,
+        submissionDate: claim.metadata.submissionDate,
+        useIntent: claim.metadata.payment.useIntent,
+    });
+    // PRODUCE — the provider's seam, else the stock producer (stock/). Whatever comes back is held
+    // to the work order before it is frozen: a mismatch is a producer bug, never a half-built FactSet
+    // and never something the engine is asked to judge.
+    const aiSpend = new Map();
+    const aiCalls = [];
+    const pdeps = {
+        config: deps.config,
+        logger: deps.logger,
+        metrics: deps.metrics,
+        span: deps.span,
+        protocolDid,
+        aiSpend,
+        aiCalls,
+        trace: deps.trace,
+        media: deps.media,
+        cache: deps.cache,
+        engine: deps.engine,
+        db: deps.db,
+        factCache: deps.factCache?.(rubricId),
+        env: deps.env,
+        scope: deps.scope,
+        settings: deps.settings,
+        finalAttempt: deps.finalAttempt,
+        ctx,
+    };
+    let produced;
+    try {
+        produced = await (deps.produceFacts ?? stockProducer)(claim, manifest, pdeps);
+    }
+    finally {
+        // Spent is spent — also when the producer then threw for a retry.
+        for (const [model, spent] of aiSpend) {
+            const tags = { op: model, id: protocolDid, outcome: deps.config.AI_PROVIDER };
+            deps.metrics?.count("ai.tokens", spent.promptTokens, { ...tags, route: "prompt" });
+            deps.metrics?.count("ai.tokens", spent.completionTokens, { ...tags, route: "completion" });
+            // The gateway's USD is not known yet — cron/ai-cost.ts emits it when the log has it.
+            if (spent.microUsd !== null)
+                deps.metrics?.count("ai.cost_micro_usd", spent.microUsd, tags);
+        }
+        // Spent is spent: the gateway calls land on the ledger even when the producer threw.
+        if (deps.db)
+            await persistAiCalls(deps.db, claim.claimId, aiCalls, deps.logger);
+    }
+    const valid = validateFacts(produced, manifest);
+    if (!valid.ok) {
+        deps.logger.error("facts.invalid", { ...ids, rubricId, issues: valid.issues });
+        return { ok: false, reason: "invalid-facts", rubricId, issues: valid.issues };
+    }
+    // Attachment facts: descriptors from the pull; sizes probed only where a `maxSizeMB` rule reads
+    // them. The probe runs with or without a media lane: a cellnode claim's https file answers are
+    // public URLs, and skipping them left every `maxSizeMB` gate on such a claim reading null.
+    const probes = sizeProbeQuestions(manifest);
+    const attachments = await Promise.all(claim.attachments.map(async (att) => {
+        let size = att.size ?? null;
+        if (size === null && probes.has(att.question)) {
+            size = await fetchAttachmentSize(deps, deps.media, att.url);
+        }
+        return {
+            question: att.question,
+            name: att.name,
+            mediaType: att.mediaType,
+            cid: att.cid ?? null,
+            size,
+        };
+    }));
+    // FREEZE — after this line, no network, no clock, no AI (§1). The strict parse is the wire
+    // contract asserted on OUR side: the ext/ai/unique/frequency lanes were validated above, so a
+    // failure here is the kit's own plumbing (ctx, attachments) and a loud bug, never a retry. The
+    // dup/rate facts ride only when produced — the key set IS the contract (an absent rule sends
+    // no key, never `undefined`).
+    let facts;
+    try {
+        facts = FactSetV1.parse({
+            version: 1,
+            frozenAt: ctx.now,
+            answers: claim.body,
+            attachments,
+            ctx,
+            ext: produced.ext,
+            ai: produced.ai,
+            ...(produced.unique !== undefined ? { unique: produced.unique } : {}),
+            ...(produced.frequency !== undefined ? { frequency: produced.frequency } : {}),
+            settings: deps.settings,
+        });
+    }
+    catch (err) {
+        throw AppError.internal("Built FactSet fails its own wire schema", err);
+    }
+    return { ok: true, rubricId, facts };
+}
+const AI_CALLS_PER_INSERT = 11;
+/**
+ * The build's AI Gateway calls → `ai_calls`, one batch. Fail-soft: the ledger is analytics, so
+ * a D1 blip here is a warning, never the reason a claim's evaluation retries.
+ */
+export async function persistAiCalls(db, claimId, calls, logger) {
+    if (calls.length === 0)
+        return;
+    try {
+        // D1 caps a statement at 100 bound parameters and a row binds 9 — chunks of 11, one batch.
+        const rows = calls.map((c) => ({ ...c, claimId }));
+        const statements = [];
+        for (let i = 0; i < rows.length; i += AI_CALLS_PER_INSERT) {
+            statements.push(db
+                .insert(aiCallsTable)
+                .values(rows.slice(i, i + AI_CALLS_PER_INSERT))
+                .onConflictDoNothing());
+        }
+        const [first, ...rest] = statements;
+        if (first)
+            await db.batch([first, ...rest]);
+    }
+    catch (err) {
+        logger.warn("ai.calls.persist-failed", {
+            claimId,
+            count: calls.length,
+            detail: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+//# sourceMappingURL=builder.js.map

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

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

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

@@ -0,0 +1,34 @@
+/**
+ * The kit's ctx — the "~free" facts (plan §9): ONE clock read, the collection window off Blocksync,
+ * and the claim's chain metadata. Assembled by the builder BEFORE the producer runs and handed to
+ * it read-only (producer.ts `deps.ctx`), so `frozenAt` is `ctx.now` and nothing downstream reads
+ * the clock again. Only `resolveCtx` touches the world; the pure ctx reader every send map goes
+ * through is `flattenCtx`, and it lives in stock/send.ts so the runner can stay node-safe.
+ */
+import { type BlocksyncDeps } from "../ixo/blocksync/index.js";
+import type { CtxFacts } from "./factset.js";
+import type { ClaimScope } from "./producer.js";
+/**
+ * A Blocksync timestamp → the engine's `z.iso.datetime()` form (Z-suffixed; an offset form is
+ * rejected there). Lossless for an instant. Unparseable is a deterministic fault, not a retry.
+ *
+ * Blocksync returns these WITHOUT a zone suffix (`…T16:23:35.727`) and means UTC — but
+ * bare `new Date(...)` parses a suffix-less datetime as LOCAL time, which would shift window/
+ * notInFuture gate boundaries off UTC depending on where the isolate runs (mirrors frequency.ts's
+ * `parseUtc` guard).
+ */
+export declare function isoDate(value: string | null): string | null;
+/**
+ * ctx resolver — one clock read + the collection window + claim metadata. The window is the claim
+ * source's (`scope`, Go Prod §7.1: null on the API lane), else the collection's on Blocksync.
+ */
+export declare function resolveCtx(deps: BlocksyncDeps & {
+    scope?: ClaimScope;
+}, claim: {
+    collectionId: string;
+    submitter: string | null;
+    submitterAddress: string | null;
+    submissionDate: string | null;
+    useIntent?: boolean;
+}): Promise<CtxFacts>;
+//# sourceMappingURL=ctx.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ctx.d.ts","sourceRoot":"","sources":["../../../src/lib/facts/ctx.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAO3D;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,aAAa,GAAG;IAAE,KAAK,CAAC,EAAE,UAAU,CAAA;CAAE,EAC5C,KAAK,EAAE;IACL,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GACA,OAAO,CAAC,QAAQ,CAAC,CAiBnB"}

package/dist/lib/facts/ctx.js

@@ -0,0 +1,51 @@
+/**
+ * The kit's ctx — the "~free" facts (plan §9): ONE clock read, the collection window off Blocksync,
+ * and the claim's chain metadata. Assembled by the builder BEFORE the producer runs and handed to
+ * it read-only (producer.ts `deps.ctx`), so `frozenAt` is `ctx.now` and nothing downstream reads
+ * the clock again. Only `resolveCtx` touches the world; the pure ctx reader every send map goes
+ * through is `flattenCtx`, and it lives in stock/send.ts so the runner can stay node-safe.
+ */
+import { AppError } from "../errors.js";
+import { getCollection } from "../ixo/blocksync/index.js";
+import { HAS_ZONE } from "./stock/frequency.js";
+/**
+ * A Blocksync timestamp → the engine's `z.iso.datetime()` form (Z-suffixed; an offset form is
+ * rejected there). Lossless for an instant. Unparseable is a deterministic fault, not a retry.
+ *
+ * Blocksync returns these WITHOUT a zone suffix (`…T16:23:35.727`) and means UTC — but
+ * bare `new Date(...)` parses a suffix-less datetime as LOCAL time, which would shift window/
+ * notInFuture gate boundaries off UTC depending on where the isolate runs (mirrors frequency.ts's
+ * `parseUtc` guard).
+ */
+export function isoDate(value) {
+    if (value === null)
+        return null;
+    const pinned = value.includes("T") && !HAS_ZONE.test(value) ? `${value}Z` : value;
+    const at = new Date(pinned);
+    if (Number.isNaN(at.getTime()))
+        throw AppError.internal(`Unparseable date from Blocksync: ${value}`);
+    return at.toISOString();
+}
+/**
+ * ctx resolver — one clock read + the collection window + claim metadata. The window is the claim
+ * source's (`scope`, Go Prod §7.1: null on the API lane), else the collection's on Blocksync.
+ */
+export async function resolveCtx(deps, claim) {
+    const window = deps.scope
+        ? await deps.scope.window(claim.collectionId)
+        : await getCollection(deps, claim.collectionId);
+    return {
+        now: new Date().toISOString(),
+        collection: {
+            startDate: isoDate(window?.startDate ?? null),
+            endDate: isoDate(window?.endDate ?? null),
+        },
+        claim: {
+            submitter: claim.submitter,
+            submitterAddress: claim.submitterAddress,
+            submissionDate: isoDate(claim.submissionDate),
+            useIntent: claim.useIntent === true,
+        },
+    };
+}
+//# sourceMappingURL=ctx.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ctx.js","sourceRoot":"","sources":["../../../src/lib/facts/ctx.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAsB,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGrE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C;;;;;;;;GAQG;AACH,MAAM,UAAU,OAAO,CAAC,KAAoB;IAC1C,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;IAClF,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC;QAC5B,MAAM,QAAQ,CAAC,QAAQ,CAAC,oCAAoC,KAAK,EAAE,CAAC,CAAC;IACvE,OAAO,EAAE,CAAC,WAAW,EAAE,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAA4C,EAC5C,KAMC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK;QACvB,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC;QAC7C,CAAC,CAAC,MAAM,aAAa,CAAC,IAAI,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;IAClD,OAAO;QACL,GAAG,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC7B,UAAU,EAAE;YACV,SAAS,EAAE,OAAO,CAAC,MAAM,EAAE,SAAS,IAAI,IAAI,CAAC;YAC7C,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,IAAI,IAAI,CAAC;SAC1C;QACD,KAAK,EAAE;YACL,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;YACxC,cAAc,EAAE,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC;YAC7C,SAAS,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI;SACpC;KACF,CAAC;AACJ,CAAC"}