@animalabs/context-manager 0.4.0 → 0.5.0

package/dist/test/adaptive/doc-plus-chat.test.js

@@ -0,0 +1,194 @@
+/**
+ * Realistic Lena-migration scenario: a chronicle that starts with a large doc,
+ * then has many turns of chat about/with that doc.
+ *
+ * Verifies the doc gets sharded at ingestion, the chat turns coexist with
+ * the doc shards, the picker handles both correctly, and the compiled
+ * output structure makes sense throughout.
+ */
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { rmSync, existsSync } from 'node:fs';
+import { ContextManager, AutobiographicalStrategy } from '../../src/index.js';
+const TEST_STORE_PATH = './test-adaptive-doc-plus-chat-store';
+function cleanup() {
+    if (existsSync(TEST_STORE_PATH)) {
+        rmSync(TEST_STORE_PATH, { recursive: true, force: true });
+    }
+}
+function makeMockMembrane() {
+    let callCount = 0;
+    return {
+        complete: async () => {
+            callCount++;
+            return {
+                content: [{ type: 'text', text: `[mock summary #${callCount}] short content.` }],
+            };
+        },
+        get callCount() {
+            return callCount;
+        },
+    };
+}
+function compiledTokens(compiled) {
+    let total = 0;
+    for (const m of compiled.messages) {
+        for (const block of m.content) {
+            if (block.type === 'text')
+                total += Math.ceil(block.text.length / 4);
+        }
+    }
+    return total;
+}
+describe('AutobiographicalStrategy — doc + chat workload (Lena-like)', () => {
+    before(() => cleanup());
+    after(() => cleanup());
+    beforeEach(() => cleanup());
+    it('500K-equivalent doc + 50 chat turns: budget honored throughout', async () => {
+        const mock = makeMockMembrane();
+        const BUDGET = 30000;
+        const strategy = new AutobiographicalStrategy({
+            adaptiveResolution: true,
+            targetChunkTokens: 1000, // ~4K chars per shard
+            recentWindowTokens: 2000,
+            mergeThreshold: 6,
+            compressionSlackRatio: 0.1,
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+            membrane: mock,
+        });
+        // Synthetic ~500K-equivalent doc. Use 50K chars ≈ 12.5K tokens for test
+        // speed; chunker treats ~1K tokens per shard. ~12 shards.
+        const sections = [];
+        for (let s = 0; s < 12; s++) {
+            sections.push(`# Section ${s}\n\n` + 'paragraph content with some words. '.repeat(40));
+        }
+        const doc = sections.join('\n\n');
+        manager.addMessage('User', [{ type: 'text', text: doc }]);
+        // Verify sharding happened at ingestion
+        const allMessages = manager.getAllMessages();
+        assert.ok(allMessages.length > 1, `expected doc to shard; got ${allMessages.length} messages`);
+        const shardCount = allMessages.length;
+        const groupId = allMessages[0].bodyGroupId;
+        assert.ok(groupId, 'first shard should have bodyGroupId');
+        for (const m of allMessages) {
+            assert.equal(m.bodyGroupId, groupId, 'all shards share bodyGroupId');
+        }
+        while (!manager.isReady()) {
+            await manager.tick();
+        }
+        // First compile after doc — verify budget honored
+        const compiledAfterDoc = await manager.compile({ maxTokens: BUDGET, reserveForResponse: 1000 });
+        assert.ok(compiledTokens(compiledAfterDoc) <= BUDGET - 1000, `after-doc tokens exceed budget: ${compiledTokens(compiledAfterDoc)}`);
+        // Now 50 chat turns about the doc
+        for (let i = 0; i < 50; i++) {
+            manager.addMessage('User', [{ type: 'text', text: `Question ${i} about section ${i % 12}: ` + 'word '.repeat(20) }]);
+            manager.addMessage('Claude', [{ type: 'text', text: `Answer ${i}: ` + 'word '.repeat(25) }]);
+            while (!manager.isReady()) {
+                await manager.tick();
+            }
+            const compiled = await manager.compile({ maxTokens: BUDGET, reserveForResponse: 1000 });
+            const tokens = compiledTokens(compiled);
+            assert.ok(tokens <= BUDGET - 1000, `turn ${i}: ${tokens} tokens exceeds budget ${BUDGET - 1000}`);
+        }
+        // The compiled output should still reflect the doc somewhere
+        const finalCompile = await manager.compile({ maxTokens: BUDGET, reserveForResponse: 1000 });
+        const finalText = finalCompile.messages
+            .flatMap((m) => m.content)
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text)
+            .join('\n');
+        // Either the doc is still raw-rendered, OR a summary referring to it appears
+        assert.ok(finalText.includes('Section') || finalText.includes('summary'), 'final compile should reference doc content via either raw or summary');
+        manager.close();
+    });
+    it('agent can lock a critical doc section and it survives folding pressure', async () => {
+        const mock = makeMockMembrane();
+        const strategy = new AutobiographicalStrategy({
+            adaptiveResolution: true,
+            targetChunkTokens: 500,
+            recentWindowTokens: 500,
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+            membrane: mock,
+        });
+        // Doc with distinct sections — big enough to shard at targetChunkTokens=500
+        // (chunker threshold = 2x targetChunkTokens = 1000 tokens; we need ~10 sections
+        // × 200 tokens = 2000+ tokens to trigger sharding).
+        const sections = Array.from({ length: 10 }, (_, i) => `# Section ${i}\n\nCRITICAL-MARKER-${i} ` + 'distinctive word here. '.repeat(40));
+        manager.addMessage('User', [{ type: 'text', text: sections.join('\n\n') }]);
+        const shards = manager.getAllMessages();
+        assert.ok(shards.length > 1, `doc should shard; got ${shards.length} messages`);
+        // Lock shard 3 specifically
+        const criticalShard = shards[3];
+        strategy.lockChunk(criticalShard.id);
+        // Add chat to push pressure
+        for (let i = 0; i < 30; i++) {
+            manager.addMessage('User', [{ type: 'text', text: `T${i}` }]);
+        }
+        while (!manager.isReady()) {
+            await manager.tick();
+        }
+        // Tight compile
+        const compiled = await manager.compile({ maxTokens: 3500, reserveForResponse: 500 });
+        // The locked shard's resolution should remain 0 in strategy.resolutions
+        const resolutions = strategy.resolutions;
+        const lockedRes = resolutions.get(criticalShard.id) ?? 0;
+        assert.equal(lockedRes, 0, `locked shard should remain L0, got L${lockedRes}`);
+        // The compiled output should contain the locked shard's content verbatim
+        // (or at least the CRITICAL-MARKER-3 substring from its raw text).
+        const allText = compiled.messages
+            .flatMap((m) => m.content)
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text)
+            .join('\n');
+        assert.ok(allText.includes('CRITICAL-MARKER-3'), 'compiled output should contain the locked shard\'s content verbatim');
+        manager.close();
+    });
+    it('doc + many turns: shards in different regions render correctly', async () => {
+        const mock = makeMockMembrane();
+        const strategy = new AutobiographicalStrategy({
+            adaptiveResolution: true,
+            targetChunkTokens: 400,
+            recentWindowTokens: 800,
+            mergeThreshold: 3,
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+            membrane: mock,
+        });
+        // Doc → some shards in middle, some in tail
+        const doc = Array.from({ length: 15 }, (_, i) => `Section ${i}: ` + 'word '.repeat(60)).join('\n\n');
+        manager.addMessage('User', [{ type: 'text', text: doc }]);
+        // Trailing chat so the doc isn't all-tail
+        for (let i = 0; i < 8; i++) {
+            manager.addMessage('User', [{ type: 'text', text: `Followup ${i}` }]);
+        }
+        while (!manager.isReady()) {
+            await manager.tick();
+        }
+        const compiled = await manager.compile({ maxTokens: 5000, reserveForResponse: 500 });
+        // The compile should have produced output containing both doc content
+        // (some sections) and chat content (followups). The doc should be a
+        // combined entry (or entries) representing its shards.
+        const userMessages = compiled.messages.filter((m) => m.participant.toLowerCase() === 'user');
+        assert.ok(userMessages.length >= 2, 'should have multiple user messages (doc + chat)');
+        // Find a user message containing "Section" (from the doc)
+        const docEntry = userMessages.find((m) => m.content
+            .filter((b) => b.type === 'text')
+            .some((b) => b.text.includes('Section ')));
+        assert.ok(docEntry, 'should have a user entry with doc section content');
+        // Find a user message containing "Followup" (from chat)
+        const chatEntry = userMessages.find((m) => m.content
+            .filter((b) => b.type === 'text')
+            .some((b) => b.text.includes('Followup')));
+        assert.ok(chatEntry, 'should have a user entry with chat followup content');
+        manager.close();
+    });
+});
+//# sourceMappingURL=doc-plus-chat.test.js.map

