@openagentsy/ledger 0.0.0-stage → 0.2.0

package/dist/policy.d.ts

@@ -0,0 +1,48 @@
+import type { Database } from 'bun:sqlite';
+import type { PolicyFiring, PolicyFiringSink } from '@openagentsy/core';
+/**
+ * Record one policy firing.
+ *
+ * The row is written once and is not deduplicated: a policy that fires twice
+ * in a session fired twice, and the count of the firings is what the report
+ * ranks the policies by.
+ */
+export declare function recordPolicyFiring(db: Database, firing: PolicyFiring): void;
+/**
+ * A sink that writes the firings into a ledger.
+ *
+ * The engine writes through the interface and knows nothing of SQLite, so
+ * the store the rows go into is the caller's choice.
+ */
+export declare function createPolicyFiringSink(db: Database): PolicyFiringSink;
+/** How often one policy was asked, and what it decided. */
+export type PolicyFireCount = {
+    /** The stable id of the policy. */
+    policyId: string;
+    /** How many times the policy was asked. */
+    count: number;
+    /** How many of those times it blocked. */
+    blocks: number;
+    /** How many of those times it flagged. */
+    flags: number;
+    /** The versions the policy carried, newest last. */
+    versions: string[];
+};
+/**
+ * The firing count of every policy the log holds a row for.
+ *
+ * The count is of every evaluation, and the block and flag counts are of the
+ * evaluations that acted, so a reader can see a policy that was asked often
+ * and never acted and one that acted every time.
+ */
+export declare function policyFireCounts(db: Database): PolicyFireCount[];
+/**
+ * The policies with the most firings, the largest first.
+ *
+ * The report asks for the ten of them; the number is a limit and not a
+ * promise, because a log with fewer policies has fewer to show.
+ */
+export declare function topPoliciesByFireCount(db: Database, limit?: number): PolicyFireCount[];
+/** How many firings the log holds in all. */
+export declare function policyFiringTotal(db: Database): number;
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAoBxE;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAmB3E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,QAAQ,GAAG,gBAAgB,CAMrE;AAED,2DAA2D;AAC3D,MAAM,MAAM,eAAe,GAAG;IAC5B,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG,eAAe,EAAE,CAqBhE;AAoBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,SAAK,GAAG,eAAe,EAAE,CAElF;AAED,6CAA6C;AAC7C,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,CAKtD"}

package/dist/policy.js

