@shield-agent/kya 0.22.0 → 0.23.0

package/dist/otel/exporter.js

@@ -0,0 +1,243 @@
+/**
+ * Best-effort OTLP/HTTP export of KYA verdicts as GenAI spans. Opt-in:
+ * disabled unless an endpoint is configured (env KYA_OTLP_EXPORT_ENDPOINT or
+ * "otlpExport" in .kya/config.json). Fire-and-forget: export NEVER blocks,
+ * delays, or changes a verdict. Every failure is swallowed and counted
+ * in-memory for a future status surface.
+ *
+ * Privacy: only verdict metadata ships (tool id, verdict, reason code, mode,
+ * host, session id, token counts when known). Tool args, prompts, approval
+ * bodies, and API keys are never exported - same rule as docs/otlp.md.
+ *
+ * No new dependencies: one hand-built OTLP/JSON payload and the global fetch.
+ */
+import { randomBytes } from "node:crypto";
+import { CLI_VERSION } from "../version.js";
+const EXPORT_TIMEOUT_MS = 2_000;
+const SERVICE_NAME = "shield-kya-cli";
+const SCOPE_NAME = "shield-kya-cli";
+const stats = { attempted: 0, exported: 0, failed: 0 };
+/** In-memory counters for a future status command; process-local only. */
+export function otlpExportStats() {
+    return { ...stats };
+}
+/**
+ * Resolve export config from env > parsed .kya/config.json. Accepts the parsed
+ * config object so callers that already read the file (resolveConfig) need no
+ * config.ts change. Returns undefined when disabled (no endpoint anywhere).
+ */
+export function resolveOtlpExportConfig(env = process.env, configJson) {
+    const file = readFileKey(configJson);
+    const endpoint = env.KYA_OTLP_EXPORT_ENDPOINT?.trim() || file?.endpoint;
+    if (!endpoint)
+        return undefined;
+    return {
+        endpoint,
+        ...(file?.headers ? { headers: file.headers } : {}),
+        insecure: file?.insecure === true,
+    };
+}
+function readFileKey(configJson) {
+    if (!configJson || typeof configJson !== "object" || Array.isArray(configJson)) {
+        return undefined;
+    }
+    const raw = configJson.otlpExport;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const key = raw;
+    const endpoint = typeof key.endpoint === "string" && key.endpoint.trim()
+        ? key.endpoint.trim()
+        : undefined;
+    if (!endpoint)
+        return undefined;
+    let headers;
+    if (key.headers && typeof key.headers === "object" && !Array.isArray(key.headers)) {
+        headers = {};
+        for (const [k, v] of Object.entries(key.headers)) {
+            if (typeof v === "string" && k.trim())
+                headers[k.trim()] = v;
+        }
+        if (Object.keys(headers).length === 0)
+            headers = undefined;
+    }
+    return {
+        endpoint,
+        ...(headers ? { headers } : {}),
+        insecure: key.insecure === true,
+    };
+}
+/** Loopback plaintext is fine; anything else over http requires insecure:true. */
+function endpointAllowed(cfg) {
+    let url;
+    try {
+        url = new URL(cfg.endpoint);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol === "https:")
+        return true;
+    if (url.protocol !== "http:")
+        return false;
+    if (cfg.insecure === true)
+        return true;
+    const host = url.hostname.toLowerCase();
+    return host === "127.0.0.1" || host === "::1" || host === "localhost";
+}
+function tracesUrl(cfg) {
+    const base = cfg.endpoint.replace(/\/+$/, "");
+    return base.endsWith("/v1/traces") ? base : `${base}/v1/traces`;
+}
+function hex(bytes) {
+    return randomBytes(bytes).toString("hex");
+}
+function nano(ts) {
+    const ms = ts ? Date.parse(ts) : Number.NaN;
+    const base = Number.isFinite(ms) ? ms : Date.now();
+    return (BigInt(Math.floor(base)) * 1000000n).toString();
+}
+function attr(key, value) {
+    return { key, value };
+}
+function strAttr(key, value) {
+    if (typeof value !== "string" || !value)
+        return undefined;
+    return attr(key, { stringValue: value });
+}
+function intAttr(key, value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+        return undefined;
+    return attr(key, { intValue: String(Math.floor(value)) });
+}
+/** One OTLP/JSON ExportTraceServiceRequest carrying exactly one verdict span. */
+export function buildVerdictTracePayload(event) {
+    const start = nano(event.ts);
+    const attributes = [
+        strAttr("gen_ai.tool.name", event.toolId),
+        strAttr("kya.verdict", event.verdict),
+        strAttr("kya.reason_code", event.reasonCode),
+        strAttr("kya.mode", event.mode),
+        strAttr("kya.host", event.host),
+        strAttr("kya.session_id", event.sessionId),
+        intAttr("gen_ai.usage.input_tokens", event.tokensIn),
+        intAttr("gen_ai.usage.output_tokens", event.tokensOut),
+    ].filter((a) => a !== undefined);
+    const denied = event.verdict === "DENY";
+    return {
+        resourceSpans: [
+            {
+                resource: {
+                    attributes: [
+                        attr("service.name", { stringValue: SERVICE_NAME }),
+                        attr("service.version", { stringValue: CLI_VERSION }),
+                    ],
+                },
+                scopeSpans: [
+                    {
+                        scope: { name: SCOPE_NAME, version: CLI_VERSION },
+                        spans: [
+                            {
+                                traceId: hex(16),
+                                spanId: hex(8),
+                                name: `kya.verdict ${event.toolId}`,
+                                // SPAN_KIND_INTERNAL: the verdict is a local policy decision.
+                                kind: 1,
+                                startTimeUnixNano: start,
+                                endTimeUnixNano: start,
+                                attributes,
+                                status: denied
+                                    ? { code: 2, message: event.reasonCode || "DENY" }
+                                    : { code: 1 },
+                            },
+                        ],
+                    },
+                ],
+            },
+        ],
+    };
+}
+/**
+ * Export one verdict span. Never throws, never blocks the caller beyond the
+ * 2s timeout budget, and never touches the verdict itself. No-op when the
+ * config is undefined (unconfigured) or the endpoint fails the scheme check.
+ */
+export async function exportVerdictSpan(event, config) {
+    if (!config || !endpointAllowed(config))
+        return;
+    stats.attempted += 1;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), EXPORT_TIMEOUT_MS);
+    try {
+        const res = await fetch(tracesUrl(config), {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                ...(config.headers ?? {}),
+            },
+            body: JSON.stringify(buildVerdictTracePayload(event)),
+            signal: controller.signal,
+        });
+        // Drain so the socket is released back to the pool.
+        await res.arrayBuffer().catch(() => new ArrayBuffer(0));
+        if (res.ok)
+            stats.exported += 1;
+        else
+            stats.failed += 1;
+    }
+    catch {
+        stats.failed += 1;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * CLI-invocable self-test: POST one synthetic span and report the outcome.
+ * Unlike exportVerdictSpan it reports failure detail instead of only counting
+ * it - still never throws.
+ */
+export async function otlpExportSelfTest(config) {
+    if (!config)
+        return { ok: false, detail: "otlpExport not configured (no endpoint)" };
+    if (!endpointAllowed(config)) {
+        return {
+            ok: false,
+            detail: `endpoint refused: non-https to a non-loopback host needs "insecure": true (${config.endpoint})`,
+        };
+    }
+    const event = {
+        ts: new Date().toISOString(),
+        sessionId: "otlp-selftest",
+        toolId: "kya__selftest",
+        verdict: "ALLOW",
+        reasonCode: "SELFTEST",
+        mode: "observe",
+        host: "ide",
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), EXPORT_TIMEOUT_MS);
+    try {
+        const res = await fetch(tracesUrl(config), {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                ...(config.headers ?? {}),
+            },
+            body: JSON.stringify(buildVerdictTracePayload(event)),
+            signal: controller.signal,
+        });
+        await res.arrayBuffer().catch(() => new ArrayBuffer(0));
+        if (res.ok) {
+            return { ok: true, detail: `span accepted (${res.status}) at ${tracesUrl(config)}` };
+        }
+        return { ok: false, detail: `endpoint returned HTTP ${res.status} at ${tracesUrl(config)}` };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, detail: `export failed: ${msg}` };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=exporter.js.map