package/dist/test/adaptive/doc-plus-chat.test.js.map

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

package/dist/test/adaptive/hard-fail.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tests that selectAdaptive throws OverBudgetError when the picker has
+ * folded everything it can but the result still exceeds the hard budget.
+ *
+ * The strategy's philosophy: surface the overage rather than silently
+ * dropping entries. The host decides how to recover.
+ */
+export {};
+//# sourceMappingURL=hard-fail.test.d.ts.map

package/dist/test/adaptive/hard-fail.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hard-fail.test.d.ts","sourceRoot":"","sources":["../../../test/adaptive/hard-fail.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/test/adaptive/hard-fail.test.js

@@ -0,0 +1,154 @@
+/**
+ * Tests that selectAdaptive throws OverBudgetError when the picker has
+ * folded everything it can but the result still exceeds the hard budget.
+ *
+ * The strategy's philosophy: surface the overage rather than silently
+ * dropping entries. The host decides how to recover.
+ */
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { rmSync, existsSync } from 'node:fs';
+import { ContextManager, AutobiographicalStrategy } from '../../src/index.js';
+import { OverBudgetError } from '../../src/adaptive/index.js';
+const TEST_STORE_PATH = './test-adaptive-hard-fail-store';
+function cleanup() {
+    if (existsSync(TEST_STORE_PATH)) {
+        rmSync(TEST_STORE_PATH, { recursive: true, force: true });
+    }
+}
+function makeMockMembrane() {
+    let callCount = 0;
+    return {
+        complete: async () => {
+            callCount++;
+            return {
+                content: [{ type: 'text', text: `[mock summary #${callCount}]` }],
+            };
+        },
+        get callCount() {
+            return callCount;
+        },
+    };
+}
+describe('AutobiographicalStrategy — adaptive OverBudgetError', () => {
+    before(() => cleanup());
+    after(() => cleanup());
+    beforeEach(() => cleanup());
+    it('throws OverBudgetError when tail alone exceeds budget', async () => {
+        const mock = makeMockMembrane();
+        const strategy = new AutobiographicalStrategy({
+            adaptiveResolution: true,
+            targetChunkTokens: 200,
+            // Large tail window: everything we add will be tail-resident, NOT
+            // foldable. The picker has nothing to do with it.
+            recentWindowTokens: 100_000,
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+            membrane: mock,
+        });
+        // Add enough content that the tail alone is huge.
+        for (let i = 0; i < 30; i++) {
+            manager.addMessage('User', [{ type: 'text', text: `Msg ${i}. ` + 'word '.repeat(80) }]);
+        }
+        while (!manager.isReady()) {
+            await manager.tick();
+        }
+        // Budget so tight that even the tail can't fit. Picker has nothing it
+        // can fold (tail is treated as pinned).
+        await assert.rejects(() => manager.compile({ maxTokens: 500, reserveForResponse: 100 }), (err) => {
+            assert.ok(err instanceof OverBudgetError, `expected OverBudgetError, got ${err?.constructor?.name}`);
+            const e = err;
+            assert.ok(e.actual > e.budget, `actual ${e.actual} should exceed budget ${e.budget}`);
+            assert.ok(e.diagnostics.tailTokens > 0, 'diagnostics should include tail tokens');
+            return true;
+        });
+        manager.close();
+    });
+    it('does NOT throw when picker can fold its way under budget', async () => {
+        const mock = makeMockMembrane();
+        const strategy = new AutobiographicalStrategy({
+            adaptiveResolution: true,
+            targetChunkTokens: 100,
+            recentWindowTokens: 200,
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+            membrane: mock,
+        });
+        for (let i = 0; i < 30; i++) {
+            manager.addMessage('User', [{ type: 'text', text: `Msg ${i}. ` + 'word '.repeat(40) }]);
+        }
+        while (!manager.isReady()) {
+            await manager.tick();
+        }
+        // Tight but reachable budget — picker should fold middle content to fit.
+        const compiled = await manager.compile({ maxTokens: 3000, reserveForResponse: 200 });
+        assert.ok(compiled.messages.length > 0);
+        manager.close();
+    });
+    it('does NOT throw under generous budget', async () => {
+        const mock = makeMockMembrane();
+        const strategy = new AutobiographicalStrategy({
+            adaptiveResolution: true,
+            targetChunkTokens: 100,
+            recentWindowTokens: 200,
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+            membrane: mock,
+        });
+        for (let i = 0; i < 10; i++) {
+            manager.addMessage('User', [{ type: 'text', text: `Msg ${i}` }]);
+        }
+        const compiled = await manager.compile({ maxTokens: 100_000, reserveForResponse: 200 });
+        assert.ok(compiled.messages.length > 0);
+        manager.close();
+    });
+    it('error diagnostics include useful state info', async () => {
+        const mock = makeMockMembrane();
+        const strategy = new AutobiographicalStrategy({
+            adaptiveResolution: true,
+            targetChunkTokens: 200,
+            recentWindowTokens: 100_000,
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+            membrane: mock,
+        });
+        for (let i = 0; i < 20; i++) {
+            manager.addMessage('User', [{ type: 'text', text: `Msg ${i}. ` + 'word '.repeat(80) }]);
+        }
+        while (!manager.isReady()) {
+            await manager.tick();
+        }
+        let caught = null;
+        try {
+            await manager.compile({ maxTokens: 400, reserveForResponse: 100 });
+        }
+        catch (err) {
+            if (err instanceof OverBudgetError)
+                caught = err;
+        }
+        assert.ok(caught, 'should have caught OverBudgetError');
+        if (!caught) {
+            manager.close();
+            return;
+        }
+        assert.equal(typeof caught.budget, 'number');
+        assert.equal(typeof caught.actual, 'number');
+        assert.equal(typeof caught.diagnostics.headTokens, 'number');
+        assert.equal(typeof caught.diagnostics.tailTokens, 'number');
+        assert.equal(typeof caught.diagnostics.middleTokens, 'number');
+        assert.equal(typeof caught.diagnostics.deepestLevel, 'number');
+        // The error message should be informative
+        assert.ok(caught.message.includes('exhausted'));
+        assert.ok(caught.message.includes('hard budget'));
+        manager.close();
+    });
+});
+//# sourceMappingURL=hard-fail.test.js.map