@@ -0,0 +1,99 @@
+import { randomUUID } from 'node:crypto';
+import { withBusyRetry } from './db.js';
+/**
+ * The policy firing log (§21.3).
+ *
+ * Every policy that was asked for a decision leaves a row here: the policy
+ * id, the version it carried at that moment, the session it happened in and
+ * what it decided. The version is the point of the row — a regression is
+ * attributed to the version that caused it and not to the policy in general.
+ *
+ * The table is the ledger's, and the rows go into the ledger's database file,
+ * so the log survives a restart: it is a store and not a memory.
+ */
+const INSERT = `INSERT INTO policy_firing
+  (id, session_id, policy_id, policy_version, layer, action, severity, reason,
+   finding_id, classification, detail, origin, ts)
+  VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)`;
+/**
+ * Record one policy firing.
+ *
+ * The row is written once and is not deduplicated: a policy that fires twice
+ * in a session fired twice, and the count of the firings is what the report
+ * ranks the policies by.
+ */
+export function recordPolicyFiring(db, firing) {
+    const ts = firing.ts ?? new Date().toISOString();
+    withBusyRetry(() => {
+        db.query(INSERT).run(randomUUID(), firing.sessionId, firing.policyId, firing.policyVersion, firing.layer, firing.action, firing.severity ?? null, firing.reason ?? null, firing.findingId ?? null, firing.classification ?? null, firing.detail ?? null, firing.origin ?? 'first-party', ts);
+    });
+}
+/**
+ * A sink that writes the firings into a ledger.
+ *
+ * The engine writes through the interface and knows nothing of SQLite, so
+ * the store the rows go into is the caller's choice.
+ */
+export function createPolicyFiringSink(db) {
+    return {
+        record: (firing) => {
+            recordPolicyFiring(db, firing);
+        },
+    };
+}
+/**
+ * The firing count of every policy the log holds a row for.
+ *
+ * The count is of every evaluation, and the block and flag counts are of the
+ * evaluations that acted, so a reader can see a policy that was asked often
+ * and never acted and one that acted every time.
+ */
+export function policyFireCounts(db) {
+    const rows = db
+        .query(`SELECT
+         policy_id AS policyId,
+         COUNT(*) AS count,
+         SUM(CASE WHEN action = 'block' THEN 1 ELSE 0 END) AS blocks,
+         SUM(CASE WHEN action = 'flag' THEN 1 ELSE 0 END) AS flags
+       FROM policy_firing
+       GROUP BY policy_id
+       ORDER BY count DESC, policy_id ASC`)
+        .all();
+    return rows.map((row) => ({
+        policyId: row.policyId,
+        count: row.count,
+        blocks: row.blocks,
+        flags: row.flags,
+        versions: policyVersions(db, row.policyId),
+    }));
+}
+/**
+ * The versions one policy carried, in the order they were seen.
+ *
+ * A policy that carried two versions was changed between the two firings,
+ * and the log is where that is visible.
+ */
+function policyVersions(db, policyId) {
+    const rows = db
+        .query(`SELECT DISTINCT policy_version AS version
+       FROM policy_firing
+       WHERE policy_id = ?
+       ORDER BY policy_version ASC`)
+        .all(policyId);
+    return rows.map((row) => row.version ?? 'unknown');
+}
+/**
+ * The policies with the most firings, the largest first.
+ *
+ * The report asks for the ten of them; the number is a limit and not a
+ * promise, because a log with fewer policies has fewer to show.
+ */
+export function topPoliciesByFireCount(db, limit = 10) {
+    return policyFireCounts(db).slice(0, Math.max(0, limit));
+}
+/** How many firings the log holds in all. */
+export function policyFiringTotal(db) {
+    const row = db.query('SELECT COUNT(*) AS total FROM policy_firing').get();
+    return row?.total ?? 0;
+}
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExC;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,GAAG;;;qCAGsB,CAAC;AAEtC;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAY,EAAE,MAAoB;IACnE,MAAM,EAAE,GAAG,MAAM,CAAC,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACjD,aAAa,CAAC,GAAG,EAAE;QACjB,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAClB,UAAU,EAAE,EACZ,MAAM,CAAC,SAAS,EAChB,MAAM,CAAC,QAAQ,EACf,MAAM,CAAC,aAAa,EACpB,MAAM,CAAC,KAAK,EACZ,MAAM,CAAC,MAAM,EACb,MAAM,CAAC,QAAQ,IAAI,IAAI,EACvB,MAAM,CAAC,MAAM,IAAI,IAAI,EACrB,MAAM,CAAC,SAAS,IAAI,IAAI,EACxB,MAAM,CAAC,cAAc,IAAI,IAAI,EAC7B,MAAM,CAAC,MAAM,IAAI,IAAI,EACrB,MAAM,CAAC,MAAM,IAAI,aAAa,EAC9B,EAAE,CACH,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,EAAY;IACjD,OAAO;QACL,MAAM,EAAE,CAAC,MAAoB,EAAE,EAAE;YAC/B,kBAAkB,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACjC,CAAC;KACF,CAAC;AACJ,CAAC;AAgBD;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAY;IAC3C,MAAM,IAAI,GAAG,EAAE;SACZ,KAAK,CACJ;;;;;;;0CAOoC,CACrC;SACA,GAAG,EAA0E,CAAC;IAEjF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACxB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,QAAQ,EAAE,cAAc,CAAC,EAAE,EAAE,GAAG,CAAC,QAAQ,CAAC;KAC3C,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,SAAS,cAAc,CAAC,EAAY,EAAE,QAAgB;IACpD,MAAM,IAAI,GAAG,EAAE;SACZ,KAAK,CACJ;;;mCAG6B,CAC9B;SACA,GAAG,CAAC,QAAQ,CAAiC,CAAC;IACjD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,IAAI,SAAS,CAAC,CAAC;AACrD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,EAAY,EAAE,KAAK,GAAG,EAAE;IAC7D,OAAO,gBAAgB,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,iBAAiB,CAAC,EAAY;IAC5C,MAAM,GAAG,GAAG,EAAE,CAAC,KAAK,CAAC,6CAA6C,CAAC,CAAC,GAAG,EAE/D,CAAC;IACT,OAAO,GAAG,EAAE,KAAK,IAAI,CAAC,CAAC;AACzB,CAAC"}

