@openagentsy/ledger 0.0.0-stage → 0.2.1

package/dist/schema.d.ts

@@ -0,0 +1,33 @@
+import type { Database } from 'bun:sqlite';
+/**
+ * The ledger's schema.
+ *
+ * Numbers only: token counts, model ids, timestamps, task ids and commit
+ * shas. A prompt, a completion or a line of code never reaches this
+ * database — the transcripts stay in OpenCode's own storage, and the ledger
+ * only ever holds the counters.
+ */
+/** The role keys the resolver hands the ledger (§6.1). */
+export declare const ROLE_KEYS: readonly ["lead", "scout", "researcher", "builder", "reviewer", "advisor", "archivist", "offload"];
+export type RoleKey = (typeof ROLE_KEYS)[number];
+/** The waste signals of §6.4. */
+export declare const WASTE_KINDS: readonly ["retry", "tool_error_loop", "interrupted", "undo", "reverted_code", "cache_miss", "no_progress"];
+export type WasteKind = (typeof WASTE_KINDS)[number];
+/** The outcome kinds of §6.5. */
+export declare const OUTCOME_KINDS: readonly ["task_completed", "task_scrapped", "commit", "pr_merged"];
+export type OutcomeKind = (typeof OUTCOME_KINDS)[number];
+/**
+ * The tables.
+ *
+ * `usage` carries the resolved role: the `role` column is the role key the
+ * adapter resolved, and `role_raw` holds the unresolved agent id of a
+ * backfilled row, which no per-role report counts.
+ *
+ * The two REV3 tables are schema only for now: their writers land in 2f.
+ * `policy_firing` carries the audit columns of REV3 §21.3 next to the
+ * classification and the detail, so the trace survives.
+ */
+export declare const SCHEMA_SQL: string;
+/** Bring the database up to the schema. Opening twice changes nothing. */
+export declare function applySchema(db: Database): void;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;GAOG;AAEH,0DAA0D;AAC1D,eAAO,MAAM,SAAS,oGASZ,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD,iCAAiC;AACjC,eAAO,MAAM,WAAW,4GAQd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,iCAAiC;AACjC,eAAO,MAAM,aAAa,qEAAsE,CAAC;AAEjG,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAOzD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,QAkEtB,CAAC;AAuBF,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAG9C"}

package/dist/schema.js

