@ixo/decision-oracle 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,56 @@
+/**
+ * C2PA "Content Credentials" provenance — reading an image's cryptographic birth certificate.
+ *
+ * When Google / OpenAI (and others) generate an image they embed a signed C2PA manifest declaring
+ * the origin. This module reads that manifest and verifies its cert chain against the official
+ * C2PA Trust List. A verified manifest that declares AI generation is PROOF — unlike the LLM visual
+ * heuristic (§A.15), which only guesses. So C2PA runs FIRST: a trusted AI manifest fails the check
+ * outright (no model call); anything else (no manifest — the common case, since a screenshot or
+ * re-encode strips it — an untrusted signer, or a real camera signer) is inconclusive and falls
+ * back to the LLM.
+ *
+ * ASYMMETRY (design around it): a positive is strong proof; a negative proves NOTHING. A screenshot
+ * of a Gemini image and a real photo both return `null` here. C2PA can confirm AI origin; it can
+ * never rule it out.
+ *
+ * Fail-SAFE by construction: any error (WASM init, unreadable bytes, malformed manifest) returns
+ * `null` = inconclusive → the LLM decides. Only a positively verified AI manifest ever flips a
+ * verdict, so a trust glitch can never falsely reject real work. Trust itself never goes dark: a
+ * known-good copy of the list is BUNDLED (`c2pa-trust-list.ts`), so verification works even with
+ * the network down — CACHE_KV / a live fetch only ever supplies a FRESHER list.
+ *
+ * Runs on WASM (c2pa-rs compiled) — the only way to read C2PA in a Worker isolate. The 6 MB module
+ * is instantiated LAZILY once per isolate (never at import time), so the evaluator's tests and the
+ * hot path for non-image checks never touch it.
+ */
+import type { ManifestStore } from "@contentauth/toolkit";
+import type { Logger } from "../../logger.js";
+import type { TraceContext } from "../../tracing.js";
+import type { Provenance } from "../factset.js";
+export type { Provenance } from "../factset.js";
+export type Vendor = Provenance["vendor"];
+export interface C2paDeps {
+    logger: Logger;
+    trace: TraceContext;
+    /** Reused CACHE_KV — a fresher trust list lives here so we don't re-fetch it per image (weekly). */
+    cache?: KVNamespace;
+}
+/** Bytes, an ArrayBuffer, a bare base64 string, or a `data:<mime>;base64,...` URL. */
+export type ImageInput = Uint8Array | ArrayBuffer | string;
+/**
+ * Fold a manifest store into a `Provenance`. Pure — no WASM, no I/O — so the three traps are tested
+ * against hand-built stores: (1) walk EVERY manifest, since Google puts `c2pa.created` in the PARENT
+ * not the active one; (2) read `validation_results` (this toolkit has no `validation_state`); (3)
+ * gate `trusted` on the POSITIVE `signingCredential.trusted` code — with no list loaded there are
+ * zero failure codes, so `failures.length === 0` would trust everything.
+ */
+export declare function extractProvenance(store: ManifestStore): Provenance;
+/**
+ * Read + verify the provenance of one image (bytes, base64, or a data URL). `null` = INCONCLUSIVE
+ * (no manifest, unreadable, or WASM unavailable) — NEVER "not AI". A non-null result carries
+ * `trusted`, the only field that turns "claims to be OpenAI" into proof.
+ */
+export declare function readImageProvenance(deps: C2paDeps, input: ImageInput, mimeType?: string): Promise<Provenance | null>;
+/** The gate: a cryptographically PROVEN AI-generated image (any trusted signer, vendor recorded). */
+export declare function isProvenAiGenerated(p: Provenance): boolean;
+//# sourceMappingURL=c2pa.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"c2pa.d.ts","sourceRoot":"","sources":["../../../../src/lib/facts/stock/c2pa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAK7C,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;AAE1C,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,YAAY,CAAC;IACpB,oGAAoG;IACpG,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,sFAAsF;AACtF,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,MAAM,CAAC;AAkK3D;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,UAAU,CAmClE;AAID;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAgB5B;AAED,qGAAqG;AACrG,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,UAAU,GAAG,OAAO,CAE1D"}

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

