opensquid 0.5.395

package/dist/anti-drift/state.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Anti-drift state primitives (0.8 unified-evaluator track).
+ *
+ * Per loop/docs/opensquid-anti-drift-unified-evaluator-design.md C-section
+ * "state primitives": one filesystem-backed source of truth for the
+ * active-task signal + violations log + drift catalog.
+ *
+ * This module is the foundation of the unified evaluator. Today it
+ * lives alongside src/hooks/ (no cutover yet). Subsequent patches
+ * port rules from src/hooks/* into src/anti-drift/rules.ts which
+ * reads from this state module, replacing per-rule transcript
+ * parsing.
+ *
+ * Three state primitives:
+ *   1. active-task.json — current in_progress task id + subject + started_at
+ *   2. violations.log   — append-only ring buffer (last N violations)
+ *   3. drift-catalog.jsonl — append-only audit trail
+ *
+ * Layout (sessions are short-lived; project scope is durable):
+ *   ~/.opensquid/sessions/<session-id>/active-task.json
+ *   ~/.opensquid/sessions/<session-id>/violations.log
+ *   ~/.opensquid/projects/<project-uuid>/drift-catalog.jsonl
+ *
+ * Design choice: writes are best-effort. State corruption is recoverable
+ * (worst case: rule fails-open, which is what the existing hooks already
+ * do). The new architecture's win is making "no active task" a positive
+ * signal (file absent) rather than a parse failure (transcript
+ * unreadable) — different shape, easier to reason about.
+ */
+export interface ActiveTaskState {
+    /** Numeric task id from Claude Code's TodoWrite / TaskCreate. */
+    id: string;
+    /** Human-readable subject (helps with grep + debugging). */
+    subject?: string;
+    /** ISO 8601 timestamp when this task was marked in_progress. */
+    started_at: string;
+}
+/**
+ * Write the active-task state. Idempotent — overwrites any existing
+ * file. Caller is responsible for choosing the right semantic (e.g.
+ * a fresh TaskCreate vs. a TaskUpdate(in_progress) on an existing
+ * task id).
+ *
+ * Exported for direct testing + use by the PreToolUse sync helper.
+ */
+export declare function writeActiveTask(sessionId: string, state: ActiveTaskState, options?: {
+    dataRoot?: string;
+}): Promise<void>;
+/**
+ * Read the active-task state. Returns null when the file is absent
+ * (the canonical "no in_progress task" signal) OR when the file is
+ * malformed (fail-safe: treat corruption as "no task" rather than
+ * crashing the gate).
+ */
+export declare function readActiveTask(sessionId: string, options?: {
+    dataRoot?: string;
+}): Promise<ActiveTaskState | null>;
+/**
+ * Delete the active-task state. Idempotent — silent no-op when the
+ * file is already absent. Called on TaskUpdate(completed).
+ */
+export declare function clearActiveTask(sessionId: string, options?: {
+    dataRoot?: string;
+}): Promise<void>;
+export interface ViolationEntry {
+    /** ISO 8601 timestamp the rule fired. */
+    ts: string;
+    /** Rule id from rules.ts. */
+    rule_id: string;
+    /** "block" | "warn" | "surface" | "auto". */
+    verdict: string;
+    /** Free-text reason (becomes the agent-facing surface text). */
+    reason: string;
+    /** Optional matched-text snippet (≤200 chars). */
+    evidence?: string;
+}
+/**
+ * Append a violation entry. Each call writes exactly one JSON line.
+ * Best-effort: silent on write failure (the rule has already fired
+ * in-process — losing the log entry is non-load-bearing).
+ */
+export declare function appendViolation(sessionId: string, entry: ViolationEntry, options?: {
+    dataRoot?: string;
+}): Promise<void>;
+/**
+ * Atomically claim all pending violations for surfacing at next UPS.
+ * Returns the parsed entries; the on-disk file is renamed-then-deleted
+ * so concurrent writers land in a fresh file the next consumer picks up.
+ */
+export declare function consumeViolations(sessionId: string, options?: {
+    dataRoot?: string;
+}): Promise<ViolationEntry[]>;
+/**
+ * Path helper for the per-project drift catalog. The catalog is
+ * project-scoped (not session-scoped) so a project's drift history
+ * accumulates across sessions.
+ *
+ * Falls back to a session-scoped path when projectUuid is null —
+ * matches the existing drift-catalog.ts fallback shape.
+ */
+export declare function driftCatalogPath(projectUuid: string | null, sessionId: string, dataRoot?: string): string;
+/**
+ * Per-session file paths that SessionEnd should clean up. Project-scoped
+ * files (drift-catalog.jsonl) are durable across sessions and excluded.
+ */
+export declare function sessionStateFiles(sessionId: string, dataRoot?: string): string[];
+//# sourceMappingURL=state.d.ts.map