package/dist/otel/exporter.js.map

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

package/dist/parse-args.d.ts

@@ -1,5 +1,5 @@
 /**
- * Minimal argv parser — no external CLI framework.
+ * Minimal argv parser - no external CLI framework.
  * Supports: flags (--foo), values (--foo bar | --foo=bar), boolean (--stdio), positionals.
  */
 export interface ParsedArgs {

package/dist/parse-args.js

@@ -1,5 +1,5 @@
 /**
- * Minimal argv parser — no external CLI framework.
+ * Minimal argv parser - no external CLI framework.
  * Supports: flags (--foo), values (--foo bar | --foo=bar), boolean (--stdio), positionals.
  */
 export function parseArgs(argv) {

package/dist/receipt/auto-open.d.ts

@@ -7,7 +7,7 @@ export interface AutoOpenResult {
 }
 /**
  * Write the latest receipt and optionally open it in the browser.
- * @param force — open even if already opened this cwd (use on DENY).
+ * @param force - open even if already opened this cwd (use on DENY).
  */
 export declare function autoOpenReceiptAfterWrap(config: ResolvedConfig, opts?: {
     force?: boolean;

package/dist/receipt/auto-open.js

@@ -42,7 +42,7 @@ function openBrowser(target) {
 }
 /**
  * Write the latest receipt and optionally open it in the browser.
- * @param force — open even if already opened this cwd (use on DENY).
+ * @param force - open even if already opened this cwd (use on DENY).
  */
 export async function autoOpenReceiptAfterWrap(config, opts = {}) {
     const env = opts.env ?? process.env;

package/dist/receipt/daemon.d.ts

@@ -18,7 +18,7 @@ export declare function writeDaemonState(cwd: string, state: ReceiptDaemonState)
 /**
  * Remove the state file. With expectedPid set (daemon shutdown), removal is
  * skipped when the file was already replaced by a newer daemon (pid mismatch)
- * — a dying daemon must not delete its successor's state. Read errors /
+ * - a dying daemon must not delete its successor's state. Read errors /
  * missing / corrupt state still remove (we own the normal case).
  */
 export declare function clearDaemonState(cwd: string, expectedPid?: number): void;
@@ -45,13 +45,13 @@ export interface DaemonProc {
  */
 export declare function listOwnedProcesses(platform?: NodeJS.Platform): DaemonProc[];
 /**
- * Pids of running `cli.js receipt-serve` daemons — any install path, any
- * cwd — so `stop --all` can sweep orphans the cwd state file does not know
+ * Pids of running `cli.js receipt-serve` daemons - any install path, any
+ * cwd - so `stop --all` can sweep orphans the cwd state file does not know
  * about. Never matches this process. `receipt-serve` must appear as a
  * standalone argv token (the daemon always spawns it as one), so an editor
  * with `receipt-serve-notes.txt` open does not match. Residual risk,
  * accepted: a same-uid process deliberately built to look like the daemon
- * (`node cli.js receipt-serve`) still matches — but the sweep is scoped to
+ * (`node cli.js receipt-serve`) still matches - but the sweep is scoped to
  * the current user's processes and only ever sends SIGTERM, so the worst
  * case is a graceful stop of a same-user lookalike.
  */
@@ -60,8 +60,8 @@ export declare function findReceiptDaemonPids(procs: readonly DaemonProc[]): num
  * Reuse the running daemon only when its pid is alive, the stored loopback
  * url answers the token handshake, AND the daemon reports this exact package
  * version. A daemon from an older (or newer, or pre-version-handshake) build
- * may serve a stale trail layout, so any mismatch — including an absent or
- * unreadable version field — stops it and spawns a fresh one. A wedged
+ * may serve a stale trail layout, so any mismatch - including an absent or
+ * unreadable version field - stops it and spawns a fresh one. A wedged
  * daemon that IS ours is stopped first so failed handshakes cannot leak
  * orphans; a foreign pid is never signaled.
  */

package/dist/receipt/daemon.js

@@ -1,7 +1,7 @@
 /**
  * Background live-receipt daemon: `kya start` spawns it detached and returns
  * to the terminal. State (pid, url, token) lives in `.kya/receipt-server.json`
- * (mode 0600 — it carries the loopback auth token); stdout/stderr go to
+ * (mode 0600 - it carries the loopback auth token); stdout/stderr go to
  * `.kya/receipt-server.log`. The daemon child is the hidden `receipt-serve`
  * command, which writes the state file once it is listening and removes it on
  * shutdown.
@@ -33,7 +33,7 @@ export function readDaemonState(cwd) {
         }
     }
     catch {
-        /* corrupt state — treat as absent */
+        /* corrupt state - treat as absent */
     }
     return undefined;
 }
@@ -58,13 +58,13 @@ function removeIfSymlink(path) {
             rmSync(path, { force: true });
     }
     catch {
-        /* absent — nothing to remove */
+        /* absent - nothing to remove */
     }
 }
 /**
  * Remove the state file. With expectedPid set (daemon shutdown), removal is
  * skipped when the file was already replaced by a newer daemon (pid mismatch)
- * — a dying daemon must not delete its successor's state. Read errors /
+ * - a dying daemon must not delete its successor's state. Read errors /
  * missing / corrupt state still remove (we own the normal case).
  */
 export function clearDaemonState(cwd, expectedPid) {
@@ -83,7 +83,7 @@ export function pidAlive(pid) {
         return true;
     }
     catch (err) {
-        // EPERM: process exists but owned by someone else — still alive.
+        // EPERM: process exists but owned by someone else - still alive.
         return err.code === "EPERM";
     }
 }
@@ -95,7 +95,7 @@ function cliJsPath() {
     const built = fileURLToPath(new URL("../cli.js", import.meta.url));
     if (existsSync(built))
         return built;
-    // Running from src/ (vitest) — spawn the built CLI.
+    // Running from src/ (vitest) - spawn the built CLI.
     return fileURLToPath(new URL("../../dist/cli.js", import.meta.url));
 }
 /**
@@ -148,13 +148,13 @@ export function listOwnedProcesses(platform = process.platform) {
     }
 }
 /**
- * Pids of running `cli.js receipt-serve` daemons — any install path, any
- * cwd — so `stop --all` can sweep orphans the cwd state file does not know
+ * Pids of running `cli.js receipt-serve` daemons - any install path, any
+ * cwd - so `stop --all` can sweep orphans the cwd state file does not know
  * about. Never matches this process. `receipt-serve` must appear as a
  * standalone argv token (the daemon always spawns it as one), so an editor
  * with `receipt-serve-notes.txt` open does not match. Residual risk,
  * accepted: a same-uid process deliberately built to look like the daemon
- * (`node cli.js receipt-serve`) still matches — but the sweep is scoped to
+ * (`node cli.js receipt-serve`) still matches - but the sweep is scoped to
  * the current user's processes and only ever sends SIGTERM, so the worst
  * case is a graceful stop of a same-user lookalike.
  */
@@ -171,7 +171,7 @@ export function findReceiptDaemonPids(procs) {
  * server behind it answers a token-authenticated handshake with 200.
  * Uses /healthz: O(1) and decoupled from render failures of the full page.
  * Every failure mode (non-200, unreadable body, missing field) yields a
- * probe without a version — callers must treat that as "unknown version",
+ * probe without a version - callers must treat that as "unknown version",
  * never as a match.
  */
 async function probeStoredDaemon(state) {
@@ -188,7 +188,7 @@ async function probeStoredDaemon(state) {
             res.body?.cancel().catch(() => undefined);
             return { ok: false };
         }
-        // Handshake passed; the version may still be unreadable — pre-0.4.1
+        // Handshake passed; the version may still be unreadable - pre-0.4.1
         // daemons answer plain "ok\n". A parse failure is an unknown version,
         // not a failed handshake.
         let version;
@@ -222,8 +222,8 @@ async function stopOwnedDaemon(pid) {
  * Reuse the running daemon only when its pid is alive, the stored loopback
  * url answers the token handshake, AND the daemon reports this exact package
  * version. A daemon from an older (or newer, or pre-version-handshake) build
- * may serve a stale trail layout, so any mismatch — including an absent or
- * unreadable version field — stops it and spawns a fresh one. A wedged
+ * may serve a stale trail layout, so any mismatch - including an absent or
+ * unreadable version field - stops it and spawns a fresh one. A wedged
  * daemon that IS ours is stopped first so failed handshakes cannot leak
  * orphans; a foreign pid is never signaled.
  */
@@ -235,7 +235,7 @@ export async function ensureReceiptDaemon(config, input) {
             return { url: existing.url, pid: existing.pid, reused: true };
         }
         if (probe.ok) {
-            // Answered our token handshake with a stale/absent version — it is
+            // Answered our token handshake with a stale/absent version - it is
             // authenticated as a kya daemon even if an older install spawned it
             // from a different cli.js path, so the args check would miss it.
             await stopOwnedDaemon(existing.pid);
@@ -274,6 +274,6 @@ export async function ensureReceiptDaemon(config, input) {
             break;
         await sleep(100);
     }
-    throw new KyaError(`receipt server failed to start — see ${daemonLogPath(config.cwd)}`, "RECEIPT_DAEMON_FAILED");
+    throw new KyaError(`receipt server failed to start - see ${daemonLogPath(config.cwd)}`, "RECEIPT_DAEMON_FAILED");
 }
 //# sourceMappingURL=daemon.js.map

package/dist/receipt/dashboard.d.ts

@@ -55,7 +55,7 @@ export interface BucketWindowInput {
 /**
  * Zero-filled bucket window: from the earliest event's bucket up to the
  * latest, capped to the most recent `cap` buckets, ascending chronologically.
- * Candidates are deduped by start ms — stepping back across a spring-forward
+ * Candidates are deduped by start ms - stepping back across a spring-forward
  * transition can map two steps to the same bucket start (duplicate column).
  * Pure and exported so tests can feed the duplicate-start case directly.
  */

package/dist/receipt/dashboard.js

@@ -25,7 +25,7 @@ const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "
 function hourLabel(startMs) {
     return `${String(new Date(startMs).getHours()).padStart(2, "0")}:00`;
 }
-/** "Sep 16 14:00" — used when an hourly window crosses midnight. */
+/** "Sep 16 14:00" - used when an hourly window crosses midnight. */
 function hourDayLabel(startMs) {
     const d = new Date(startMs);
     return `${MONTHS[d.getMonth()]} ${d.getDate()} ${hourLabel(startMs)}`;
@@ -48,7 +48,7 @@ function stepBack(startMs, i, granularity) {
 /**
  * Zero-filled bucket window: from the earliest event's bucket up to the
  * latest, capped to the most recent `cap` buckets, ascending chronologically.
- * Candidates are deduped by start ms — stepping back across a spring-forward
+ * Candidates are deduped by start ms - stepping back across a spring-forward
  * transition can map two steps to the same bucket start (duplicate column).
  * Pure and exported so tests can feed the duplicate-start case directly.
  */

package/dist/receipt/embeddings.d.ts

@@ -1,19 +1,30 @@
 import type { TrailEvent } from "../trail.js";
 export interface EmbeddingProvider {
     embed(text: string): Promise<number[] | undefined>;
+    /** Optional batch embed. Providers that implement this can warm the index
+     * orders of magnitude faster than one-by-one calls. */
+    embedBatch?(texts: string[]): Promise<(number[] | undefined)[] | undefined>;
 }
 /** Local MiniLM provider via fastembed; loaded on first use. */
 export declare class LocalMiniLmProvider implements EmbeddingProvider {
     private readonly env;
-    private model;
-    private tried;
+    private queryModel;
+    private batchModel;
+    private queryTried;
+    private batchTried;
+    /** fastembed model init is not re-entrant; serialize loadModel calls. */
+    private loadLock;
     constructor(env?: NodeJS.ProcessEnv);
+    private withLoadLock;
+    private loadModel;
     embed(text: string): Promise<number[] | undefined>;
+    embedBatch(texts: string[]): Promise<(number[] | undefined)[] | undefined>;
 }
 /** On-disk cache for event embeddings keyed by event id and document sha1. */
 export declare class EventEmbeddingCache {
     private data;
-    constructor();
+    private readonly cacheFile;
+    constructor(cacheFile?: string);
     private load;
     private save;
     getCached(eventId: string, textSha1: string): number[] | undefined;
@@ -28,7 +39,7 @@ export declare class EventEmbeddingCache {
 /**
  * Build a map of embeddings for the given events. Already-cached entries are
  * returned without calling the provider; missing entries are embedded and
- * written to the cache in a single batch.
+ * written to the cache in chunks so the index warms incrementally.
  */
 export declare function buildEventEmbeddings(events: readonly TrailEvent[], provider: EmbeddingProvider, cache: EventEmbeddingCache): Promise<Map<string, number[]>>;
 //# sourceMappingURL=embeddings.d.ts.map

package/dist/receipt/embeddings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../../src/receipt/embeddings.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;CACpD;AAyBD,gEAAgE;AAChE,qBAAa,mBAAoB,YAAW,iBAAiB;IAI/C,OAAO,CAAC,QAAQ,CAAC,GAAG;IAHhC,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,KAAK,CAAS;gBAEO,GAAG,GAAE,MAAM,CAAC,UAAwB;IAE3D,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC;CAiCzD;AAgBD,8EAA8E;AAC9E,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,IAAI,CAAY;;IAMxB,OAAO,CAAC,IAAI;IAWZ,OAAO,CAAC,IAAI;IASZ,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IAIlE,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IAIpE,2EAA2E;IAC3E,OAAO,CAAC,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,GAAG,IAAI;CAO3G;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAqBhC"}
+{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../../src/receipt/embeddings.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACnD;2DACuD;IACvD,UAAU,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC;CAC7E;AAsBD,gEAAgE;AAChE,qBAAa,mBAAoB,YAAW,iBAAiB;IAQ/C,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPhC,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAuC;gBAE1B,GAAG,GAAE,MAAM,CAAC,UAAwB;YAEnD,YAAY;YAMZ,SAAS;IA4BjB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC;IAmBlD,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,EAAE,GAAG,SAAS,CAAC;CA0BjF;AAgBD,8EAA8E;AAC9E,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,IAAI,CAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,SAAS,CAAC,EAAE,MAAM;IAK9B,OAAO,CAAC,IAAI;IAWZ,OAAO,CAAC,IAAI;IASZ,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IAIlE,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IAIpE,2EAA2E;IAC3E,OAAO,CAAC,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,GAAG,IAAI;CAO3G;AAID;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAgDhC"}