@animalabs/context-manager 0.3.0 → 0.5.0

package/dist/test/recall-positioning.test.js

@@ -0,0 +1,181 @@
+/**
+ * Tests for per-region recall pair emission (audit gap #2).
+ *
+ * Pre-fix, AutobiographicalStrategy concatenated ALL selected summaries with
+ * `\n\n---\n\n` separators into ONE Q/A pair placed between the head window
+ * and the recent window. Per the spec audit, this is the structural
+ * equivalent of Lena's dual-recall corruption pattern from Hermes: the agent
+ * sees memories as a wall of summaries from another speaker, with no
+ * positional or temporal coherence per individual summary.
+ *
+ * Post-fix, each selected summary emits as its own Q/A recall pair, sorted
+ * chronologically by source-range position. The legacy combined-pair shape
+ * is still available via `positionedRecallPairs: false`.
+ */
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert';
+import { rmSync, existsSync } from 'node:fs';
+import { ContextManager, AutobiographicalStrategy } from '../src/index.js';
+const TEST_STORE_PATH = './test-recall-positioning';
+function cleanup() {
+    if (existsSync(TEST_STORE_PATH)) {
+        rmSync(TEST_STORE_PATH, { recursive: true, force: true });
+    }
+}
+function textBlock(text) {
+    return [{ type: 'text', text }];
+}
+class TestableStrategy extends AutobiographicalStrategy {
+    /** Seed an L1 against a specific source-message id. */
+    seedL1Against(content, firstMsgId, lastMsgId) {
+        const entry = {
+            id: `L1-${this.nextSummaryIdCounter()}`,
+            level: 1,
+            content,
+            tokens: Math.ceil(content.length / 4),
+            sourceLevel: 0,
+            sourceIds: [firstMsgId, lastMsgId],
+            sourceRange: { first: firstMsgId, last: lastMsgId },
+            created: Date.now(),
+        };
+        this.pushSummary(entry);
+        return entry;
+    }
+}
+function recallEntries(messages) {
+    const pairs = [];
+    for (let i = 0; i < messages.length - 1; i++) {
+        const a = messages[i];
+        const b = messages[i + 1];
+        if (a.participant === 'Context Manager') {
+            const q = a.content.map(c => (c.type === 'text' ? c.text : '')).join('');
+            const ans = b.content.map(c => (c.type === 'text' ? c.text : '')).join('');
+            pairs.push({ q, a: ans });
+        }
+    }
+    return pairs;
+}
+describe('AutobiographicalStrategy — per-region recall pairs (gap #2)', () => {
+    before(cleanup);
+    after(cleanup);
+    beforeEach(cleanup);
+    it('emits one Q/A pair per selected summary, in chronological order', async () => {
+        // recentWindowTokens deliberately small so the three "old" messages we
+        // seed summaries against fall OUTSIDE the recent window — otherwise
+        // anti-redundancy (correctly) hides summaries about messages that are
+        // already shown verbatim in the recent window.
+        const strategy = new TestableStrategy({
+            headWindowTokens: 0,
+            recentWindowTokens: 8,
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+        });
+        // Three "old" messages whose summaries we'll test, plus one message
+        // big enough to dominate the recent window so the older three fall out.
+        const m1 = manager.addMessage('user', textBlock('first'));
+        const m2 = manager.addMessage('user', textBlock('second'));
+        const m3 = manager.addMessage('user', textBlock('third'));
+        manager.addMessage('user', textBlock('latest message ' + 'X'.repeat(50)));
+        // Seed three summaries. Seed in the *opposite* order from chronological
+        // so we can verify the strategy sorts them by source position rather
+        // than by creation order.
+        strategy.seedL1Against('summary about THIRD', m3, m3);
+        strategy.seedL1Against('summary about FIRST', m1, m1);
+        strategy.seedL1Against('summary about SECOND', m2, m2);
+        const compiled = await manager.compile({ maxTokens: 100_000, reserveForResponse: 0 });
+        const pairs = recallEntries(compiled.messages);
+        assert.equal(pairs.length, 3, 'should emit 3 distinct recall pairs');
+        // Order should follow source position (m1 < m2 < m3), not seed order.
+        assert.match(pairs[0].a, /FIRST/, 'first pair must cover m1');
+        assert.match(pairs[1].a, /SECOND/, 'second pair must cover m2');
+        assert.match(pairs[2].a, /THIRD/, 'third pair must cover m3');
+        // No --- separators (the legacy concat-marker should be gone).
+        for (const p of pairs) {
+            assert.ok(!p.a.includes('---'), `pair ${p.q} unexpectedly contains '---' separator`);
+        }
+        manager.close();
+    });
+    it('renders the recall header template with summary id by default', async () => {
+        const strategy = new TestableStrategy({
+            headWindowTokens: 0,
+            recentWindowTokens: 8,
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+        });
+        const m1 = manager.addMessage('user', textBlock('foo'));
+        manager.addMessage('user', textBlock('latest ' + 'X'.repeat(50)));
+        const seeded = strategy.seedL1Against('content', m1, m1);
+        const compiled = await manager.compile({ maxTokens: 100_000, reserveForResponse: 0 });
+        const pairs = recallEntries(compiled.messages);
+        assert.equal(pairs.length, 1);
+        assert.equal(pairs[0].q, `[Recall ${seeded.id}]`, 'default template should be [Recall {id}]');
+    });
+    it('honors a custom recall header template with all substitutions', async () => {
+        const strategy = new TestableStrategy({
+            headWindowTokens: 0,
+            recentWindowTokens: 8,
+            recallHeaderTemplate: 'memory {id} (L{level}) covering {first}..{last}',
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+        });
+        const m1 = manager.addMessage('user', textBlock('foo'));
+        const m2 = manager.addMessage('user', textBlock('bar'));
+        manager.addMessage('user', textBlock('latest ' + 'X'.repeat(50)));
+        const seeded = strategy.seedL1Against('content', m1, m2);
+        const compiled = await manager.compile({ maxTokens: 100_000, reserveForResponse: 0 });
+        const pairs = recallEntries(compiled.messages);
+        assert.equal(pairs[0].q, `memory ${seeded.id} (L1) covering ${m1}..${m2}`);
+    });
+    it('reverts to combined single-pair shape when positionedRecallPairs is false', async () => {
+        const strategy = new TestableStrategy({
+            headWindowTokens: 0,
+            recentWindowTokens: 8,
+            positionedRecallPairs: false,
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+        });
+        const m1 = manager.addMessage('user', textBlock('a'));
+        const m2 = manager.addMessage('user', textBlock('b'));
+        const m3 = manager.addMessage('user', textBlock('c'));
+        manager.addMessage('user', textBlock('latest ' + 'X'.repeat(50)));
+        strategy.seedL1Against('A', m1, m1);
+        strategy.seedL1Against('B', m2, m2);
+        strategy.seedL1Against('C', m3, m3);
+        const compiled = await manager.compile({ maxTokens: 100_000, reserveForResponse: 0 });
+        const pairs = recallEntries(compiled.messages);
+        assert.equal(pairs.length, 1, 'legacy mode should emit a single combined pair');
+        assert.equal(pairs[0].q, 'What do you remember from earlier?');
+        assert.match(pairs[0].a, /A\n\n---\n\nB\n\n---\n\nC/);
+    });
+    it('stops emitting pairs when overall budget would be exceeded', async () => {
+        const strategy = new TestableStrategy({
+            headWindowTokens: 0,
+            recentWindowTokens: 8,
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+        });
+        const m1 = manager.addMessage('user', textBlock('a'));
+        const m2 = manager.addMessage('user', textBlock('b'));
+        const m3 = manager.addMessage('user', textBlock('c'));
+        manager.addMessage('user', textBlock('latest ' + 'X'.repeat(50)));
+        // Each summary is ~400 chars (~100 tokens). Three pairs ≈ 300+ tokens of recall.
+        const big = 'X'.repeat(400);
+        strategy.seedL1Against(big + ' first', m1, m1);
+        strategy.seedL1Against(big + ' second', m2, m2);
+        strategy.seedL1Against(big + ' third', m3, m3);
+        const compiled = await manager.compile({ maxTokens: 250, reserveForResponse: 0 });
+        const pairs = recallEntries(compiled.messages);
+        assert.ok(pairs.length > 0 && pairs.length < 3, `expected partial recall emission under tight budget, got ${pairs.length}`);
+    });
+});
+//# sourceMappingURL=recall-positioning.test.js.map