@@ -0,0 +1,234 @@
+/**
+ * C2PA "Content Credentials" provenance — reading an image's cryptographic birth certificate.
+ *
+ * When Google / OpenAI (and others) generate an image they embed a signed C2PA manifest declaring
+ * the origin. This module reads that manifest and verifies its cert chain against the official
+ * C2PA Trust List. A verified manifest that declares AI generation is PROOF — unlike the LLM visual
+ * heuristic (§A.15), which only guesses. So C2PA runs FIRST: a trusted AI manifest fails the check
+ * outright (no model call); anything else (no manifest — the common case, since a screenshot or
+ * re-encode strips it — an untrusted signer, or a real camera signer) is inconclusive and falls
+ * back to the LLM.
+ *
+ * ASYMMETRY (design around it): a positive is strong proof; a negative proves NOTHING. A screenshot
+ * of a Gemini image and a real photo both return `null` here. C2PA can confirm AI origin; it can
+ * never rule it out.
+ *
+ * Fail-SAFE by construction: any error (WASM init, unreadable bytes, malformed manifest) returns
+ * `null` = inconclusive → the LLM decides. Only a positively verified AI manifest ever flips a
+ * verdict, so a trust glitch can never falsely reject real work. Trust itself never goes dark: a
+ * known-good copy of the list is BUNDLED (`c2pa-trust-list.ts`), so verification works even with
+ * the network down — CACHE_KV / a live fetch only ever supplies a FRESHER list.
+ *
+ * Runs on WASM (c2pa-rs compiled) — the only way to read C2PA in a Worker isolate. The 6 MB module
+ * is instantiated LAZILY once per isolate (never at import time), so the evaluator's tests and the
+ * hot path for non-image checks never touch it.
+ */
+import wasmModule from "../../../c2pa.wasm";
+import { fetchClient } from "../../http/client.js";
+import { readCache } from "../../metrics.js";
+import { C2PA_TRUST_LIST_PEM } from "./c2pa-trust-list.js";
+const AI_SOURCE_TYPE = "http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia";
+// The OFFICIAL C2PA Trust List (launched 2025) — NOT the frozen legacy anchors.pem at
+// contentcredentials.org, which predates the 2025 CAs that sign OpenAI/Google images.
+const TRUST_LIST_URL = "https://raw.githubusercontent.com/c2pa-org/conformance-public/main/trust-list/C2PA-TRUST-LIST.pem";
+const TRUST_KV_KEY = "c2pa:trust-list-pem";
+const TRUST_TTL_SEC = 604800; // weekly — CAs are added/rotated; a fresher list trusts more images
+// --- lazy WASM + toolkit (never runs at import time) ---------------------------------------------
+let toolkitOnce;
+function toolkit(logger) {
+    if (toolkitOnce === undefined) {
+        toolkitOnce = (async () => {
+            try {
+                const tk = await import("@contentauth/toolkit");
+                tk.initSync({ module: wasmModule }); // ~35ms, once per isolate, no I/O
+                return { read: tk.getManifestStoreFromArrayBuffer };
+            }
+            catch (err) {
+                logger.warn("c2pa.wasm-init-failed", { error: String(err) });
+                return null;
+            }
+        })();
+    }
+    return toolkitOnce;
+}
+// --- trust list: bundled fallback, refreshed via CACHE_KV / live fetch (weekly) ------------------
+let settingsMemo;
+/** c2pa-rs settings — snake_case (NOT the node SDK's camelCase). `verify_trust` needs real anchors. */
+function buildSettings(anchorsPem) {
+    return JSON.stringify({
+        trust: { verify_trust_list: true, trust_anchors: anchorsPem },
+        verify: {
+            verify_trust: true,
+            verify_after_reading: true,
+            ocsp_fetch: false, // a subrequest per read; the trust list is the real defense
+        },
+    });
+}
+const isPem = (s) => !!s && s.includes("BEGIN CERTIFICATE");
+/** Resolve the anchor PEM: CACHE_KV → live fetch (cached) → bundled snapshot. Never fails. */
+async function anchorsPem(deps) {
+    const { cache } = deps;
+    if (cache) {
+        const cached = await readCache("c2pa-trust", () => cache.get(TRUST_KV_KEY));
+        if (isPem(cached))
+            return cached;
+    }
+    try {
+        const res = await fetchClient(TRUST_LIST_URL, { trace: deps.trace, attempts: 2 });
+        // Discarded bodies pin one of the isolate's 6 open connections until GC.
+        if (!res.ok)
+            await res.body?.cancel().catch(() => { });
+        const text = res.ok ? await res.text() : null;
+        if (isPem(text)) {
+            await deps.cache?.put(TRUST_KV_KEY, text, { expirationTtl: TRUST_TTL_SEC }).catch(() => { });
+            return text;
+        }
+        deps.logger.warn("c2pa.trust-fetch-bad", { status: res.status });
+    }
+    catch (err) {
+        deps.logger.warn("c2pa.trust-fetch-failed", { error: String(err) });
+    }
+    return C2PA_TRUST_LIST_PEM; // bundled — do not cache, so the next isolate retries the fetch
+}
+async function trustSettings(deps) {
+    if (settingsMemo)
+        return settingsMemo; // warm isolate
+    settingsMemo = buildSettings(await anchorsPem(deps));
+    return settingsMemo;
+}
+// --- input normalization -------------------------------------------------------------------------
+function base64ToBytes(b64) {
+    const bin = atob(b64.replace(/\s/g, ""));
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/** Magic-byte sniff — the toolkit needs the right mime; a wrong one just yields `null` (safe). */
+function sniffMime(b) {
+    if (b.length >= 4 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47)
+        return "image/png";
+    if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff)
+        return "image/jpeg";
+    if (b.length >= 12 &&
+        b[0] === 0x52 &&
+        b[1] === 0x49 &&
+        b[2] === 0x46 &&
+        b[3] === 0x46 && // "RIFF"
+        b[8] === 0x57 &&
+        b[9] === 0x45 &&
+        b[10] === 0x42 &&
+        b[11] === 0x50 // "WEBP"
+    )
+        return "image/webp";
+    return undefined;
+}
+/** bytes/base64/data-URL → the exact ArrayBuffer + mime the toolkit wants. */
+function normalize(input, mimeType) {
+    let bytes;
+    let mime = mimeType;
+    if (typeof input === "string") {
+        const dataUrl = /^data:([^;,]+)?;base64,(.*)$/s.exec(input);
+        if (dataUrl) {
+            mime ??= dataUrl[1] || undefined;
+            bytes = base64ToBytes(dataUrl[2] ?? "");
+        }
+        else {
+            bytes = base64ToBytes(input);
+        }
+    }
+    else if (input instanceof ArrayBuffer) {
+        bytes = new Uint8Array(input);
+    }
+    else {
+        bytes = input;
+    }
+    // A Uint8Array view may span a larger buffer — hand the toolkit an exact copy.
+    const buf = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    return { buf, mimeType: mime ?? sniffMime(bytes) ?? "application/octet-stream" };
+}
+function classify(issuer) {
+    const s = (issuer ?? "").toLowerCase();
+    if (s.includes("google"))
+        return "google";
+    if (s.includes("openai"))
+        return "openai";
+    return issuer ? "other" : "unknown";
+}
+function actionsOf(m) {
+    return (m.assertions ?? [])
+        .filter((a) => a.label.startsWith("c2pa.actions"))
+        .flatMap((a) => a.data?.actions ?? []);
+}
+/**
+ * Fold a manifest store into a `Provenance`. Pure — no WASM, no I/O — so the three traps are tested
+ * against hand-built stores: (1) walk EVERY manifest, since Google puts `c2pa.created` in the PARENT
+ * not the active one; (2) read `validation_results` (this toolkit has no `validation_state`); (3)
+ * gate `trusted` on the POSITIVE `signingCredential.trusted` code — with no list loaded there are
+ * zero failure codes, so `failures.length === 0` would trust everything.
+ */
+export function extractProvenance(store) {
+    let creatorIssuer;
+    let creatorAgent;
+    let aiGenerated = false;
+    let watermarked = false;
+    for (const m of Object.values(store.manifests ?? {})) {
+        for (const act of actionsOf(m)) {
+            if (act.digitalSourceType === AI_SOURCE_TYPE)
+                aiGenerated = true;
+            if (act.action.startsWith("c2pa.watermarked"))
+                watermarked = true;
+            if (/watermark/i.test(act.description ?? ""))
+                watermarked = true;
+            if (act.action === "c2pa.created") {
+                creatorIssuer = m.signature_info?.issuer;
+                creatorAgent = act.softwareAgent;
+            }
+        }
+    }
+    const active = store.active_manifest
+        ? store.manifests?.[store.active_manifest]
+        : undefined;
+    const issuer = creatorIssuer ?? active?.signature_info?.issuer;
+    const codes = store.validation_results?.activeManifest;
+    return {
+        vendor: classify(issuer),
+        issuer,
+        model: typeof creatorAgent === "object" ? creatorAgent.name : creatorAgent,
+        modelVersion: typeof creatorAgent === "object" ? creatorAgent.version : undefined,
+        aiGenerated,
+        watermarked,
+        signedAt: active?.signature_info?.time,
+        trusted: (codes?.success ?? []).some((s) => s.code === "signingCredential.trusted"),
+        failures: (codes?.failure ?? []).map((f) => f.code),
+    };
+}
+// --- public entry --------------------------------------------------------------------------------
+/**
+ * Read + verify the provenance of one image (bytes, base64, or a data URL). `null` = INCONCLUSIVE
+ * (no manifest, unreadable, or WASM unavailable) — NEVER "not AI". A non-null result carries
+ * `trusted`, the only field that turns "claims to be OpenAI" into proof.
+ */
+export async function readImageProvenance(deps, input, mimeType) {
+    const tk = await toolkit(deps.logger);
+    if (!tk)
+        return null;
+    const { buf, mimeType: mime } = normalize(input, mimeType);
+    const settings = await trustSettings(deps);
+    let store;
+    try {
+        const report = await tk.read(buf, mime, settings);
+        store = report.manifest_store;
+    }
+    catch {
+        return null; // no manifest — inconclusive, not proof it isn't AI
+    }
+    if (!store?.manifests)
+        return null;
+    return extractProvenance(store);
+}
+/** The gate: a cryptographically PROVEN AI-generated image (any trusted signer, vendor recorded). */
+export function isProvenAiGenerated(p) {
+    return p.aiGenerated && p.trusted;
+}
+//# sourceMappingURL=c2pa.js.map

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

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

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