package/dist/test/adaptive/hard-fail.test.js.map

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

package/dist/test/adaptive/harness.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Synthetic test harness for the adaptive-resolution picker.
+ *
+ * Builds a minimal in-memory chronicle simulator with:
+ *  - Chunks (PickerChunk shape) with deterministic token counts.
+ *  - A mocked LLM that produces deterministic "summaries" by hashing input.
+ *  - A summary tree that grows as the LLM is called.
+ *  - A function to run the picker against a built state.
+ *
+ * The mock LLM doesn't actually call any API — it constructs fake summary
+ * content so we can validate picker logic, fold semantics, and cache stickiness
+ * without external dependencies.
+ */
+import type { SummaryEntry } from '../../src/types/strategy.js';
+import type { PickerChunk } from '../../src/adaptive/picker.js';
+import type { ChunkId, SummaryId } from '../../src/adaptive/folding-strategy.js';
+/**
+ * Default tokens per recall pair, regardless of source level.
+ * The design specifies that L_k summaries target a constant size (~2K tokens
+ * by convention) so each level's recall pair has predictable footprint.
+ */
+export declare const DEFAULT_RECALL_PAIR_TOKENS = 200;
+/** Default group size: how many L_k items combine into one L_{k+1}. */
+export declare const DEFAULT_MERGE_THRESHOLD = 6;
+export interface MockChronicleOptions {
+    /** Tokens for each recall pair. */
+    recallPairTokens?: number;
+    /** L_k items per L_{k+1} parent. */
+    mergeThreshold?: number;
+}
+/**
+ * Mutable in-memory chronicle. Mirrors what the real strategy would manage
+ * but trimmed to just what the picker needs.
+ */
+export declare class MockChronicle {
+    readonly chunks: PickerChunk[];
+    readonly summaries: Map<string, SummaryEntry>;
+    readonly recallPairTokens: Map<string, number>;
+    private summaryCounter;
+    readonly mergeThreshold: number;
+    readonly defaultRecallPairTokens: number;
+    /** Mock LLM call count, for telemetry assertions. */
+    llmCalls: number;
+    constructor(opts?: MockChronicleOptions);
+    /**
+     * Add a chunk to the chronicle (e.g., a chat message or a doc shard).
+     *
+     * @returns the created PickerChunk
+     */
+    addChunk(opts: {
+        id: ChunkId;
+        rawTokens: number;
+        bodyGroupId?: string;
+        pinned?: boolean;
+        lockedByAgent?: boolean;
+    }): PickerChunk;
+    /**
+     * Produce an L1 summary for a range of chunks. Mocks the LLM call.
+     * Idempotent: the same chunk range produces the same summary id.
+     *
+     * @returns the produced SummaryEntry (or the existing one if already produced)
+     */
+    produceL1(chunkIds: ChunkId[]): SummaryEntry;
+    /**
+     * Produce an L_{k+1} summary from N L_k summaries.
+     */
+    produceUpper(level: number, sourceSummaryIds: SummaryId[]): SummaryEntry;
+    /**
+     * Speculative pre-producer: when N siblings exist sharing the same potential
+     * parent at level k+1, eagerly produce L_{k+1}. Bottom-up, idempotent.
+     * Mirrors the design's background pre-producer (§7 #2 settled decisions).
+     */
+    preProduceUpperLevels(): void;
+    /**
+     * Build a head/tail bookkeeping from chunk indices.
+     */
+    computeHeadTail(opts: {
+        headTokens: number;
+        tailTokens: number;
+    }): {
+        headTokens: number;
+        tailTokens: number;
+        headChunkIds: Set<ChunkId>;
+        tailChunkIds: Set<ChunkId>;
+    };
+    /**
+     * Apply a snapshot of resolutions back onto the chunks (used after running
+     * the picker to commit the new state for subsequent turns).
+     */
+    applyResolutions(resolutions: ReadonlyMap<ChunkId, number>): void;
+    private linkChunksToL1;
+    private allocSummaryId;
+    private firstChunkSeq;
+    private sumTokens;
+}
+/**
+ * Convenience: build N chunks with uniform token size, then auto-produce
+ * the full summary chain (L1, L2, …) bottom-up via the mergeThreshold rule.
+ *
+ * Returns the populated MockChronicle.
+ */
+export declare function buildChronicleWithChain(opts: {
+    chunkCount: number;
+    tokensPerChunk: number;
+    mergeThreshold?: number;
+    recallPairTokens?: number;
+    produceChain?: boolean;
+}): MockChronicle;
+//# sourceMappingURL=harness.d.ts.map

package/dist/test/adaptive/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../../../test/adaptive/harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,wCAAwC,CAAC;AAEjF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C,uEAAuE;AACvE,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oCAAoC;IACpC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,CAAM;IACpC,QAAQ,CAAC,SAAS,4BAAsC;IACxD,QAAQ,CAAC,gBAAgB,sBAAgC;IACzD,OAAO,CAAC,cAAc,CAA6B;IAEnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IAEzC,qDAAqD;IACrD,QAAQ,SAAK;gBAED,IAAI,GAAE,oBAAyB;IAK3C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE;QACb,EAAE,EAAE,OAAO,CAAC;QACZ,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,GAAG,WAAW;IAcf;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,YAAY;IA2B5C;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAE,GAAG,YAAY;IA2CxE;;;;OAIG;IACH,qBAAqB,IAAI,IAAI;IA8B7B;;OAEG;IACH,eAAe,CAAC,IAAI,EAAE;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG;QACF,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3B,YAAY,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;KAC5B;IA4BD;;;OAGG;IACH,gBAAgB,CAAC,WAAW,EAAE,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,IAAI;IASjE,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,SAAS;CAKlB;AAMD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,aAAa,CAmBhB"}