package/dist/test/recall-positioning.test.js.map

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

package/dist/test/search.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tests for the search API (audit gap #7).
+ *
+ * Substring + regex search over summary content, plus single-summary
+ * lookup by id. Exposed through ContextManager passthrough so callers
+ * (e.g. agent-framework MCPL host) can build `memory_search` /
+ * `memory_read` agent tools on top.
+ */
+export {};
+//# sourceMappingURL=search.test.d.ts.map

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

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

package/dist/test/search.test.js

@@ -0,0 +1,141 @@
+/**
+ * Tests for the search API (audit gap #7).
+ *
+ * Substring + regex search over summary content, plus single-summary
+ * lookup by id. Exposed through ContextManager passthrough so callers
+ * (e.g. agent-framework MCPL host) can build `memory_search` /
+ * `memory_read` agent tools on top.
+ */
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert';
+import { rmSync, existsSync } from 'node:fs';
+import { ContextManager, AutobiographicalStrategy } from '../src/index.js';
+const TEST_STORE_PATH = './test-search';
+function cleanup() {
+    if (existsSync(TEST_STORE_PATH)) {
+        rmSync(TEST_STORE_PATH, { recursive: true, force: true });
+    }
+}
+function textBlock(text) {
+    return [{ type: 'text', text }];
+}
+class SeedableStrategy extends AutobiographicalStrategy {
+    seedSummary(content, level = 1, mergedInto) {
+        const entry = {
+            id: `L${level}-${this.nextSummaryIdCounter()}`,
+            level,
+            content,
+            tokens: Math.ceil(content.length / 4),
+            sourceLevel: 0,
+            sourceIds: ['x'],
+            sourceRange: { first: 'x', last: 'x' },
+            created: Date.now(),
+            ...(mergedInto ? { mergedInto } : {}),
+        };
+        this.pushSummary(entry);
+        return entry;
+    }
+}
+describe('AutobiographicalStrategy — search (gap #7)', () => {
+    before(cleanup);
+    after(cleanup);
+    beforeEach(cleanup);
+    it('returns empty when no summaries match the substring', async () => {
+        const strategy = new SeedableStrategy();
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+        });
+        strategy.seedSummary('first memory about cats');
+        strategy.seedSummary('second memory about dogs');
+        const results = manager.searchSummaries({ text: 'unicorns' });
+        assert.equal(results.length, 0);
+        manager.close();
+    });
+    it('case-insensitive substring search returns matches sorted by hit count', async () => {
+        const strategy = new SeedableStrategy();
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+        });
+        strategy.seedSummary('a meditation on cats and CATS and cats'); // 3 hits
+        strategy.seedSummary('one note about Cats'); // 1 hit
+        strategy.seedSummary('something about dogs'); // 0 hits
+        const results = manager.searchSummaries({ text: 'cats' });
+        assert.equal(results.length, 2, 'two summaries should match');
+        assert.equal(results[0].matches, 3, 'highest hit count first');
+        assert.equal(results[1].matches, 1);
+        manager.close();
+    });
+    it('regex search supports patterns and counts global matches', async () => {
+        const strategy = new SeedableStrategy();
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+        });
+        strategy.seedSummary('found errors at 14:23 and 16:45 and 18:00');
+        strategy.seedSummary('no times here');
+        const results = manager.searchSummaries({ regex: /\d{2}:\d{2}/ });
+        assert.equal(results.length, 1);
+        assert.equal(results[0].matches, 3, 'should count all 3 timestamps');
+        manager.close();
+    });
+    it('level filter restricts to chosen levels', async () => {
+        const strategy = new SeedableStrategy();
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+        });
+        strategy.seedSummary('shared word here', 1);
+        strategy.seedSummary('shared word also', 2);
+        strategy.seedSummary('shared word too', 3);
+        const l2only = manager.searchSummaries({ text: 'shared', levels: [2] });
+        assert.equal(l2only.length, 1);
+        assert.equal(l2only[0].summary.level, 2);
+        const l1andL3 = manager.searchSummaries({ text: 'shared', levels: [1, 3] });
+        assert.equal(l1andL3.length, 2);
+        assert.ok(l1andL3.every(r => r.summary.level === 1 || r.summary.level === 3));
+        manager.close();
+    });
+    it('excludes merged summaries by default; includeMerged opts in', async () => {
+        const strategy = new SeedableStrategy();
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+        });
+        strategy.seedSummary('alive content', 1);
+        strategy.seedSummary('folded content', 1, 'L2-99'); // already merged
+        const live = manager.searchSummaries({ text: 'content' });
+        assert.equal(live.length, 1, 'merged summaries hidden by default');
+        assert.equal(live[0].summary.content, 'alive content');
+        const all = manager.searchSummaries({ text: 'content', includeMerged: true });
+        assert.equal(all.length, 2, 'includeMerged should reveal both');
+        manager.close();
+    });
+    it('limit caps the result count', async () => {
+        const strategy = new SeedableStrategy();
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+        });
+        for (let i = 0; i < 10; i++) {
+            strategy.seedSummary(`hit ${i} hit hit`);
+        }
+        const results = manager.searchSummaries({ text: 'hit', limit: 3 });
+        assert.equal(results.length, 3);
+    });
+    it('getSummary returns an entry by id', async () => {
+        const strategy = new SeedableStrategy();
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+        });
+        const seeded = strategy.seedSummary('lookup me');
+        const got = manager.getSummary(seeded.id);
+        assert.ok(got, 'should find the seeded summary');
+        assert.equal(got?.content, 'lookup me');
+        assert.equal(manager.getSummary('nonexistent'), null);
+        manager.close();
+    });
+});
+//# sourceMappingURL=search.test.js.map