package/dist/policy.test.d.ts

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

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

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

package/dist/policy.test.js

@@ -0,0 +1,126 @@
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { closeLedger, openLedger } from './db.js';
+import { createPolicyFiringSink, policyFireCounts, policyFiringTotal, recordPolicyFiring, topPoliciesByFireCount, } from './policy.js';
+/**
+ * The policy firing log (§21.3).
+ *
+ * The log is a store and not a memory: the rows are read back after the
+ * ledger was closed and opened again.
+ */
+/** A ledger in a directory of its own. */
+function ledger() {
+    const root = mkdtempSync(join(tmpdir(), 'openagentsy-policy-'));
+    return { root, db: openLedger(root) };
+}
+describe('the policy firing log', () => {
+    it('reads back what was written after the ledger was closed and opened again', () => {
+        const { root, db } = ledger();
+        recordPolicyFiring(db, {
+            sessionId: 'ses_1',
+            policyId: 'oa.anti-sycophancy',
+            policyVersion: '1.0.0',
+            layer: 4,
+            action: 'flag',
+            severity: 'warn',
+            reason: 'praise',
+            origin: 'first-party',
+        });
+        recordPolicyFiring(db, {
+            sessionId: 'ses_1',
+            policyId: 'oa.anti-sycophancy',
+            policyVersion: '1.0.0',
+            layer: 4,
+            action: 'block',
+            reason: 'high-risk domain',
+            origin: 'first-party',
+        });
+        recordPolicyFiring(db, {
+            sessionId: 'ses_2',
+            policyId: 'oa.agi-framing',
+            policyVersion: '1.2.0',
+            layer: 4,
+            action: 'allow',
+            origin: 'external',
+        });
+        closeLedger(db);
+        const again = openLedger(root);
+        try {
+            expect(policyFiringTotal(again)).toBe(3);
+            const counts = topPoliciesByFireCount(again, 10);
+            expect(counts[0]?.policyId).toBe('oa.anti-sycophancy');
+            expect(counts[0]?.count).toBe(2);
+            expect(counts[0]?.flags).toBe(1);
+            expect(counts[0]?.blocks).toBe(1);
+            expect(counts[0]?.versions).toEqual(['1.0.0']);
+            expect(counts[1]?.policyId).toBe('oa.agi-framing');
+            expect(counts[1]?.versions).toEqual(['1.2.0']);
+        }
+        finally {
+            closeLedger(again);
+        }
+    });
+    it('holds the version the policy carried when it fired', () => {
+        const { db } = ledger();
+        try {
+            recordPolicyFiring(db, {
+                sessionId: 'ses_1',
+                policyId: 'oa.anti-sycophancy',
+                policyVersion: '1.1.0',
+                layer: 4,
+                action: 'allow',
+                origin: 'first-party',
+            });
+            const row = db
+                .query('SELECT policy_version, session_id, action FROM policy_firing WHERE policy_id = ?')
+                .get('oa.anti-sycophancy');
+            expect(row.policy_version).toBe('1.1.0');
+            expect(row.session_id).toBe('ses_1');
+            expect(row.action).toBe('allow');
+        }
+        finally {
+            closeLedger(db);
+        }
+    });
+    it('marks a module a plugin brought as external', () => {
+        const { db } = ledger();
+        try {
+            const sink = createPolicyFiringSink(db);
+            sink.record({
+                sessionId: 'ses_1',
+                policyId: 'acme.no-warnings',
+                policyVersion: '0.1.0',
+                layer: 4,
+                action: 'allow',
+                origin: 'external',
+            });
+            const row = db
+                .query('SELECT origin FROM policy_firing WHERE policy_id = ?')
+                .get('acme.no-warnings');
+            expect(row.origin).toBe('external');
+        }
+        finally {
+            closeLedger(db);
+        }
+    });
+    it('counts every policy the log holds a row for', () => {
+        const { db } = ledger();
+        try {
+            recordPolicyFiring(db, {
+                sessionId: 'ses_1',
+                policyId: 'oa.agi-framing',
+                policyVersion: '1.0.0',
+                layer: 4,
+                action: 'allow',
+                origin: 'first-party',
+            });
+            expect(policyFireCounts(db).map((entry) => entry.policyId)).toEqual(['oa.agi-framing']);
+        }
+        finally {
+            closeLedger(db);
+        }
+    });
+});
+//# sourceMappingURL=policy.test.js.map