@@ -0,0 +1,139 @@
+/**
+ * The ledger's schema.
+ *
+ * Numbers only: token counts, model ids, timestamps, task ids and commit
+ * shas. A prompt, a completion or a line of code never reaches this
+ * database — the transcripts stay in OpenCode's own storage, and the ledger
+ * only ever holds the counters.
+ */
+/** The role keys the resolver hands the ledger (§6.1). */
+export const ROLE_KEYS = [
+    'lead',
+    'scout',
+    'researcher',
+    'builder',
+    'reviewer',
+    'advisor',
+    'archivist',
+    'offload',
+];
+/** The waste signals of §6.4. */
+export const WASTE_KINDS = [
+    'retry',
+    'tool_error_loop',
+    'interrupted',
+    'undo',
+    'reverted_code',
+    'cache_miss',
+    'no_progress',
+];
+/** The outcome kinds of §6.5. */
+export const OUTCOME_KINDS = ['task_completed', 'task_scrapped', 'commit', 'pr_merged'];
+/** The list a CHECK constraint takes. */
+function kindList(kinds) {
+    return kinds.map((kind) => `'${kind}'`).join(',');
+}
+/**
+ * The tables.
+ *
+ * `usage` carries the resolved role: the `role` column is the role key the
+ * adapter resolved, and `role_raw` holds the unresolved agent id of a
+ * backfilled row, which no per-role report counts.
+ *
+ * The two REV3 tables are schema only for now: their writers land in 2f.
+ * `policy_firing` carries the audit columns of REV3 §21.3 next to the
+ * classification and the detail, so the trace survives.
+ */
+export const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS usage (
+  message_id      TEXT PRIMARY KEY,        -- dedup key (OpenCode message id)
+  session_id      TEXT NOT NULL,
+  root_session_id TEXT NOT NULL,           -- Lead session; subagents roll up here
+  role            TEXT,                    -- RESOLVED role key
+  role_raw        TEXT,                    -- unresolved agent id, backfilled rows only
+  provider        TEXT NOT NULL,
+  model           TEXT NOT NULL,
+  input           INTEGER NOT NULL DEFAULT 0,
+  output          INTEGER NOT NULL DEFAULT 0,
+  reasoning       INTEGER NOT NULL DEFAULT 0,
+  cache_read      INTEGER NOT NULL DEFAULT 0,
+  cache_write     INTEGER NOT NULL DEFAULT 0,
+  cost_reported   REAL,                    -- from OpenCode message.cost, if present
+  cost_estimated  REAL,                    -- from pricing chain; NULL = unpriced (never 0)
+  latency_ms      INTEGER,
+  task_id         TEXT,                    -- in-progress task at the time, if any
+  ts              TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS usage_root ON usage(root_session_id);
+CREATE INDEX IF NOT EXISTS usage_task ON usage(task_id);
+
+CREATE TABLE IF NOT EXISTS waste (
+  id INTEGER PRIMARY KEY, root_session_id TEXT, message_id TEXT,
+  kind TEXT CHECK (kind IN (${kindList(WASTE_KINDS)})),
+  tokens INTEGER NOT NULL, detail TEXT, ts TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS outcome (
+  id INTEGER PRIMARY KEY, root_session_id TEXT, task_id TEXT, commit_sha TEXT,
+  kind TEXT CHECK (kind IN (${kindList(OUTCOME_KINDS)})), ts TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS footprint (
+  message_id TEXT PRIMARY KEY REFERENCES usage(message_id),
+  energy_lo REAL, energy_hi REAL, water_lo REAL, water_hi REAL,
+  co2_lo REAL, co2_hi REAL, method_version TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS policy_firing (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  policy_id TEXT NOT NULL,
+  policy_version TEXT,
+  layer INTEGER,
+  action TEXT NOT NULL,
+  severity TEXT,
+  reason TEXT,
+  finding_id TEXT,
+  classification TEXT,
+  detail TEXT,
+  origin TEXT,                     -- 'first-party' | 'external' (§21)
+  ts TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_policy_firing_session ON policy_firing(session_id, ts);
+CREATE INDEX IF NOT EXISTS idx_policy_firing_policy ON policy_firing(policy_id, ts);
+
+CREATE TABLE IF NOT EXISTS safety_metric (
+  id INTEGER PRIMARY KEY,
+  ts TEXT NOT NULL,
+  session_id TEXT,
+  metric TEXT NOT NULL,
+  value REAL,
+  cohort TEXT
+);
+`;
+/**
+ * The columns the policy_firing table gained after it was first written.
+ *
+ * A ledger that was written before a column existed still has to take the
+ * rows of the policies that fire now, so the column is added on open. The
+ * check makes it happen once: a column that is there is not added again.
+ */
+const POLICY_FIRING_COLUMNS = [
+    { name: 'origin', ddl: 'ALTER TABLE policy_firing ADD COLUMN origin TEXT' },
+];
+/** Add the columns a ledger that was written before does not have. */
+function migratePolicyFiring(db) {
+    const columns = db.query('PRAGMA table_info(policy_firing)').all();
+    const names = new Set(columns.map((column) => column.name));
+    for (const column of POLICY_FIRING_COLUMNS) {
+        if (names.has(column.name))
+            continue;
+        db.exec(column.ddl);
+    }
+}
+/** Bring the database up to the schema. Opening twice changes nothing. */
+export function applySchema(db) {
+    db.exec(SCHEMA_SQL);
+    migratePolicyFiring(db);
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,0DAA0D;AAC1D,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,MAAM;IACN,OAAO;IACP,YAAY;IACZ,SAAS;IACT,UAAU;IACV,SAAS;IACT,WAAW;IACX,SAAS;CACD,CAAC;AAIX,iCAAiC;AACjC,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,OAAO;IACP,iBAAiB;IACjB,aAAa;IACb,MAAM;IACN,eAAe;IACf,YAAY;IACZ,aAAa;CACL,CAAC;AAIX,iCAAiC;AACjC,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,gBAAgB,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,CAAU,CAAC;AAIjG,yCAAyC;AACzC,SAAS,QAAQ,CAAC,KAAwB;IACxC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;8BAyBI,QAAQ,CAAC,WAAW,CAAC;;;;;;8BAMrB,QAAQ,CAAC,aAAa,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCpD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,qBAAqB,GAA6C;IACtE,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,kDAAkD,EAAE;CAC5E,CAAC;AAEF,sEAAsE;AACtE,SAAS,mBAAmB,CAAC,EAAY;IACvC,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC,GAAG,EAAwB,CAAC;IACzF,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5D,KAAK,MAAM,MAAM,IAAI,qBAAqB,EAAE,CAAC;QAC3C,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,SAAS;QACrC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,WAAW,CAAC,EAAY;IACtC,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACpB,mBAAmB,CAAC,EAAE,CAAC,CAAC;AAC1B,CAAC"}

package/dist/schema.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=schema.test.d.ts.map

package/dist/schema.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.test.d.ts","sourceRoot":"","sources":["../src/schema.test.ts"],"names":[],"mappings":""}

package/dist/schema.test.js

@@ -0,0 +1,129 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { BUSY_RETRIES, closeLedger, isBusyError, openLedger, withBusyRetry } from './db.js';
+import { applySchema } from './schema.js';
+let root;
+beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'openagentsy-ledger-'));
+});
+afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+});
+const INSERT = `INSERT INTO usage (message_id, session_id, root_session_id, provider, model, ts)
+  VALUES ('msg_lock','ses','root','p','m','2026-10-26T00:00:00.000Z')`;
+describe('the ledger schema', () => {
+    it('holds the six tables of the plan', () => {
+        const db = openLedger(root);
+        try {
+            const tables = db
+                .query("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'")
+                .all();
+            expect(tables.map((row) => row.name).sort()).toEqual([
+                'footprint',
+                'outcome',
+                'policy_firing',
+                'safety_metric',
+                'usage',
+                'waste',
+            ]);
+        }
+        finally {
+            closeLedger(db);
+        }
+    });
+    it('is the same after it is applied twice', () => {
+        const db = openLedger(root);
+        try {
+            const read = () => db
+                .query("SELECT name, sql FROM sqlite_master WHERE type IN ('table','index') ORDER BY name")
+                .all();
+            const before = read();
+            applySchema(db);
+            expect(read()).toEqual(before);
+        }
+        finally {
+            closeLedger(db);
+        }
+    });
+    it('opens in WAL mode with a busy timeout', () => {
+        const db = openLedger(root);
+        try {
+            const journal = db.query('PRAGMA journal_mode').get();
+            expect(journal.journal_mode.toLowerCase()).toBe('wal');
+            const busy = db.query('PRAGMA busy_timeout').get();
+            expect(busy.timeout).toBe(250);
+        }
+        finally {
+            closeLedger(db);
+        }
+    });
+});
+describe('the busy retry', () => {
+    it('tries five times and then gives up', () => {
+        let attempts = 0;
+        expect(() => withBusyRetry(() => {
+            attempts += 1;
+            throw new Error('SQLITE_BUSY: database is locked');
+        })).toThrow(/SQLITE_BUSY/);
+        expect(attempts).toBe(BUSY_RETRIES + 1);
+    });
+    it('returns the value of the first attempt that works', () => {
+        let attempts = 0;
+        const value = withBusyRetry(() => {
+            attempts += 1;
+            if (attempts < 3)
+                throw new Error('database is locked');
+            return 'written';
+        });
+        expect(value).toBe('written');
+        expect(attempts).toBe(3);
+    });
+    it('does not retry an error that is not a busy one', () => {
+        let attempts = 0;
+        expect(() => withBusyRetry(() => {
+            attempts += 1;
+            throw new Error('no such table: usage');
+        })).toThrow(/no such table/);
+        expect(attempts).toBe(1);
+    });
+    it('gives up on a locked database and writes once the lock is gone', () => {
+        const writer = openLedger(root);
+        const other = openLedger(root);
+        try {
+            other.exec('PRAGMA busy_timeout = 0');
+            writer.exec('BEGIN EXCLUSIVE');
+            // The error has to be the busy one, and the loop has to have tried
+            // again: a retry that never retries would pass a plain toThrow.
+            let caught;
+            let attempts = 0;
+            try {
+                withBusyRetry(() => {
+                    attempts += 1;
+                    return other.query(INSERT).run();
+                });
+            }
+            catch (error) {
+                caught = error;
+            }
+            expect(caught).toBeDefined();
+            expect(isBusyError(caught)).toBe(true);
+            expect(String(caught.message)).toMatch(/locked|SQLITE_BUSY/);
+            expect(attempts).toBeGreaterThan(1);
+            expect(attempts).toBe(BUSY_RETRIES + 1);
+            writer.exec('COMMIT');
+            let written = 0;
+            expect(() => withBusyRetry(() => {
+                written += 1;
+                return other.query(INSERT).run();
+            })).not.toThrow();
+            expect(written).toBe(1);
+        }
+        finally {
+            closeLedger(writer);
+            closeLedger(other);
+        }
+    });
+});
+//# sourceMappingURL=schema.test.js.map

package/dist/schema.test.js.map

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

package/dist/waste.d.ts

@@ -0,0 +1,116 @@
+import { Database } from 'bun:sqlite';
+import type { WasteKind } from './schema.js';
+/**
+ * The waste signals of §6.4 — and who finds them.
+ *
+ * The seven kinds of §6.4 split in two, and the split is by what the
+ * detector needs to see:
+ *
+ * - `cache_miss`, `no_progress` and `reverted_code` are computable from what
+ *   is already on disk — OpenCode's own storage, the board's records and the
+ *   repository — so this module finds them. They need no live event.
+ * - `retry`, `tool_error_loop`, `interrupted` and `undo` are properties of a
+ *   tool call while it happens: they need the event bridge of the plugin, so
+ *   they are recorded by the bridge through the same `recordWaste` this
+ *   module writes with. `HOOK_WASTE_KINDS` names them, so the two halves can
+ *   be counted apart.
+ *
+ * The full list of the seven is `WASTE_KINDS` in the schema, and the CHECK
+ * constraint on the `waste` table holds all of them.
+ */
+/** The kinds this module can find on its own. */
+export declare const DETECTED_WASTE_KINDS: readonly ["cache_miss", "no_progress", "reverted_code"];
+/** The kinds the event bridge finds, because they live in the tool call. */
+export declare const HOOK_WASTE_KINDS: readonly ["retry", "tool_error_loop", "interrupted", "undo"];
+/** The ratio below which a turn counts as a cache miss (§6.4). */
+export declare const CACHE_MISS_RATIO = 0.5;
+/** How long a revert may take before it is not a revert any more (§6.4). */
+export declare const REVERT_WINDOW_DAYS = 14;
+/** A waste signal, ready to be written. */
+export type WasteCandidate = {
+    kind: WasteKind;
+    tokens: number;
+    ts: string;
+    rootSessionId?: string | undefined;
+    messageId?: string | undefined;
+    detail?: string | undefined;
+};
+/**
+ * Write the waste signals, and skip the ones that are already there.
+ *
+ * A detector is a command: it runs again and again over the same history,
+ * so it must not count the same turn twice. The dedup key is the kind and
+ * the message for a message-bound signal, and the kind, the time and the
+ * detail for one that has no message.
+ */
+export declare function recordWasteRows(db: Database, rows: WasteCandidate[]): number;
+/** What the cache-miss detector needs to know. */
+export type CacheMissOptions = {
+    /** Where OpenCode keeps its storage. */
+    dataDir?: string | undefined;
+    /** Only the turns that happened after this instant. */
+    since?: string | undefined;
+    /** The sessions to read; by default the sessions the ledger knows. */
+    sessions?: string[] | undefined;
+    /** The ratio below which a turn counts as a miss. */
+    threshold?: number | undefined;
+};
+/**
+ * The cache misses of §6.4.
+ *
+ * A turn with no new user parts since the previous assistant message is a
+ * retry or a continuation: the prefix was unchanged by definition, so a low
+ * cache ratio is the model's problem and not the user's. The detection reads
+ * the message list of a session: the pair is the previous assistant message
+ * and the one after it, and a user message between them ends the pair. A
+ * user message that carried no text part does not end it — nothing new came
+ * from the user — but only when the storage records parts at all.
+ *
+ * The tokens counted are the uncached input of the turn — the part of the
+ * prefix the model had to read again.
+ */
+export declare function detectCacheMiss(db: Database, options?: CacheMissOptions): WasteCandidate[];
+/** What the no-progress detector needs to know. */
+export type NoProgressOptions = {
+    /** The agent id the Lead writes its records under. */
+    leadAgent?: string | undefined;
+    /** The role key the Lead's usage rows carry. */
+    leadRole?: string | undefined;
+    /** Only the rounds that closed after this instant. */
+    since?: string | undefined;
+};
+/**
+ * The rounds of the Lead that went nowhere (§6.4, §8.7).
+ *
+ * A round that dispatched nothing, consumed no results and changed nothing
+ * on the board cannot claim progress, so it is written down as waste. The
+ * tokens counted are the round's tokens — the Lead's own.
+ */
+export declare function detectNoProgress(db: Database, boardDb: Database, options?: NoProgressOptions): WasteCandidate[];
+/**
+ * The no-progress rounds, read from the board at a path.
+ *
+ * The board is opened read-only and closed again here, so a caller does not
+ * have to know how the board is stored.
+ */
+export declare function detectNoProgressAtPath(db: Database, boardPath: string, options?: NoProgressOptions): WasteCandidate[];
+/** What the revert scanner needs to know. */
+export type RevertOptions = {
+    /** The tokens the builders of a task spent, for the share. */
+    tokensForTask?: ((taskId: string) => number) | undefined;
+    /** How long a revert may take. */
+    windowDays?: number | undefined;
+};
+/**
+ * The reverted code of §6.4.
+ *
+ * A commit that carries a `Refs:` trailer and whose lines are deleted again
+ * within the window is code that was written and then taken back. The tokens
+ * counted are the builder tokens of the task, times the share of the added
+ * lines that were lost.
+ *
+ * This is a command and not a daemon: it walks the history of a repository
+ * once, when a person or the Lead asks for it.
+ */
+export declare function scanReverts(gitDir: string, since: string, options?: RevertOptions): WasteCandidate[];
+//# sourceMappingURL=waste.d.ts.map

package/dist/waste.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"waste.d.ts","sourceRoot":"","sources":["../src/waste.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAatC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AAEH,iDAAiD;AACjD,eAAO,MAAM,oBAAoB,yDAA0D,CAAC;AAE5F,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,8DAA+D,CAAC;AAE7F,kEAAkE;AAClE,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,2CAA2C;AAC3C,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B,CAAC;AAWF;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,MAAM,CAe5E;AAuID,kDAAkD;AAClD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAChC,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,GAAE,gBAAqB,GAAG,cAAc,EAAE,CAuB9F;AAqHD,mDAAmD;AACnD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,CAAC;AAgHF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,QAAQ,EACZ,OAAO,EAAE,QAAQ,EACjB,OAAO,GAAE,iBAAsB,GAC9B,cAAc,EAAE,CAclB;AAgCD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,QAAQ,EACZ,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,iBAAsB,GAC9B,cAAc,EAAE,CAQlB;AAWD,6CAA6C;AAC7C,MAAM,MAAM,aAAa,GAAG;IAC1B,8DAA8D;IAC9D,aAAa,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,CAAC;IACzD,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,cAAc,EAAE,CAsBlB"}