package/dist/test/search.test.js.map

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

package/dist/test/speculation-cap.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tests for speculation cap + preflight hook (audit gap #8).
+ *
+ * Pre-fix: every new message triggered an auto-tick that compressed any
+ * pending chunk, regardless of how many speculative L1s the strategy was
+ * already holding. Lena's archive on Hermes ended up with dozens of
+ * speculatively-built L1s before there was any real budget pressure.
+ *
+ * Post-fix:
+ *  - `maxSpeculativeL1s` caps the count of (unmerged L1s + queued chunks).
+ *    When at cap, `onNewMessage` defers auto-tick — chunks still queue,
+ *    but compression doesn't fire until an explicit tick() / compile().
+ *  - `shouldCompressPreflight()` is overridable so subclasses can add
+ *    custom predictive scheduling.
+ */
+export {};
+//# sourceMappingURL=speculation-cap.test.d.ts.map

package/dist/test/speculation-cap.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speculation-cap.test.d.ts","sourceRoot":"","sources":["../../test/speculation-cap.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/test/speculation-cap.test.js

@@ -0,0 +1,157 @@
+/**
+ * Tests for speculation cap + preflight hook (audit gap #8).
+ *
+ * Pre-fix: every new message triggered an auto-tick that compressed any
+ * pending chunk, regardless of how many speculative L1s the strategy was
+ * already holding. Lena's archive on Hermes ended up with dozens of
+ * speculatively-built L1s before there was any real budget pressure.
+ *
+ * Post-fix:
+ *  - `maxSpeculativeL1s` caps the count of (unmerged L1s + queued chunks).
+ *    When at cap, `onNewMessage` defers auto-tick — chunks still queue,
+ *    but compression doesn't fire until an explicit tick() / compile().
+ *  - `shouldCompressPreflight()` is overridable so subclasses can add
+ *    custom predictive scheduling.
+ */
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert';
+import { rmSync, existsSync } from 'node:fs';
+import { ContextManager, AutobiographicalStrategy } from '../src/index.js';
+const TEST_STORE_PATH = './test-speculation-cap';
+function cleanup() {
+    if (existsSync(TEST_STORE_PATH)) {
+        rmSync(TEST_STORE_PATH, { recursive: true, force: true });
+    }
+}
+function textBlock(text) {
+    return [{ type: 'text', text }];
+}
+class TickCountingStrategy extends AutobiographicalStrategy {
+    tickCalls = 0;
+    async tick(ctx) {
+        this.tickCalls++;
+        // Do NOT call super.tick — we don't have a real membrane in tests
+        // and we just want to count whether onNewMessage decided to fire.
+    }
+    seedL1(content) {
+        const entry = {
+            id: `L1-${this.nextSummaryIdCounter()}`,
+            level: 1,
+            content,
+            tokens: Math.ceil(content.length / 4),
+            sourceLevel: 0,
+            sourceIds: ['x'],
+            sourceRange: { first: 'x', last: 'x' },
+            created: Date.now(),
+        };
+        this.pushSummary(entry);
+        return entry;
+    }
+    /** True if there's an unprocessed chunk eligible for compression. */
+    hasQueuedChunk() {
+        return this.compressionQueue.length > 0;
+    }
+}
+/**
+ * Add enough small messages to force ≥1 chunk to form in the
+ * compressible region. With targetChunkTokens=20 and chunkOnMessageBoundary,
+ * 5 messages of ~6 tokens each will close one chunk after 4 msgs.
+ */
+async function setupWithQueuedChunk(strategy) {
+    const manager = await ContextManager.open({
+        path: TEST_STORE_PATH,
+        strategy,
+    });
+    // recentWindowTokens=5 (small) means only the latest message stays in recent;
+    // the rest are compressible and will form chunks once we hit targetChunkTokens.
+    // 5 padding messages of ~6 tokens, plus one trailing recent message.
+    for (let i = 0; i < 5; i++) {
+        manager.addMessage('user', textBlock(`m-${i} hello world`));
+    }
+    manager.addMessage('user', textBlock('latest one ' + 'X'.repeat(20)));
+    // Wait for any onNewMessage handlers to settle
+    await new Promise(r => setTimeout(r, 30));
+    return manager;
+}
+describe('AutobiographicalStrategy — speculation cap (gap #8)', () => {
+    before(cleanup);
+    after(cleanup);
+    beforeEach(cleanup);
+    it('default: auto-tick fires whenever a chunk is queued', async () => {
+        const strategy = new TickCountingStrategy({
+            headWindowTokens: 0,
+            recentWindowTokens: 5,
+            targetChunkTokens: 20,
+            autoTickOnNewMessage: true,
+        });
+        const manager = await setupWithQueuedChunk(strategy);
+        assert.ok(strategy.hasQueuedChunk(), 'sanity: chunk should have formed in compressible region');
+        assert.ok(strategy.tickCalls >= 1, `default behavior must auto-tick (got ${strategy.tickCalls})`);
+        manager.close();
+    });
+    it('with maxSpeculativeL1s, auto-tick is deferred when at cap', async () => {
+        const strategy = new TickCountingStrategy({
+            headWindowTokens: 0,
+            recentWindowTokens: 5,
+            targetChunkTokens: 20,
+            autoTickOnNewMessage: true,
+            maxSpeculativeL1s: 2,
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+        });
+        // Seed AFTER open so initialize() doesn't wipe the seeds.
+        strategy.seedL1('summary 1');
+        strategy.seedL1('summary 2');
+        strategy.seedL1('summary 3');
+        const ticksBefore = strategy.tickCalls;
+        for (let i = 0; i < 5; i++) {
+            manager.addMessage('user', textBlock(`m-${i} hello world`));
+        }
+        manager.addMessage('user', textBlock('latest one ' + 'X'.repeat(20)));
+        await new Promise(r => setTimeout(r, 30));
+        assert.ok(strategy.hasQueuedChunk(), 'sanity: chunk formed');
+        assert.equal(strategy.tickCalls, ticksBefore, 'auto-tick must NOT fire when unmerged L1s already exceed maxSpeculativeL1s');
+        manager.close();
+    });
+    it('cap allows auto-tick when count is under the limit', async () => {
+        const strategy = new TickCountingStrategy({
+            headWindowTokens: 0,
+            recentWindowTokens: 5,
+            targetChunkTokens: 20,
+            autoTickOnNewMessage: true,
+            maxSpeculativeL1s: 5,
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+        });
+        strategy.seedL1('summary 1');
+        const ticksBefore = strategy.tickCalls;
+        for (let i = 0; i < 5; i++) {
+            manager.addMessage('user', textBlock(`m-${i} hello world`));
+        }
+        manager.addMessage('user', textBlock('latest one ' + 'X'.repeat(20)));
+        await new Promise(r => setTimeout(r, 30));
+        assert.ok(strategy.hasQueuedChunk(), 'sanity: chunk formed');
+        assert.ok(strategy.tickCalls > ticksBefore, 'auto-tick should fire when under cap');
+        manager.close();
+    });
+    it('shouldCompressPreflight=false defers auto-tick', async () => {
+        class DeferAlways extends TickCountingStrategy {
+            shouldCompressPreflight() { return false; }
+        }
+        const strategy = new DeferAlways({
+            headWindowTokens: 0,
+            recentWindowTokens: 5,
+            targetChunkTokens: 20,
+            autoTickOnNewMessage: true,
+        });
+        const manager = await setupWithQueuedChunk(strategy);
+        assert.ok(strategy.hasQueuedChunk(), 'sanity: chunk formed');
+        assert.equal(strategy.tickCalls, 0, 'preflight=false must block auto-tick');
+        manager.close();
+    });
+});
+//# sourceMappingURL=speculation-cap.test.js.map

package/dist/test/speculation-cap.test.js.map

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

package/dist/test/strategy-persistence.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tests for AutobiographicalStrategy persistence + branch fork.
+ *
+ * Strategy state (summaries, summaryIdCounter, mergeQueue) was previously
+ * in-memory only — first process restart wiped the entire L1/L2/L3 pyramid.
+ * Forking the underlying chronicle branch silently shared state across
+ * branches because nothing was actually branch-scoped.
+ *
+ * These tests cover:
+ *  1. restart-and-resume: state survives close/reopen of the same path.
+ *  2. branch fork: a forked branch has its own summary timeline.
+ *  3. branch switch: switching back picks up the right branch's state.
+ */
+export {};
+//# sourceMappingURL=strategy-persistence.test.d.ts.map

package/dist/test/strategy-persistence.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy-persistence.test.d.ts","sourceRoot":"","sources":["../../test/strategy-persistence.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}