@fgv/ts-agent-memory 5.1.0-36

package/dist/test/unit/store/fileTreeMemoryStore.test.js

@@ -0,0 +1,647 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+import '@fgv/ts-utils-jest';
+import { Converters, Logging, fail, succeed } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
+import { BodyConverterRegistry, Convert, FileTreeMemoryStore, KnowledgeIdentityCodec, LtmIdentityCodec, MemoryCapCullPolicy, MtmIdentityCodec, envelopeConverter, joinFrontmatter } from '../../../index';
+const knowledgeKind = 'knowledge';
+/** Build a record whose envelope fields are validated through the B0 converter. */
+function makeRecord(spec) {
+    var _a, _b, _c, _d, _e;
+    return {
+        envelope: envelopeConverter
+            .convert({
+            id: spec.id,
+            entityId: (_a = spec.entityId) !== null && _a !== void 0 ? _a : spec.id,
+            kind: (_b = spec.kind) !== null && _b !== void 0 ? _b : 'knowledge',
+            tags: (_c = spec.tags) !== null && _c !== void 0 ? _c : [],
+            links: (_d = spec.links) !== null && _d !== void 0 ? _d : [],
+            created: 0,
+            updated: 0,
+            seq: 0,
+            contentHash: '',
+            provenance: { source: 'agent' }
+        })
+            .orThrow(),
+        body: (_e = spec.body) !== null && _e !== void 0 ? _e : `body for ${spec.id}`
+    };
+}
+/** A mutable in-memory root, optionally seeded with raw files. */
+function mutableRoot(files = []) {
+    const tree = FileTree.inMemory([...files], { mutable: true }).orThrow();
+    const root = tree.getDirectory('/').orThrow();
+    if (!FileTree.isMutableDirectoryItem(root)) {
+        throw new Error('expected a mutable root directory');
+    }
+    return root;
+}
+function knowledgeRegistry(bodyConverter = Converters.string) {
+    const registry = BodyConverterRegistry.create().orThrow();
+    registry.register(knowledgeKind, bodyConverter);
+    return registry;
+}
+const knowledgeCodecs = new Map([
+    [knowledgeKind, new KnowledgeIdentityCodec()]
+]);
+/** A serialized knowledge file for seeding a vault. */
+function knowledgeFile(id, body, overrides = {}) {
+    const envelope = Object.assign({ id, entityId: id, kind: 'knowledge', tags: [], links: [], created: 1, updated: 1, seq: 5, contentHash: 'seed', provenance: { source: 'agent' } }, overrides);
+    const frontmatter = Object.entries(envelope)
+        .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+        .join('\n');
+    return joinFrontmatter(frontmatter, body);
+}
+describe('FileTreeMemoryStore', () => {
+    let clockValue;
+    const clock = () => clockValue;
+    function createStore(params = {}) {
+        var _a, _b, _c;
+        return FileTreeMemoryStore.create({
+            root: (_a = params.root) !== null && _a !== void 0 ? _a : mutableRoot(),
+            registry: (_b = params.registry) !== null && _b !== void 0 ? _b : knowledgeRegistry(),
+            codecs: (_c = params.codecs) !== null && _c !== void 0 ? _c : knowledgeCodecs,
+            defaultCodec: params.defaultCodec,
+            writePolicies: params.writePolicies,
+            clock
+        });
+    }
+    beforeEach(() => {
+        clockValue = 1000;
+    });
+    describe('create', () => {
+        test('starts from an empty vault', async () => {
+            const store = createStore().orThrow();
+            expect(await store.list()).toSucceedWith([]);
+        });
+        test('indexes a pre-existing vault and resumes seq past the highest persisted seq', async () => {
+            const root = mutableRoot([
+                { path: 'knowledge/doc-a.md', contents: knowledgeFile('doc-a', 'A', { seq: 7 }) },
+                { path: 'knowledge/doc-b.md', contents: knowledgeFile('doc-b', 'B', { seq: 3 }) },
+                { path: 'knowledge/notes.txt', contents: 'not a record' },
+                { path: 'top-level.md', contents: 'ignored at root' }
+            ]);
+            const store = createStore({ root }).orThrow();
+            expect(await store.list()).toSucceedAndSatisfy((listed) => {
+                expect(listed.map((r) => r.envelope.id).sort()).toEqual(['doc-a', 'doc-b']);
+            });
+            // The next put must get seq 8 (highest persisted was 7).
+            expect(await store.put(makeRecord({ id: 'doc-c' }))).toSucceedAndSatisfy((put) => {
+                expect(put.envelope.seq).toBe(8);
+            });
+        });
+        test('fails loudly when a seeded file id does not match its filename', () => {
+            const root = mutableRoot([{ path: 'knowledge/real.md', contents: knowledgeFile('wrong', 'body') }]);
+            expect(createStore({ root })).toFailWith(/does not match filename stem/i);
+        });
+        test('fails loudly when a seeded file violates the codec round-trip (wrong scope)', () => {
+            const root = mutableRoot([{ path: 'elsewhere/doc.md', contents: knowledgeFile('doc', 'body') }]);
+            expect(createStore({ root })).toFailWith(/does not match expected scope/i);
+        });
+    });
+    describe('factory defaults', () => {
+        test('falls back to default codecs/policies/scope-encoding/clock when omitted', async () => {
+            const store = FileTreeMemoryStore.create({
+                root: mutableRoot(),
+                registry: knowledgeRegistry(),
+                defaultCodec: new KnowledgeIdentityCodec()
+            }).orThrow();
+            expect(await store.put(makeRecord({ id: 'x', body: 'y' }))).toSucceedAndSatisfy((record) => {
+                expect(record.envelope.id).toBe('x');
+                // The default clock (Date.now) stamps a real epoch.
+                expect(record.envelope.created).toBeGreaterThan(0);
+            });
+        });
+        test('uses a custom scope encoding when provided', async () => {
+            const store = FileTreeMemoryStore.create({
+                root: mutableRoot(),
+                registry: knowledgeRegistry(),
+                codecs: knowledgeCodecs,
+                scopeEncoding: (scope) => succeed(scope),
+                clock
+            }).orThrow();
+            await store.put(makeRecord({ id: 'x', body: 'y' }));
+            expect(await store.get(knowledgeKind, 'x')).toSucceedAndSatisfy((record) => {
+                expect(record === null || record === void 0 ? void 0 : record.body).toBe('y');
+            });
+        });
+    });
+    describe('put / get round-trip', () => {
+        test('first write stamps created/updated/seq/contentHash and is retrievable', async () => {
+            const store = createStore().orThrow();
+            expect(await store.put(makeRecord({ id: 'intro', body: 'hello' }))).toSucceedAndSatisfy((put) => {
+                expect(put.envelope.created).toBe(1000);
+                expect(put.envelope.updated).toBe(1000);
+                expect(put.envelope.seq).toBe(1);
+                expect(put.envelope.contentHash).not.toBe('');
+            });
+            expect(await store.get(knowledgeKind, 'intro')).toSucceedAndSatisfy((record) => {
+                expect(record === null || record === void 0 ? void 0 : record.body).toBe('hello');
+                expect(record === null || record === void 0 ? void 0 : record.envelope.id).toBe('intro');
+            });
+        });
+        test('get returns undefined for a missing entity', async () => {
+            const store = createStore().orThrow();
+            expect(await store.get(knowledgeKind, 'absent')).toSucceedWith(undefined);
+        });
+        test('getById reads a record directly by scope and id', async () => {
+            const store = createStore().orThrow();
+            await store.put(makeRecord({ id: 'direct', body: 'x' }));
+            expect(await store.getById('knowledge', 'direct')).toSucceedAndSatisfy((record) => {
+                expect(record === null || record === void 0 ? void 0 : record.body).toBe('x');
+            });
+        });
+        test('rejects a non-string body', async () => {
+            const store = createStore().orThrow();
+            expect(await store.put(makeRecord({ id: 'obj', body: { a: 1 } }))).toFailWith(/only string .* bodies are supported/i);
+        });
+        test('rejects a body the registered converter refuses', async () => {
+            const strict = Converters.string.map((s) => s === 'ok' ? succeed(s) : fail('must be ok'));
+            const store = createStore({ registry: knowledgeRegistry(strict) }).orThrow();
+            expect(await store.put(makeRecord({ id: 'bad', body: 'nope' }))).toFailWith(/invalid body.*must be ok/i);
+        });
+        test('fails when no codec is registered for the kind', async () => {
+            const registry = BodyConverterRegistry.create().orThrow();
+            registry.register('other', Converters.string);
+            const store = createStore({ registry }).orThrow();
+            expect(await store.put(makeRecord({ id: 'x', kind: 'other' }))).toFailWith(/no identity codec registered/i);
+        });
+    });
+    describe('content-hash dedup', () => {
+        test('an identical re-put is a no-op that returns the existing record', async () => {
+            const store = createStore().orThrow();
+            let firstSeq = -1;
+            let firstUpdated = -1;
+            expect(await store.put(makeRecord({ id: 'doc', body: 'same' }))).toSucceedAndSatisfy((first) => {
+                firstSeq = first.envelope.seq;
+                firstUpdated = first.envelope.updated;
+            });
+            expect(await store.put(makeRecord({ id: 'doc', body: 'same' }))).toSucceedAndSatisfy((second) => {
+                expect(second.envelope.seq).toBe(firstSeq);
+                expect(second.envelope.updated).toBe(firstUpdated);
+            });
+        });
+        test('dedup is scope-wide: a different entity with identical content collapses', async () => {
+            const store = createStore().orThrow();
+            let firstId = '';
+            expect(await store.put(makeRecord({ id: 'doc-a', body: 'identical' }))).toSucceedAndSatisfy((first) => {
+                firstId = first.envelope.id;
+            });
+            expect(await store.put(makeRecord({ id: 'doc-b', body: 'identical' }))).toSucceedAndSatisfy((second) => {
+                expect(second.envelope.id).toBe(firstId);
+            });
+            // doc-b was never written.
+            expect(await store.get(knowledgeKind, 'doc-b')).toSucceedWith(undefined);
+        });
+    });
+    describe('last-write-wins update', () => {
+        test('updates mutable fields via applyUpdate, preserving created and bumping seq/updated', async () => {
+            const store = createStore().orThrow();
+            let firstCreated = -1;
+            let firstSeq = -1;
+            expect(await store.put(makeRecord({ id: 'doc', body: 'v1', tags: ['a'] }))).toSucceedAndSatisfy((first) => {
+                firstCreated = first.envelope.created;
+                firstSeq = first.envelope.seq;
+            });
+            clockValue = 2000;
+            expect(await store.put(makeRecord({ id: 'doc', body: 'v2', tags: ['b', 'c'] }))).toSucceedAndSatisfy((second) => {
+                expect(second.envelope.created).toBe(firstCreated);
+                expect(second.envelope.updated).toBe(2000);
+                expect(second.envelope.seq).toBe(firstSeq + 1);
+                expect(second.body).toBe('v2');
+                expect(second.envelope.tags).toEqual(['b', 'c']);
+            });
+            expect(await store.list({ tag: 'a' })).toSucceedWith([]);
+        });
+        test('surfaces a policy applyUpdate failure with context', async () => {
+            const failingPolicy = {
+                mutableFields: ['body'],
+                admit: () => succeed({ decision: 'accept' }),
+                applyUpdate: () => fail('patch blew up')
+            };
+            const store = createStore({
+                writePolicies: new Map([[knowledgeKind, failingPolicy]])
+            }).orThrow();
+            await store.put(makeRecord({ id: 'doc', body: 'v1' }));
+            expect(await store.put(makeRecord({ id: 'doc', body: 'v2' }))).toFailWith(/update failed: patch blew up/i);
+        });
+        test('persists the policy-updated body and fails loudly if it is not a string', async () => {
+            // A policy whose applyUpdate swaps in a non-string body must be rejected at
+            // serialization time, not silently persist the incoming string.
+            const nonStringBodyPolicy = {
+                mutableFields: ['body'],
+                admit: () => succeed({ decision: 'accept' }),
+                applyUpdate: (existing) => succeed({ envelope: existing.envelope, body: { not: 'a string' } })
+            };
+            const store = createStore({
+                writePolicies: new Map([[knowledgeKind, nonStringBodyPolicy]])
+            }).orThrow();
+            await store.put(makeRecord({ id: 'doc', body: 'v1' }));
+            expect(await store.put(makeRecord({ id: 'doc', body: 'v2' }))).toFailWith(/policy returned a non-string body/i);
+        });
+    });
+    describe('admission policy', () => {
+        test("a 'reject' decision fails the put with the reason", async () => {
+            const rejectPolicy = {
+                mutableFields: [],
+                admit: () => succeed({ decision: 'reject', reason: 'over quota' }),
+                applyUpdate: (r) => succeed(r)
+            };
+            const store = createStore({
+                writePolicies: new Map([[knowledgeKind, rejectPolicy]])
+            }).orThrow();
+            expect(await store.put(makeRecord({ id: 'doc' }))).toFailWith(/rejected by policy: over quota/i);
+        });
+        test("a 'cull-oldest' decision evicts the named records before writing", async () => {
+            let putCount = 0;
+            const cullPolicy = {
+                mutableFields: ['body'],
+                admit: () => {
+                    putCount += 1;
+                    // First put admits; the second evicts the first.
+                    return putCount === 1
+                        ? succeed({ decision: 'accept' })
+                        : succeed({ decision: 'cull-oldest', evict: ['old'] });
+                },
+                applyUpdate: (r) => succeed(r)
+            };
+            const store = createStore({
+                writePolicies: new Map([[knowledgeKind, cullPolicy]])
+            }).orThrow();
+            await store.put(makeRecord({ id: 'old', body: 'old' }));
+            expect(await store.put(makeRecord({ id: 'new', body: 'new' }))).toSucceedAndSatisfy((put) => {
+                expect(put.envelope.id).toBe('new');
+            });
+            expect(await store.get(knowledgeKind, 'old')).toSucceedWith(undefined);
+        });
+        test("a 'cull-oldest' eviction of a missing record is best-effort: the committed put still succeeds and the failure is logged", async () => {
+            const cullPolicy = {
+                mutableFields: ['body'],
+                admit: () => succeed({ decision: 'cull-oldest', evict: ['ghost'] }),
+                applyUpdate: (r) => succeed(r)
+            };
+            const logger = new Logging.InMemoryLogger();
+            const store = FileTreeMemoryStore.create({
+                root: mutableRoot(),
+                registry: knowledgeRegistry(),
+                codecs: knowledgeCodecs,
+                writePolicies: new Map([[knowledgeKind, cullPolicy]]),
+                clock,
+                logger
+            }).orThrow();
+            // The new record is the authoritative commit; a failed best-effort eviction
+            // must NOT fail the put — it is logged and the cap self-heals next write.
+            expect(await store.put(makeRecord({ id: 'new', body: 'new' }))).toSucceedAndSatisfy((put) => {
+                expect(put.envelope.id).toBe('new');
+                expect(put.envelope.embeddingRef).toBeUndefined();
+            });
+            expect(await store.get(knowledgeKind, 'new')).toSucceedAndSatisfy((record) => {
+                expect(record === null || record === void 0 ? void 0 : record.envelope.id).toBe('new');
+            });
+            expect(logger.logged.some((m) => /best-effort eviction of 'ghost' failed.*not found/i.test(m))).toBe(true);
+        });
+    });
+    describe('list', () => {
+        test('filters by scope, kind, and tag', async () => {
+            const store = createStore().orThrow();
+            await store.put(makeRecord({ id: 'a', body: 'a', tags: ['t1'] }));
+            await store.put(makeRecord({ id: 'b', body: 'b', tags: ['t2'] }));
+            expect(await store.list()).toSucceedAndSatisfy((r) => expect(r).toHaveLength(2));
+            expect(await store.list({ scope: 'knowledge' })).toSucceedAndSatisfy((r) => expect(r).toHaveLength(2));
+            expect(await store.list({ scope: 'other' })).toSucceedAndSatisfy((r) => expect(r).toHaveLength(0));
+            expect(await store.list({ kind: knowledgeKind })).toSucceedAndSatisfy((r) => expect(r).toHaveLength(2));
+            expect(await store.list({ kind: 'missing' })).toSucceedAndSatisfy((r) => expect(r).toHaveLength(0));
+            expect(await store.list({ tag: 't1' })).toSucceedAndSatisfy((byTag) => {
+                expect(byTag).toHaveLength(1);
+                expect(byTag[0].envelope.id).toBe('a');
+            });
+        });
+    });
+    describe('delete', () => {
+        test('removes a record and returns its id', async () => {
+            const store = createStore().orThrow();
+            await store.put(makeRecord({ id: 'doomed', body: 'x' }));
+            expect(await store.delete(knowledgeKind, 'doomed')).toSucceedWith('doomed');
+            expect(await store.get(knowledgeKind, 'doomed')).toSucceedWith(undefined);
+            expect(await store.list()).toSucceedAndSatisfy((r) => expect(r).toHaveLength(0));
+        });
+        test('fails when the record does not exist', async () => {
+            const store = createStore().orThrow();
+            expect(await store.delete(knowledgeKind, 'nope')).toFailWith(/no record found/i);
+        });
+    });
+    describe('write-lock serialization', () => {
+        test('concurrent puts all land with monotonic seq', async () => {
+            const store = createStore().orThrow();
+            const results = await Promise.all([
+                store.put(makeRecord({ id: 'p1', body: '1' })),
+                store.put(makeRecord({ id: 'p2', body: '2' })),
+                store.put(makeRecord({ id: 'p3', body: '3' }))
+            ]);
+            const seqs = results.map((r) => {
+                let seq = -1;
+                expect(r).toSucceedAndSatisfy((rec) => {
+                    seq = rec.envelope.seq;
+                });
+                return seq;
+            });
+            expect([...seqs].sort((a, b) => a - b)).toEqual([1, 2, 3]);
+            expect(await store.list()).toSucceedAndSatisfy((r) => expect(r).toHaveLength(3));
+        });
+    });
+    describe('multi-segment scope codec', () => {
+        const turnKind = 'turn';
+        /** Maps `<conv>:<turn>` ⇄ scope `conversations/<conv>`, stem `turn-<n>`. */
+        const turnCodec = {
+            encode: (entityId) => {
+                const [conv, turn] = entityId.split(':');
+                return succeed({
+                    scope: `conversations/${conv}`,
+                    idStem: `turn-${turn}`,
+                    isVersioned: false
+                });
+            },
+            decode: (scope, stem) => {
+                const conv = scope.split('/')[1];
+                const turn = stem.replace('turn-', '');
+                return Convert.entityId.convert(`${conv}:${turn}`);
+            },
+            verifyRoundTrip: () => succeed(true)
+        };
+        function turnStore() {
+            const registry = BodyConverterRegistry.create().orThrow();
+            registry.register(turnKind, Converters.string);
+            return FileTreeMemoryStore.create({
+                root: mutableRoot(),
+                registry,
+                codecs: new Map([[turnKind, turnCodec]]),
+                clock
+            }).orThrow();
+        }
+        test('writes and reads through a nested scope directory', async () => {
+            const store = turnStore();
+            await store.put(makeRecord({ id: 'turn-0', entityId: 'c1:0', kind: 'turn', body: 'first turn' }));
+            expect(await store.get(turnKind, 'c1:0')).toSucceedAndSatisfy((record) => {
+                expect(record === null || record === void 0 ? void 0 : record.body).toBe('first turn');
+                expect(record === null || record === void 0 ? void 0 : record.envelope.id).toBe('turn-0');
+            });
+            expect((await store.list({ scope: 'conversations/c1' })).orThrow()).toHaveLength(1);
+        });
+        test('fails when the envelope id does not match the codec-derived stem', async () => {
+            const store = turnStore();
+            // id 'turn-9' but codec maps c1:0 → stem 'turn-0'.
+            expect(await store.put(makeRecord({ id: 'turn-9', entityId: 'c1:0', kind: 'turn', body: 'x' }))).toFailWith(/does not match codec-derived stem/i);
+        });
+    });
+    describe('versioned codec (loud degradation)', () => {
+        const versionedKind = 'versioned';
+        const versionedCodec = {
+            encode: (entityId) => succeed({ scope: 'versioned', idStem: entityId, isVersioned: true }),
+            decode: (__scope, stem) => Convert.entityId.convert(stem),
+            verifyRoundTrip: () => succeed(true)
+        };
+        function versionedStore() {
+            const registry = BodyConverterRegistry.create().orThrow();
+            registry.register(versionedKind, Converters.string);
+            return FileTreeMemoryStore.create({
+                root: mutableRoot(),
+                registry,
+                codecs: new Map([[versionedKind, versionedCodec]]),
+                clock
+            }).orThrow();
+        }
+        test('put fails loudly on a versioned layout', async () => {
+            expect(await versionedStore().put(makeRecord({ id: 'v', kind: 'versioned', body: 'x' }))).toFailWith(/versioned\/temporal layout not yet supported/i);
+        });
+        test('get fails loudly on a versioned layout', async () => {
+            expect(await versionedStore().get(versionedKind, 'v')).toFailWith(/versioned\/temporal layout not yet supported/i);
+        });
+        test('delete fails loudly on a versioned layout', async () => {
+            expect(await versionedStore().delete(versionedKind, 'v')).toFailWith(/versioned\/temporal layout not yet supported/i);
+        });
+    });
+    describe('default codec', () => {
+        test('a kind without an explicit codec entry uses the default codec', async () => {
+            const store = FileTreeMemoryStore.create({
+                root: mutableRoot(),
+                registry: knowledgeRegistry(),
+                codecs: new Map(),
+                defaultCodec: new KnowledgeIdentityCodec(),
+                clock
+            }).orThrow();
+            const put = (await store.put(makeRecord({ id: 'fallback', body: 'x' }))).orThrow();
+            expect(put.envelope.id).toBe('fallback');
+        });
+    });
+    describe('experience (memory) kinds — Phase C', () => {
+        const ltmKind = 'ltm';
+        const mtmKind = 'mtm';
+        /** A registry that gates the knowledge + LTM + MTM kind bodies (all strings here). */
+        function multiKindRegistry() {
+            const registry = BodyConverterRegistry.create().orThrow();
+            registry.register(knowledgeKind, Converters.string);
+            registry.register(ltmKind, Converters.string);
+            registry.register(mtmKind, Converters.string);
+            return registry;
+        }
+        const multiKindCodecs = new Map([
+            [knowledgeKind, new KnowledgeIdentityCodec()],
+            [ltmKind, new LtmIdentityCodec()],
+            [mtmKind, new MtmIdentityCodec()]
+        ]);
+        /** Cap-cull policy for the LTM/MTM kinds (entity-scoped dedup). */
+        function memoryPolicies(maxRecords = 5) {
+            const capCull = MemoryCapCullPolicy.create({
+                maxRecords,
+                mutableFields: ['body', 'tags', 'links', 'provenance', 'embeddingRef']
+            }).orThrow();
+            return new Map([
+                [ltmKind, capCull],
+                [mtmKind, capCull]
+            ]);
+        }
+        function memoryStore(root, maxRecords = 5) {
+            return FileTreeMemoryStore.create({
+                root: root !== null && root !== void 0 ? root : mutableRoot(),
+                registry: multiKindRegistry(),
+                codecs: multiKindCodecs,
+                writePolicies: memoryPolicies(maxRecords),
+                clock
+            }).orThrow();
+        }
+        test('registers all three kind families from one FileTree vault', async () => {
+            const store = memoryStore();
+            (await store.put(makeRecord({ id: 'intro', kind: 'knowledge', body: 'k' }))).orThrow();
+            (await store.put(makeRecord({ id: 'conv-1', entityId: 'conv-1', kind: 'ltm', body: 'l' }))).orThrow();
+            (await store.put(makeRecord({ id: 'turn-5', entityId: 'conv-1:5', kind: 'mtm', body: 'm' }))).orThrow();
+            expect(await store.get(knowledgeKind, 'intro')).toSucceedAndSatisfy((r) => {
+                expect(r === null || r === void 0 ? void 0 : r.envelope.kind).toBe('knowledge');
+            });
+            expect(await store.get(ltmKind, 'conv-1')).toSucceedAndSatisfy((r) => {
+                expect(r === null || r === void 0 ? void 0 : r.envelope.kind).toBe('ltm');
+            });
+            expect(await store.get(mtmKind, 'conv-1:5')).toSucceedAndSatisfy((r) => {
+                expect(r === null || r === void 0 ? void 0 : r.envelope.id).toBe('turn-5');
+                expect(r === null || r === void 0 ? void 0 : r.envelope.entityId).toBe('conv-1:5');
+            });
+        });
+        test('MTM composite key persists at conversations/<id>/turn-<n> and round-trips a reload', async () => {
+            const root = mutableRoot();
+            const store = memoryStore(root);
+            (await store.put(makeRecord({ id: 'turn-0', entityId: 'conv-x:0', kind: 'mtm', body: 'm0' }))).orThrow();
+            // A fresh store over the same root must re-index the MTM record (verifyRoundTrip
+            // exercises the multi-segment scope on load).
+            const reopened = memoryStore(root);
+            expect(await reopened.get(mtmKind, 'conv-x:0')).toSucceedAndSatisfy((r) => {
+                expect(r === null || r === void 0 ? void 0 : r.envelope.id).toBe('turn-0');
+            });
+        });
+        test('entity-scoped dedup: two distinct entities with identical content both persist', async () => {
+            // Regression for the flagged collapse bug: turn-5 and turn-9 share the same
+            // { kind, body, links } but are distinct entities and must NOT collapse.
+            const store = memoryStore();
+            const five = (await store.put(makeRecord({ id: 'turn-5', entityId: 'conv-1:5', kind: 'mtm', body: 'identical' }))).orThrow();
+            const nine = (await store.put(makeRecord({ id: 'turn-9', entityId: 'conv-1:9', kind: 'mtm', body: 'identical' }))).orThrow();
+            expect(five.envelope.id).toBe('turn-5');
+            expect(nine.envelope.id).toBe('turn-9');
+            expect(nine.envelope.id).not.toBe(five.envelope.id);
+            // Both are independently retrievable — neither collapsed into the other.
+            expect(await store.get(mtmKind, 'conv-1:5')).toSucceedAndSatisfy((r) => {
+                expect(r === null || r === void 0 ? void 0 : r.envelope.id).toBe('turn-5');
+            });
+            expect(await store.get(mtmKind, 'conv-1:9')).toSucceedAndSatisfy((r) => {
+                expect(r === null || r === void 0 ? void 0 : r.envelope.id).toBe('turn-9');
+            });
+            expect(await store.list({ kind: mtmKind })).toSucceedAndSatisfy((records) => {
+                expect(records).toHaveLength(2);
+            });
+        });
+        test('entity-scoped dedup: an identical re-put of the SAME entity is a no-op', async () => {
+            const store = memoryStore();
+            let firstSeq = -1;
+            expect(await store.put(makeRecord({ id: 'turn-5', entityId: 'conv-1:5', kind: 'mtm', body: 'same' }))).toSucceedAndSatisfy((r) => {
+                firstSeq = r.envelope.seq;
+            });
+            expect(await store.put(makeRecord({ id: 'turn-5', entityId: 'conv-1:5', kind: 'mtm', body: 'same' }))).toSucceedAndSatisfy((r) => {
+                expect(r.envelope.seq).toBe(firstSeq);
+            });
+        });
+        test('merge-patch updates the body of an existing memory entity (distinct content)', async () => {
+            const store = memoryStore();
+            let firstCreated = -1;
+            let firstSeq = -1;
+            expect(await store.put(makeRecord({ id: 'turn-5', entityId: 'conv-1:5', kind: 'mtm', body: 'v1' }))).toSucceedAndSatisfy((r) => {
+                firstCreated = r.envelope.created;
+                firstSeq = r.envelope.seq;
+            });
+            clockValue = 2000;
+            expect(await store.put(makeRecord({ id: 'turn-5', entityId: 'conv-1:5', kind: 'mtm', body: 'v2' }))).toSucceedAndSatisfy((r) => {
+                expect(r.body).toBe('v2');
+                expect(r.envelope.created).toBe(firstCreated);
+                expect(r.envelope.updated).toBe(2000);
+                expect(r.envelope.seq).toBe(firstSeq + 1);
+            });
+        });
+        test('cap-cull fires end-to-end: writing past maxRecords evicts the oldest in the scope', async () => {
+            // maxRecords: 3 over the shared conversations/conv-1 MTM scope. Four
+            // distinct turns are written with strictly increasing `created`; the
+            // store builds the per-scope/per-kind admission cohort, so the fourth
+            // write culls the oldest (turn-0) and leaves the cap at exactly 3.
+            const store = memoryStore(undefined, 3);
+            for (let turn = 0; turn < 4; turn++) {
+                clockValue = 1000 + turn; // distinct `created` so "oldest" is unambiguous.
+                (await store.put(makeRecord({
+                    id: `turn-${turn}`,
+                    entityId: `conv-1:${turn}`,
+                    kind: 'mtm',
+                    body: `turn ${turn}`
+                }))).orThrow();
+            }
+            // turn-0 (oldest) was evicted; turn-1..turn-3 remain → exactly maxRecords.
+            expect(await store.get(mtmKind, 'conv-1:0')).toSucceedWith(undefined);
+            expect(await store.get(mtmKind, 'conv-1:1')).toSucceedAndSatisfy((r) => {
+                expect(r === null || r === void 0 ? void 0 : r.envelope.id).toBe('turn-1');
+            });
+            expect(await store.get(mtmKind, 'conv-1:3')).toSucceedAndSatisfy((r) => {
+                expect(r === null || r === void 0 ? void 0 : r.envelope.id).toBe('turn-3');
+            });
+            expect(await store.list({ kind: mtmKind })).toSucceedAndSatisfy((records) => {
+                expect(records).toHaveLength(3);
+                expect(records.map((r) => r.envelope.id).sort()).toEqual(['turn-1', 'turn-2', 'turn-3']);
+            });
+        });
+        test('cap-cull does not evict on a same-entity update (replace, not grow)', async () => {
+            // With the cohort excluding the target id, updating an existing turn while
+            // at the cap is a replace: the cohort is maxRecords-1, so no cull fires.
+            const store = memoryStore(undefined, 3);
+            for (let turn = 0; turn < 3; turn++) {
+                clockValue = 1000 + turn;
+                (await store.put(makeRecord({ id: `turn-${turn}`, entityId: `conv-1:${turn}`, kind: 'mtm', body: `v1-${turn}` }))).orThrow();
+            }
+            clockValue = 2000;
+            (await store.put(makeRecord({ id: 'turn-0', entityId: 'conv-1:0', kind: 'mtm', body: 'v2-0' }))).orThrow();
+            // All three still present (turn-0 updated, not culled).
+            expect(await store.list({ kind: mtmKind })).toSucceedAndSatisfy((records) => {
+                expect(records).toHaveLength(3);
+            });
+            expect(await store.get(mtmKind, 'conv-1:0')).toSucceedAndSatisfy((r) => {
+                expect(r === null || r === void 0 ? void 0 : r.body).toBe('v2-0');
+            });
+        });
+        test('cap-cull evicts multiple victims in one write when the cohort starts over cap', async () => {
+            // Seed five turns under cap 5 (no eviction), then reopen the same vault
+            // with cap 2. The next write's cohort is the five seeded records, so the
+            // single admit returns FOUR victims (oldest by `created`) and the post-
+            // write count settles to exactly the new cap.
+            const root = mutableRoot();
+            const seeded = memoryStore(root, 5);
+            for (let turn = 0; turn < 5; turn++) {
+                clockValue = 1000 + turn;
+                (await seeded.put(makeRecord({ id: `turn-${turn}`, entityId: `conv-1:${turn}`, kind: 'mtm', body: `turn ${turn}` }))).orThrow();
+            }
+            const reopened = memoryStore(root, 2);
+            clockValue = 2000;
+            (await reopened.put(makeRecord({ id: 'turn-5', entityId: 'conv-1:5', kind: 'mtm', body: 'turn 5' }))).orThrow();
+            // turn-0..turn-3 (the four oldest) evicted; turn-4 + turn-5 remain.
+            for (const culled of [0, 1, 2, 3]) {
+                expect(await reopened.get(mtmKind, `conv-1:${culled}`)).toSucceedWith(undefined);
+            }
+            expect(await reopened.list({ kind: mtmKind })).toSucceedAndSatisfy((records) => {
+                expect(records.map((r) => r.envelope.id).sort()).toEqual(['turn-4', 'turn-5']);
+            });
+        });
+        test('cap-cull is scoped to (scope, kind): other scopes and kinds are not evicted', async () => {
+            // cap 2 over MTM. A second conversation scope and a knowledge record share
+            // the vault; filling conv-1 past its cap must leave both untouched.
+            const store = memoryStore(undefined, 2);
+            clockValue = 500;
+            (await store.put(makeRecord({ id: 'turn-0', entityId: 'conv-2:0', kind: 'mtm', body: 'other convo' }))).orThrow();
+            clockValue = 600;
+            (await store.put(makeRecord({ id: 'intro', kind: 'knowledge', body: 'knowledge doc' }))).orThrow();
+            for (let turn = 0; turn < 3; turn++) {
+                clockValue = 1000 + turn;
+                (await store.put(makeRecord({
+                    id: `turn-${turn}`,
+                    entityId: `conv-1:${turn}`,
+                    kind: 'mtm',
+                    body: `c1 turn ${turn}`
+                }))).orThrow();
+            }
+            // conv-1 culled its oldest (turn-0) down to exactly cap 2.
+            expect(await store.get(mtmKind, 'conv-1:0')).toSucceedWith(undefined);
+            expect(await store.list({ scope: 'conversations/conv-1' })).toSucceedAndSatisfy((records) => {
+                expect(records.map((r) => r.envelope.id).sort()).toEqual(['turn-1', 'turn-2']);
+            });
+            // The other conversation scope and the knowledge kind are untouched.
+            expect(await store.get(mtmKind, 'conv-2:0')).toSucceedAndSatisfy((r) => {
+                expect(r === null || r === void 0 ? void 0 : r.envelope.id).toBe('turn-0');
+                expect(r === null || r === void 0 ? void 0 : r.body).toBe('other convo');
+            });
+            expect(await store.get(knowledgeKind, 'intro')).toSucceedAndSatisfy((r) => {
+                expect(r === null || r === void 0 ? void 0 : r.body).toBe('knowledge doc');
+            });
+        });
+    });
+});
+//# sourceMappingURL=fileTreeMemoryStore.test.js.map