@@ -0,0 +1,91 @@
+/**
+ * One retried, transcripted call — the core the stock connectors (ext-source.ts, ai-check.ts) and
+ * `tools.http.json` (a provider's handler) all share. The retry budget is §A.14.4 /
+ * evaluator-spec §6: 3 attempts, exponential backoff, ~30s total cap, a per-attempt timeout chosen
+ * by the caller.
+ *
+ * ONE attempt loop, two façades: `withRetryBudget` does the fetching, the JSON read and the
+ * transcript, and a per-attempt CLASSIFIER decides what an answer means — "done, here is the value"
+ * or "retry, here is why". `callWithRetryBudget` classifies against a source/model contract (a
+ * contract miss is the unreachable path, never a verdict); `jsonRequest` classifies on the HTTP
+ * status alone and hands the outcome back for the handler to interpret. Keeping the loop single is
+ * the point: retry semantics, the ~30s cap and the frozen transcript must not drift between the
+ * lane the kit runs and the lane a provider's handler runs.
+ */
+import { type Transport } from "../../http/client.js";
+import type { Transcript } from "../factset.js";
+import type { ProducerDeps } from "../producer.js";
+export declare const redactHeaders: (headers: Record<string, string>) => Record<string, string>;
+export declare function redactUrl(url: string): string;
+/**
+ * The most of a response body the TRANSCRIPT keeps. The caller still gets the whole parsed body (up
+ * to `MAX_RESPONSE_BYTES`); the transcript freezes into the FactSet and lands in `decisions.facts`,
+ * where a multi-MiB answer breaks D1's row limit AFTER the engine has decided and billed — and the
+ * recovery path rebuilds the same facts and fails the same way. Past the cap the transcript records
+ * the body's size and digest instead: a pure function of the bytes, so a review fold's re-pull
+ * freezes the same thing (the engine's `response.body` is `unknown` — any JSON is valid there).
+ */
+export declare const MAX_TRANSCRIPT_BODY_BYTES: number;
+/** The stand-in `transcriptBody` freezes past the cap. */
+export declare const isTruncated: (body: unknown) => body is {
+    truncated: true;
+    bytes: number;
+};
+/** A transcript's `response.body`: `readable` itself, or past the cap the bytes' size + digest. */
+export declare function transcriptBody(bytes: Uint8Array, readable: unknown): Promise<unknown>;
+/** The answers that mean "later", not "no": a 5xx, a 408 (timeout) or a 429 (rate limited). */
+export declare const isTransientStatus: (status: number) => boolean;
+/**
+ * A 4xx the endpoint will answer again: anything but 408 (a timeout, retried like one) and 429
+ * (rate limited, the one 4xx that means "later"). 5xx stays the transient path.
+ */
+export declare const isFinalStatus: (status: number) => boolean;
+export interface CallOutcome<T> {
+    ok: boolean;
+    value: T | null;
+    detail: string;
+    /** The failure was transient (see `RetriedResult.transient`): the caller throws, never freezes. */
+    transient: boolean;
+    retryAfterMs: number | null;
+    /** The last attempt's parsed body — whole, where the transcript may hold only its digest. */
+    body: unknown;
+    transcript: Transcript;
+}
+/**
+ * The connectors' façade: a POST under the budget, read against a strict contract. A non-2xx, an
+ * unparseable body and a contract MISS are all the unreachable path (§A.14.4: a contract miss is
+ * NEVER a `valid:false`). `transcriptBody` substitutes the recorded request body when the real one
+ * must not be persisted verbatim (base64 image payloads → CID + digest).
+ */
+export declare function callWithRetryBudget<T>(deps: Pick<ProducerDeps, "trace">, url: string, body: unknown, headers: Record<string, string>, timeoutMs: number, read: (parsed: Record<string, unknown>) => {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    detail: string;
+    final?: boolean;
+}, transcriptBody?: unknown, send?: Transport): Promise<CallOutcome<T>>;
+/**
+ * The handler's façade: the same call with NO contract reader — what `tools.http.json` gives a
+ * provider's handler (facts/types.ts `HttpJsonResult`). The difference is only what an answer
+ * MEANS: here every HTTP outcome, 404 and 500 included, comes back as `{ ok, status, body }`
+ * instead of becoming an error fact, because only the handler knows whether a 404 is a failure or
+ * a "no such batch, so false". A 5xx, a 408 or a 429 burns an attempt and retries; any other 4xx
+ * ends the loop on the spot — the same request gets the same answer (a handler that wants one shot
+ * even on a 5xx passes `attempts: 1`). Nothing here throws for an HTTP outcome — a network error on every attempt is
+ * `status: null`, the "no response at all" case.
+ */
+export declare function jsonRequest(deps: Pick<ProducerDeps, "trace">, req: {
+    url: string;
+    method: "GET" | "POST";
+    headers: Record<string, string>;
+    body?: unknown;
+    timeoutMs: number;
+    attempts: number;
+}): Promise<{
+    ok: boolean;
+    status: number | null;
+    body: unknown;
+    transcript: Transcript;
+}>;
+//# sourceMappingURL=call.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"call.d.ts","sourceRoot":"","sources":["../../../../src/lib/facts/stock/call.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAML,KAAK,SAAS,EACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA+BhD,eAAO,MAAM,aAAa,YAAa,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CACJ,CAAC;AASlF,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAoB7C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,QAAY,CAAC;AAEnD,0DAA0D;AAC1D,eAAO,MAAM,WAAW,SAAU,OAAO,KAAG,IAAI,IAAI;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CACe,CAAC;AAEpG,mGAAmG;AACnG,wBAAsB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAI3F;AAoBD,+FAA+F;AAC/F,eAAO,MAAM,iBAAiB,WAAY,MAAM,KAAG,OACA,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,aAAa,WAAY,MAAM,KAAG,OACoB,CAAC;AAiLpE,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,mGAAmG;IACnG,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,6FAA6F;IAC7F,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,UAAU,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,CACJ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,EAC5E,cAAc,CAAC,EAAE,OAAO,EACxB,IAAI,CAAC,EAAE,SAAS,GACf,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAuCzB;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,EACjC,GAAG,EAAE;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB,GACA,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,CAAC,CAcxF"}