package/dist/policy.test.js.map

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

package/dist/pricing.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The pricing chain (§6.3).
+ *
+ * The reported cost of a message wins, then models.dev, then LiteLLM, then
+ * OpenRouter, and then nothing: a model nobody prices stays unpriced and is
+ * shown as unpriced, never as zero dollars. A zero would be a lie about
+ * money, and a report that says "free" is a report nobody can act on.
+ */
+/** The token counts of one message. */
+export type TokenCounts = {
+    input: number;
+    output: number;
+    reasoning?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+};
+/** The rates of a band, per million tokens. */
+export type Rates = {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+};
+/**
+ * A band of the pricing.
+ *
+ * `above` is the number of input tokens the band starts at. A source with
+ * no tiers has one band, from zero upwards.
+ */
+export type Tier = Rates & {
+    above: number;
+};
+/** Where a price came from. */
+export type PriceSource = 'reported' | 'models.dev' | 'litellm' | 'openrouter' | 'none';
+export type PriceResult = {
+    /** The price in dollars, or null when no source knows it. */
+    cost: number | null;
+    source: PriceSource;
+    /** The bands that priced it. */
+    tiers?: Tier[];
+};
+export type PriceOptions = {
+    /** The cost OpenCode reported, when it reported one. */
+    reportedCost?: number | null;
+    /** Where the cached sources live. */
+    cacheDir?: string;
+    /** The fetch to use, so a test does not need the network. */
+    fetchImpl?: FetchLike;
+    /** How long a fetch may take. */
+    timeoutMs?: number;
+    /** The clock, so a test can age a cache file. */
+    now?: () => number;
+    /** Where the bundled snapshot lives. */
+    snapshotDir?: string;
+};
+/**
+ * The fetch the chain uses.
+ *
+ * It is not the global `fetch` type, because a test hands in a plain
+ * function and the global one carries properties a double does not have.
+ */
+export type FetchLike = (url: string, init?: {
+    signal?: AbortSignal;
+}) => Promise<Response>;
+/** How long a cached source stays fresh. */
+export declare const CACHE_TTL_MS: number;
+/** How long a fetch may take before the chain moves on. */
+export declare const FETCH_TIMEOUT_MS = 10000;
+/** One source of the chain. */
+export type Source = {
+    name: PriceSource;
+    /** The file the source is cached in. */
+    file: string;
+    url: string;
+    reduce: (raw: unknown) => unknown;
+    lookup: (payload: unknown, provider: string, model: string) => Tier[] | null;
+};
+/** The chain, in order. The first hit wins. */
+export declare const SOURCES: readonly Source[];
+/** Where the cached sources live. */
+export declare function defaultCacheDir(): string;
+/** Where the bundled snapshot lives. */
+export declare function defaultSnapshotDir(): string;
+/**
+ * The price of a message.
+ *
+ * The reported cost of the message wins, because the host knows what it
+ * charged. After that the chain runs, and when every source fails the
+ * result is a null cost and the source `none`: unpriced, not free.
+ */
+export declare function priceMessage(provider: string, model: string, tokens: TokenCounts, options?: PriceOptions): Promise<PriceResult>;
+//# sourceMappingURL=pricing.d.ts.map

package/dist/pricing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../src/pricing.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AAEH,uCAAuC;AACvC,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,+CAA+C;AAC/C,MAAM,MAAM,KAAK,GAAG;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,KAAK,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,+BAA+B;AAC/B,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,GAAG,YAAY,GAAG,MAAM,CAAC;AAExF,MAAM,MAAM,WAAW,GAAG;IACxB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,WAAW,CAAC;IACpB,gCAAgC;IAChC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE5F,4CAA4C;AAC5C,eAAO,MAAM,YAAY,QAAsB,CAAC;AAChD,2DAA2D;AAC3D,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAqMvC,+BAA+B;AAC/B,MAAM,MAAM,MAAM,GAAG;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IAClC,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,EAAE,GAAG,IAAI,CAAC;CAC9E,CAAC;AAEF,+CAA+C;AAC/C,eAAO,MAAM,OAAO,EAAE,SAAS,MAAM,EAwCpC,CAAC;AAEF,qCAAqC;AACrC,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,wCAAwC;AACxC,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AA+DD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CAiBtB"}