package/dist/anti-drift/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src.legacy/anti-drift/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAWH,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAiBjC;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,IAAI,CAAC,CAOf;AAMD,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,cAAc,EACrB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,cAAc,EAAE,CAAC,CA+B3B;AAMD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAMR;AAMD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAEhF"}

package/dist/anti-drift/state.js

@@ -0,0 +1,177 @@
+/**
+ * Anti-drift state primitives (0.8 unified-evaluator track).
+ *
+ * Per loop/docs/opensquid-anti-drift-unified-evaluator-design.md C-section
+ * "state primitives": one filesystem-backed source of truth for the
+ * active-task signal + violations log + drift catalog.
+ *
+ * This module is the foundation of the unified evaluator. Today it
+ * lives alongside src/hooks/ (no cutover yet). Subsequent patches
+ * port rules from src/hooks/* into src/anti-drift/rules.ts which
+ * reads from this state module, replacing per-rule transcript
+ * parsing.
+ *
+ * Three state primitives:
+ *   1. active-task.json — current in_progress task id + subject + started_at
+ *   2. violations.log   — append-only ring buffer (last N violations)
+ *   3. drift-catalog.jsonl — append-only audit trail
+ *
+ * Layout (sessions are short-lived; project scope is durable):
+ *   ~/.opensquid/sessions/<session-id>/active-task.json
+ *   ~/.opensquid/sessions/<session-id>/violations.log
+ *   ~/.opensquid/projects/<project-uuid>/drift-catalog.jsonl
+ *
+ * Design choice: writes are best-effort. State corruption is recoverable
+ * (worst case: rule fails-open, which is what the existing hooks already
+ * do). The new architecture's win is making "no active task" a positive
+ * signal (file absent) rather than a parse failure (transcript
+ * unreadable) — different shape, easier to reason about.
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { resolveDataRoot } from "../codex/store.js";
+function activeTaskPath(sessionId, dataRoot) {
+    return path.join(resolveDataRoot(dataRoot), "sessions", sessionId, "active-task.json");
+}
+/**
+ * Write the active-task state. Idempotent — overwrites any existing
+ * file. Caller is responsible for choosing the right semantic (e.g.
+ * a fresh TaskCreate vs. a TaskUpdate(in_progress) on an existing
+ * task id).
+ *
+ * Exported for direct testing + use by the PreToolUse sync helper.
+ */
+export async function writeActiveTask(sessionId, state, options = {}) {
+    const p = activeTaskPath(sessionId, options.dataRoot);
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    await fs.writeFile(p, JSON.stringify(state, null, 2) + "\n", "utf8");
+}
+/**
+ * Read the active-task state. Returns null when the file is absent
+ * (the canonical "no in_progress task" signal) OR when the file is
+ * malformed (fail-safe: treat corruption as "no task" rather than
+ * crashing the gate).
+ */
+export async function readActiveTask(sessionId, options = {}) {
+    const p = activeTaskPath(sessionId, options.dataRoot);
+    let raw;
+    try {
+        raw = await fs.readFile(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.id !== "string" || typeof parsed?.started_at !== "string") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Delete the active-task state. Idempotent — silent no-op when the
+ * file is already absent. Called on TaskUpdate(completed).
+ */
+export async function clearActiveTask(sessionId, options = {}) {
+    const p = activeTaskPath(sessionId, options.dataRoot);
+    try {
+        await fs.rm(p);
+    }
+    catch {
+        /* already gone — idempotent */
+    }
+}
+function violationsPath(sessionId, dataRoot) {
+    return path.join(resolveDataRoot(dataRoot), "sessions", sessionId, "violations.log");
+}
+/**
+ * Append a violation entry. Each call writes exactly one JSON line.
+ * Best-effort: silent on write failure (the rule has already fired
+ * in-process — losing the log entry is non-load-bearing).
+ */
+export async function appendViolation(sessionId, entry, options = {}) {
+    const p = violationsPath(sessionId, options.dataRoot);
+    try {
+        await fs.mkdir(path.dirname(p), { recursive: true });
+        await fs.appendFile(p, JSON.stringify(entry) + "\n", "utf8");
+    }
+    catch {
+        /* best-effort logging — swallow */
+    }
+}
+/**
+ * Atomically claim all pending violations for surfacing at next UPS.
+ * Returns the parsed entries; the on-disk file is renamed-then-deleted
+ * so concurrent writers land in a fresh file the next consumer picks up.
+ */
+export async function consumeViolations(sessionId, options = {}) {
+    const p = violationsPath(sessionId, options.dataRoot);
+    const claimed = `${p}.consuming.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+    try {
+        await fs.rename(p, claimed);
+    }
+    catch {
+        return [];
+    }
+    let raw;
+    try {
+        raw = await fs.readFile(claimed, "utf8");
+    }
+    catch {
+        raw = "";
+    }
+    try {
+        await fs.rm(claimed);
+    }
+    catch {
+        /* already gone */
+    }
+    if (!raw.trim())
+        return [];
+    const entries = [];
+    for (const line of raw.split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        try {
+            entries.push(JSON.parse(t));
+        }
+        catch {
+            /* skip malformed line */
+        }
+    }
+    return entries;
+}
+// =====================================================================
+// drift-catalog.jsonl — project-scoped audit trail
+// =====================================================================
+/**
+ * Path helper for the per-project drift catalog. The catalog is
+ * project-scoped (not session-scoped) so a project's drift history
+ * accumulates across sessions.
+ *
+ * Falls back to a session-scoped path when projectUuid is null —
+ * matches the existing drift-catalog.ts fallback shape.
+ */
+export function driftCatalogPath(projectUuid, sessionId, dataRoot) {
+    const root = resolveDataRoot(dataRoot);
+    if (projectUuid) {
+        return path.join(root, "projects", projectUuid, "drift-catalog.jsonl");
+    }
+    return path.join(root, "sessions", sessionId, "drift-catalog.jsonl");
+}
+// =====================================================================
+// SessionEnd cleanup — paths the cleanup phase removes
+// =====================================================================
+/**
+ * Per-session file paths that SessionEnd should clean up. Project-scoped
+ * files (drift-catalog.jsonl) are durable across sessions and excluded.
+ */
+export function sessionStateFiles(sessionId, dataRoot) {
+    return [activeTaskPath(sessionId, dataRoot), violationsPath(sessionId, dataRoot)];
+}
+//# sourceMappingURL=state.js.map

package/dist/anti-drift/state.js.map

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

package/dist/anti-drift/state.test.js

@@ -0,0 +1,120 @@
+/**
+ * Tests for anti-drift/state.ts (0.8 unified-evaluator track foundation).
+ *
+ * Each test uses a fresh tmpdir as dataRoot to keep tests hermetic.
+ */
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { appendViolation, clearActiveTask, consumeViolations, driftCatalogPath, readActiveTask, sessionStateFiles, writeActiveTask, } from "./state.js";
+const SESSION = "test-session-xyz";
+let tmp;
+beforeEach(async () => {
+    tmp = await fs.mkdtemp(path.join(os.tmpdir(), "anti-drift-state-"));
+});
+afterEach(async () => {
+    await fs.rm(tmp, { recursive: true, force: true });
+});
+describe("active-task state", () => {
+    it("readActiveTask returns null when no file exists", async () => {
+        expect(await readActiveTask(SESSION, { dataRoot: tmp })).toBeNull();
+    });
+    it("writeActiveTask + readActiveTask round-trips", async () => {
+        const state = {
+            id: "11",
+            subject: "scaffold anti-drift/state.ts",
+            started_at: "2026-05-18T15:00:00.000Z",
+        };
+        await writeActiveTask(SESSION, state, { dataRoot: tmp });
+        const got = await readActiveTask(SESSION, { dataRoot: tmp });
+        expect(got).toEqual(state);
+    });
+    it("writeActiveTask is overwrite (idempotent for TaskUpdate semantics)", async () => {
+        await writeActiveTask(SESSION, { id: "11", subject: "first", started_at: "2026-05-18T15:00:00.000Z" }, { dataRoot: tmp });
+        await writeActiveTask(SESSION, { id: "11", subject: "updated", started_at: "2026-05-18T15:01:00.000Z" }, { dataRoot: tmp });
+        const got = await readActiveTask(SESSION, { dataRoot: tmp });
+        expect(got?.subject).toBe("updated");
+    });
+    it("clearActiveTask removes the file", async () => {
+        await writeActiveTask(SESSION, { id: "11", started_at: "2026-05-18T15:00:00.000Z" }, { dataRoot: tmp });
+        expect(await readActiveTask(SESSION, { dataRoot: tmp })).not.toBeNull();
+        await clearActiveTask(SESSION, { dataRoot: tmp });
+        expect(await readActiveTask(SESSION, { dataRoot: tmp })).toBeNull();
+    });
+    it("clearActiveTask is idempotent (no error when file absent)", async () => {
+        await expect(clearActiveTask(SESSION, { dataRoot: tmp })).resolves.toBeUndefined();
+    });
+    it("readActiveTask returns null on malformed JSON (fail-safe)", async () => {
+        const dir = path.join(tmp, "sessions", SESSION);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(path.join(dir, "active-task.json"), "not valid json {", "utf8");
+        expect(await readActiveTask(SESSION, { dataRoot: tmp })).toBeNull();
+    });
+    it("readActiveTask returns null on missing required fields", async () => {
+        const dir = path.join(tmp, "sessions", SESSION);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(path.join(dir, "active-task.json"), '{"subject":"no id field"}', "utf8");
+        expect(await readActiveTask(SESSION, { dataRoot: tmp })).toBeNull();
+    });
+});
+describe("violations.log", () => {
+    it("consumeViolations returns empty array when no file exists", async () => {
+        expect(await consumeViolations(SESSION, { dataRoot: tmp })).toEqual([]);
+    });
+    it("appendViolation + consumeViolations round-trips a single entry", async () => {
+        const entry = {
+            ts: "2026-05-18T15:05:00.000Z",
+            rule_id: "active-task-required",
+            verdict: "block",
+            reason: "log_phase called without an in_progress task",
+        };
+        await appendViolation(SESSION, entry, { dataRoot: tmp });
+        expect(await consumeViolations(SESSION, { dataRoot: tmp })).toEqual([entry]);
+    });
+    it("consumeViolations clears the file (atomic claim)", async () => {
+        await appendViolation(SESSION, { ts: "1", rule_id: "x", verdict: "block", reason: "y" }, { dataRoot: tmp });
+        const first = await consumeViolations(SESSION, { dataRoot: tmp });
+        expect(first.length).toBe(1);
+        // Second consume on now-empty state returns empty.
+        expect(await consumeViolations(SESSION, { dataRoot: tmp })).toEqual([]);
+    });
+    it("multiple appends accumulate", async () => {
+        await appendViolation(SESSION, { ts: "1", rule_id: "a", verdict: "block", reason: "r1" }, { dataRoot: tmp });
+        await appendViolation(SESSION, { ts: "2", rule_id: "b", verdict: "warn", reason: "r2" }, { dataRoot: tmp });
+        const got = await consumeViolations(SESSION, { dataRoot: tmp });
+        expect(got.length).toBe(2);
+        expect(got.map((e) => e.rule_id)).toEqual(["a", "b"]);
+    });
+    it("consumeViolations skips malformed lines silently", async () => {
+        const dir = path.join(tmp, "sessions", SESSION);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(path.join(dir, "violations.log"), `not json\n${JSON.stringify({ ts: "1", rule_id: "ok", verdict: "warn", reason: "real" })}\n`, "utf8");
+        const got = await consumeViolations(SESSION, { dataRoot: tmp });
+        expect(got).toHaveLength(1);
+        expect(got[0].rule_id).toBe("ok");
+    });
+});
+describe("driftCatalogPath", () => {
+    it("uses project-scoped path when projectUuid is provided", () => {
+        const got = driftCatalogPath("abc-uuid", SESSION, tmp);
+        expect(got).toBe(path.join(tmp, "projects", "abc-uuid", "drift-catalog.jsonl"));
+    });
+    it("falls back to session-scoped path when projectUuid is null", () => {
+        const got = driftCatalogPath(null, SESSION, tmp);
+        expect(got).toBe(path.join(tmp, "sessions", SESSION, "drift-catalog.jsonl"));
+    });
+});
+describe("sessionStateFiles", () => {
+    it("returns the per-session state file paths for SessionEnd cleanup", () => {
+        const got = sessionStateFiles(SESSION, tmp);
+        expect(got).toContain(path.join(tmp, "sessions", SESSION, "active-task.json"));
+        expect(got).toContain(path.join(tmp, "sessions", SESSION, "violations.log"));
+        expect(got).toHaveLength(2);
+    });
+    it("does NOT include project-scoped paths (drift-catalog.jsonl is durable across sessions)", () => {
+        const got = sessionStateFiles(SESSION, tmp);
+        expect(got.every((p) => !p.includes("/projects/"))).toBe(true);
+        expect(got.every((p) => !p.endsWith("drift-catalog.jsonl"))).toBe(true);
+    });
+});

package/dist/channels/adapters/discord.d.ts

@@ -0,0 +1,45 @@
+/**
+ * discord:// adapter — outbound delivery via discord.js v14.
+ *
+ * URI scheme: `discord://<guild_id>/<channel_id>` (both snowflake numerics).
+ *
+ * Dependency: `discord.js` is an OPTIONAL peerDependency. Users who never
+ * configure a Discord channel pay nothing — we lazy-load the module on
+ * first `start()`/`send()`. If the dependency is missing at runtime, the
+ * adapter surfaces a structured error via `SendResult` rather than
+ * crashing the process.
+ *
+ * Intents: deliberately narrow to `GatewayIntentBits.Guilds` only. We do
+ * NOT request `MessageContent` (which requires verified-bot approval
+ * after 100 servers) because the adapter is outbound-only — we never
+ * read message contents.
+ *
+ * Lifecycle: `start()` logs in + waits for the `ready` event before
+ * resolving so the first `send()` cannot race the gateway handshake.
+ * `stop()` destroys the client. `send()` auto-starts if not yet ready.
+ *
+ * Security: the bot token is closed over by this function and never
+ * appears in any log output, error message, or SendResult — the same
+ * discipline as the Telegram adapter.
+ */
+import type { InboundChannelEvent } from '../../runtime/event.js';
+import type { ChannelAdapter, InboundSubscription } from '../types.js';
+export interface DiscordAdapterOpts {
+    /** Bot token from the Discord Developer Portal. */
+    token: string;
+}
+export interface DiscordAdapter extends ChannelAdapter {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * AUTO.6 — attach a `messageCreate` listener that emits a unified
+     * `InboundChannelEvent`. The first call upgrades the gateway intents
+     * to include `GuildMessages` + `MessageContent` (intents are immutable
+     * after client construction; a subscribeInbound that comes AFTER the
+     * outbound client is already running throws — callers must subscribe
+     * before send() or start()).
+     */
+    subscribeInbound(handler: (event: InboundChannelEvent) => Promise<void>): Promise<InboundSubscription>;
+}
+export declare function discordAdapter(opts: DiscordAdapterOpts): DiscordAdapter;
+//# sourceMappingURL=discord.d.ts.map

package/dist/channels/adapters/discord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discord.d.ts","sourceRoot":"","sources":["../../../src/channels/adapters/discord.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAkB,mBAAmB,EAAc,MAAM,aAAa,CAAC;AAEnG,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAe,SAAQ,cAAc;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB;;;;;;;OAOG;IACH,gBAAgB,CACd,OAAO,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,GACrD,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACjC;AA4DD,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,cAAc,CAqLvE"}