@fgv/ts-agent-memory 5.1.0-47 → 5.1.0-49

package/dist/test/unit/tools/memoryTools.test.js

@@ -1,842 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-import '@fgv/ts-utils-jest';
-import { Converters, fail, succeed } from '@fgv/ts-utils';
-import { FileTree } from '@fgv/ts-json-base';
-import { BodyConverterRegistry, DEFAULT_MEMORY_TOOLS, FileTreeMemoryStore, HybridRetriever, KnowledgeIdentityCodec, LinkTraversalRetriever, MemoryIndex, MtmIdentityCodec, RecencyRetriever, ScoreUnionMergeStrategy, StructuredFilterRetriever, TagRetriever, createMemoryTools, envelopeConverter } from '../../../index';
-const knowledgeKind = 'knowledge';
-const mtmKind = 'mtm';
-// ---------------------------------------------------------------------------
-// Fixtures
-// ---------------------------------------------------------------------------
-function mutableRoot() {
-    const tree = FileTree.inMemory([], { mutable: true }).orThrow();
-    const root = tree.getDirectory('/').orThrow();
-    if (!FileTree.isMutableDirectoryItem(root)) {
-        throw new Error('expected a mutable root directory');
-    }
-    return root;
-}
-function registryWith(entries) {
-    var _a;
-    const registry = BodyConverterRegistry.create().orThrow();
-    for (const entry of entries) {
-        registry.register(entry.kind, (_a = entry.converter) !== null && _a !== void 0 ? _a : Converters.string);
-    }
-    return registry;
-}
-const codecs = new Map([
-    [knowledgeKind, new KnowledgeIdentityCodec()],
-    [mtmKind, new MtmIdentityCodec()]
-]);
-/** A write policy that always rejects — exercises the admit-reject → fail path. */
-class RejectingPolicy {
-    constructor() {
-        this.mutableFields = ['body'];
-    }
-    admit() {
-        return succeed({ decision: 'reject', reason: 'blocked by test policy' });
-    }
-    applyUpdate(existing) {
-        return succeed(existing);
-    }
-}
-function makeStore(params = {}) {
-    var _a;
-    return FileTreeMemoryStore.create({
-        root: mutableRoot(),
-        registry: (_a = params.registry) !== null && _a !== void 0 ? _a : registryWith([{ kind: knowledgeKind }, { kind: mtmKind }]),
-        codecs,
-        writePolicies: params.writePolicies
-    }).orThrow();
-}
-function makeEntry(spec) {
-    var _a, _b, _c, _d, _e, _f;
-    const record = {
-        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 : []).map((target) => {
-                var _a;
-                return ({
-                    type: 'rel',
-                    target: { scope: (_a = spec.scope) !== null && _a !== void 0 ? _a : 'knowledge', id: target }
-                });
-            }),
-            created: 0,
-            updated: (_e = spec.updated) !== null && _e !== void 0 ? _e : 0,
-            seq: 0,
-            contentHash: 'h',
-            provenance: { source: 'agent' }
-        })
-            .orThrow(),
-        body: `body-${spec.id}`
-    };
-    return { scope: ((_f = spec.scope) !== null && _f !== void 0 ? _f : 'knowledge'), record };
-}
-function makeIndex(specs) {
-    const index = MemoryIndex.create().orThrow();
-    index.rebuild(specs.map(makeEntry)).orThrow();
-    return index;
-}
-/**
- * A HybridRetriever (structured + tag) over the given entries — the seedless
- * `memory_search` backing. A bare `LinkTraversalRetriever` is intentionally NOT
- * composed here: it hard-fails a seedless query, so link traversal is the
- * separate `memory_context` retriever.
- */
-function makeRetriever(specs) {
-    const index = makeIndex(specs);
-    return HybridRetriever.create([
-        RecencyRetriever.create(index).orThrow(),
-        StructuredFilterRetriever.create(index).orThrow(),
-        TagRetriever.create(index).orThrow()
-    ], ScoreUnionMergeStrategy.create().orThrow()).orThrow();
-}
-/** A LinkTraversalRetriever over the given entries — the `memory_context` backing. */
-function makeLinkRetriever(specs) {
-    return LinkTraversalRetriever.create(makeIndex(specs)).orThrow();
-}
-/** Build the full five-tool suite for structural / annotation inspection. */
-function allTools(overrides = {}) {
-    var _a, _b, _c;
-    return createMemoryTools(Object.assign({ store: (_a = overrides.store) !== null && _a !== void 0 ? _a : makeStore(), retriever: (_b = overrides.retriever) !== null && _b !== void 0 ? _b : makeRetriever([]), registry: (_c = overrides.registry) !== null && _c !== void 0 ? _c : registryWith([{ kind: knowledgeKind }, { kind: mtmKind }]), codecs, tools: ['memory_write', 'memory_read', 'memory_search', 'memory_context', 'memory_delete'] }, overrides));
-}
-function toolByName(tools, name) {
-    const tool = tools.find((t) => t.config.name === name);
-    if (tool === undefined) {
-        throw new Error(`tool '${name}' not found`);
-    }
-    return tool;
-}
-/** The property names declared by a tool's JSON-schema. */
-function schemaProperties(tool) {
-    var _a;
-    const json = tool.config.parametersSchema.toJson();
-    return Object.keys((_a = json.properties) !== null && _a !== void 0 ? _a : {});
-}
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-describe('createMemoryTools', () => {
-    describe('tool subset selection', () => {
-        test('defaults to the read-only set (excludes memory_write / memory_delete)', () => {
-            const tools = createMemoryTools({
-                store: makeStore(),
-                retriever: makeRetriever([]),
-                registry: registryWith([{ kind: knowledgeKind }])
-            });
-            expect(tools.map((t) => t.config.name)).toEqual(['memory_search', 'memory_context']);
-            expect(DEFAULT_MEMORY_TOOLS).toEqual(['memory_search', 'memory_context']);
-        });
-        test('includes memory_write / memory_delete only when named', () => {
-            const tools = createMemoryTools({
-                store: makeStore(),
-                retriever: makeRetriever([]),
-                registry: registryWith([{ kind: knowledgeKind }]),
-                codecs,
-                tools: ['memory_write', 'memory_delete']
-            });
-            expect(tools.map((t) => t.config.name)).toEqual(['memory_write', 'memory_delete']);
-        });
-        test('returns tools in a stable builder order regardless of selection order', () => {
-            const tools = createMemoryTools({
-                store: makeStore(),
-                retriever: makeRetriever([]),
-                registry: registryWith([{ kind: knowledgeKind }]),
-                codecs,
-                tools: ['memory_delete', 'memory_search', 'memory_write']
-            });
-            expect(tools.map((t) => t.config.name)).toEqual(['memory_write', 'memory_search', 'memory_delete']);
-        });
-        test('an empty selection yields no tools', () => {
-            const tools = createMemoryTools({
-                store: makeStore(),
-                retriever: makeRetriever([]),
-                registry: registryWith([{ kind: knowledgeKind }]),
-                tools: []
-            });
-            expect(tools).toEqual([]);
-        });
-    });
-    describe('scope isolation (adoption gate)', () => {
-        test('NO tool schema declares a scope (or scope-widening) property', () => {
-            const tools = allTools();
-            expect(tools).toHaveLength(5);
-            for (const tool of tools) {
-                const props = schemaProperties(tool);
-                expect(props.length).toBeGreaterThan(0);
-                for (const prop of props) {
-                    expect(prop.toLowerCase()).not.toContain('scope');
-                }
-            }
-        });
-    });
-    describe('behavior annotations (Component 4)', () => {
-        test('read-only tools are readOnlyHint with openWorldHint false', () => {
-            const tools = allTools();
-            for (const name of ['memory_search', 'memory_context', 'memory_read']) {
-                expect(toolByName(tools, name).config.annotations).toEqual({
-                    readOnlyHint: true,
-                    openWorldHint: false
-                });
-            }
-        });
-        test('memory_write is non-destructive, non-idempotent, closed-world', () => {
-            expect(toolByName(allTools(), 'memory_write').config.annotations).toEqual({
-                destructiveHint: false,
-                idempotentHint: false,
-                openWorldHint: false
-            });
-        });
-        test('memory_delete is destructive, idempotent, closed-world', () => {
-            expect(toolByName(allTools(), 'memory_delete').config.annotations).toEqual({
-                destructiveHint: true,
-                idempotentHint: true,
-                openWorldHint: false
-            });
-        });
-    });
-    describe('parametersSchema validation', () => {
-        test('memory_write accepts a well-formed record and rejects a missing body', () => {
-            const schema = toolByName(allTools(), 'memory_write').config.parametersSchema;
-            expect(schema.convert({ kind: 'knowledge', entityId: 'doc-1', body: 'hello' })).toSucceed();
-            expect(schema.convert({
-                kind: 'knowledge',
-                entityId: 'doc-1',
-                body: 'hello',
-                tags: ['a'],
-                links: [{ type: 'rel', target: { id: 'doc-2' }, confidence: 0.5 }]
-            })).toSucceed();
-            expect(schema.convert({
-                kind: 'knowledge',
-                entityId: 'doc-1',
-                body: 'hello',
-                links: [{ type: 'rel', target: { scope: 'conversations/other', id: 'turn-1' } }]
-            })).toSucceed();
-            expect(schema.convert({ kind: 'knowledge', entityId: 'doc-1' })).toFail();
-            // A bare-string target (the pre-scoped format) is rejected at the schema.
-            expect(schema.convert({
-                kind: 'knowledge',
-                entityId: 'doc-1',
-                body: 'x',
-                links: [{ type: 'rel', target: 'doc-2' }]
-            })).toFail();
-        });
-        test('memory_read / memory_delete require kind and entityId', () => {
-            for (const name of ['memory_read', 'memory_delete']) {
-                const schema = toolByName(allTools(), name).config.parametersSchema;
-                expect(schema.convert({ kind: 'knowledge', entityId: 'doc-1' })).toSucceed();
-                expect(schema.convert({ kind: 'knowledge' })).toFail();
-            }
-        });
-        test('memory_search rejects a non-integer limit and accepts an all-optional query', () => {
-            const schema = toolByName(allTools(), 'memory_search').config.parametersSchema;
-            expect(schema.convert({})).toSucceed();
-            expect(schema.convert({ tag: 'x', limit: 3 })).toSucceed();
-            expect(schema.convert({ limit: 'three' })).toFail();
-        });
-        test('memory_context requires a from seed with a REQUIRED scope (nested { id, scope })', () => {
-            const schema = toolByName(allTools(), 'memory_context').config.parametersSchema;
-            expect(schema.convert({ from: { id: 'doc-1', scope: 'knowledge' } })).toSucceed();
-            // scope is schema-REQUIRED (unlike a write link target) — the wire schema must
-            // not advertise an optionality the tool does not honor. Omitting it fails.
-            expect(schema.convert({ from: { id: 'doc-1' } })).toFail();
-            expect(schema.convert({ hops: 2 })).toFail();
-            // A bare-string seed (the pre-scoped format) is rejected at the schema.
-            expect(schema.convert({ from: 'doc-1' })).toFail();
-        });
-        test('the memory_context wire schema marks from.scope as required', () => {
-            // Guards the schema-accuracy contract at the wire level: an LLM reading the
-            // tool's `parameters` sees scope in the seed's `required` array.
-            const schema = toolByName(allTools(), 'memory_context').config.parametersSchema;
-            const wire = schema.toJson();
-            expect(wire.properties.from.required).toContain('scope');
-        });
-    });
-    describe('memory_write', () => {
-        async function write(tool, args) {
-            return tool.execute(args);
-        }
-        test('writes a new record (outcome: written) and round-trips through memory_read', async () => {
-            const store = makeStore();
-            const tools = createMemoryTools({
-                store,
-                retriever: makeRetriever([]),
-                registry: registryWith([{ kind: knowledgeKind }]),
-                codecs,
-                tools: ['memory_write', 'memory_read']
-            });
-            const writeTool = toolByName(tools, 'memory_write');
-            expect(await write(writeTool, { kind: 'knowledge', entityId: 'doc-1', body: 'first', tags: ['t'] })).toSucceedAndSatisfy((value) => {
-                const result = value;
-                expect(result.outcome).toBe('written');
-                expect(result.id).toBe('doc-1');
-                expect(result.entityId).toBe('doc-1');
-            });
-            expect(await toolByName(tools, 'memory_read').execute({ kind: 'knowledge', entityId: 'doc-1' })).toSucceedAndSatisfy((value) => {
-                const read = value;
-                expect(read.found).toBe(true);
-                expect(read.item.body).toBe('first');
-                expect(read.item.tags).toEqual(['t']);
-            });
-        });
-        test('persists authored links (with confidence) on the written record', async () => {
-            const store = makeStore();
-            const tools = createMemoryTools({
-                store,
-                retriever: makeRetriever([]),
-                registry: registryWith([{ kind: knowledgeKind }]),
-                codecs,
-                tools: ['memory_write', 'memory_read']
-            });
-            expect(await toolByName(tools, 'memory_write').execute({
-                kind: 'knowledge',
-                entityId: 'doc-1',
-                body: 'linked',
-                links: [
-                    // scope omitted → defaults to the writing record's own scope (knowledge)
-                    { type: 'rel', target: { id: 'doc-2' }, confidence: 0.9 },
-                    { type: 'rel', target: { id: 'doc-3' } }
-                ]
-            })).toSucceedAndSatisfy((v) => expect(v.outcome).toBe('written'));
-            // The persisted links carry the writing record's scope on each target.
-            expect(await store.get(knowledgeKind, 'doc-1')).toSucceedAndSatisfy((rec) => {
-                expect(rec === null || rec === void 0 ? void 0 : rec.envelope.links).toEqual([
-                    { type: 'rel', target: { scope: 'knowledge', id: 'doc-2' }, confidence: 0.9 },
-                    { type: 'rel', target: { scope: 'knowledge', id: 'doc-3' } }
-                ]);
-            });
-        });
-        test('an authored link with an EXPLICIT scope is honored verbatim (cross-scope edge)', async () => {
-            const store = makeStore();
-            const tools = createMemoryTools({
-                store,
-                retriever: makeRetriever([]),
-                registry: registryWith([{ kind: knowledgeKind }]),
-                codecs,
-                tools: ['memory_write']
-            });
-            expect(await toolByName(tools, 'memory_write').execute({
-                kind: 'knowledge',
-                entityId: 'doc-1',
-                body: 'cross',
-                links: [{ type: 'mtm-ref', target: { scope: 'conversations/conv-a', id: 'turn-3' } }]
-            })).toSucceed();
-            expect(await store.get(knowledgeKind, 'doc-1')).toSucceedAndSatisfy((rec) => {
-                expect(rec === null || rec === void 0 ? void 0 : rec.envelope.links).toEqual([
-                    { type: 'mtm-ref', target: { scope: 'conversations/conv-a', id: 'turn-3' } }
-                ]);
-            });
-        });
-        test('an identical re-put of the same entity is a dedup no-op (outcome: deduped)', async () => {
-            const store = makeStore();
-            const tool = toolByName(allTools({ store }), 'memory_write');
-            expect(await write(tool, { kind: 'knowledge', entityId: 'doc-1', body: 'same' })).toSucceedAndSatisfy((v) => expect(v.outcome).toBe('written'));
-            expect(await write(tool, { kind: 'knowledge', entityId: 'doc-1', body: 'same' })).toSucceedAndSatisfy((v) => expect(v.outcome).toBe('deduped'));
-        });
-        test('content-scope dedup under a different entity reports deduped', async () => {
-            const store = makeStore();
-            const tool = toolByName(allTools({ store }), 'memory_write');
-            expect(await write(tool, { kind: 'knowledge', entityId: 'doc-a', body: 'shared' })).toSucceed();
-            // Knowledge dedups scope-wide: identical body under a different docId is a no-op
-            // that returns the existing (different-entity) record.
-            expect(await write(tool, { kind: 'knowledge', entityId: 'doc-b', body: 'shared' })).toSucceedAndSatisfy((v) => expect(v.outcome).toBe('deduped'));
-        });
-        test('an update with new content reports written', async () => {
-            const store = makeStore();
-            const tool = toolByName(allTools({ store }), 'memory_write');
-            expect(await write(tool, { kind: 'knowledge', entityId: 'doc-1', body: 'v1' })).toSucceed();
-            expect(await write(tool, { kind: 'knowledge', entityId: 'doc-1', body: 'v2' })).toSucceedAndSatisfy((v) => expect(v.outcome).toBe('written'));
-        });
-        test('maps an MTM composite entityId to its turn stem', async () => {
-            const store = makeStore();
-            const tools = createMemoryTools({
-                store,
-                retriever: makeRetriever([]),
-                registry: registryWith([{ kind: knowledgeKind }, { kind: mtmKind }]),
-                codecs,
-                tools: ['memory_write', 'memory_read']
-            });
-            expect(await toolByName(tools, 'memory_write').execute({
-                kind: 'mtm',
-                entityId: 'conv-1:7',
-                body: 'turn body'
-            })).toSucceedAndSatisfy((value) => {
-                const result = value;
-                expect(result.id).toBe('turn-7');
-                expect(result.entityId).toBe('conv-1:7');
-            });
-            // Read back via the same composite entityId.
-            expect(await toolByName(tools, 'memory_read').execute({ kind: 'mtm', entityId: 'conv-1:7' })).toSucceedAndSatisfy((value) => {
-                expect(value.found).toBe(true);
-            });
-        });
-        test('a body the kind converter rejects fails the write', async () => {
-            const rejectBad = Converters.string.map((s) => s === 'BAD' ? fail('body not allowed') : succeed(s));
-            const registry = registryWith([{ kind: knowledgeKind, converter: rejectBad }]);
-            const store = makeStore({ registry });
-            const tool = toolByName(allTools({ store, registry }), 'memory_write');
-            expect(await write(tool, { kind: 'knowledge', entityId: 'doc-1', body: 'BAD' })).toFailWith(/invalid body|body not allowed/i);
-        });
-        test('a policy admit-reject surfaces as a failure', async () => {
-            const store = makeStore({
-                writePolicies: new Map([[knowledgeKind, new RejectingPolicy()]])
-            });
-            const tool = toolByName(allTools({ store }), 'memory_write');
-            expect(await write(tool, { kind: 'knowledge', entityId: 'doc-1', body: 'x' })).toFailWith(/rejected by policy|blocked by test policy/i);
-        });
-        test('fails when no codec is available for the kind', async () => {
-            const store = makeStore();
-            const tool = toolByName(createMemoryTools({
-                store,
-                retriever: makeRetriever([]),
-                registry: registryWith([{ kind: knowledgeKind }]),
-                tools: ['memory_write'] // no codecs / defaultCodec supplied
-            }), 'memory_write');
-            expect(await write(tool, { kind: 'knowledge', entityId: 'doc-1', body: 'x' })).toFailWith(/no identity codec available/i);
-        });
-        test('rejects a kind with no registered converter', async () => {
-            const tool = toolByName(allTools(), 'memory_write');
-            expect(await write(tool, { kind: 'unregistered', entityId: 'doc-1', body: 'x' })).toFailWith(/no registered body converter/i);
-        });
-        test('rejects a kind outside the kinds whitelist', async () => {
-            const tool = toolByName(allTools({ kinds: [mtmKind] }), 'memory_write');
-            expect(await write(tool, { kind: 'knowledge', entityId: 'doc-1', body: 'x' })).toFailWith(/not enabled for memory tools/i);
-        });
-        test('propagates a store.get failure (does not mask a real fault as a fresh write)', async () => {
-            const failingStore = {
-                get: async () => fail('disk fault'),
-                getById: async () => fail('unused'),
-                list: async () => succeed([]),
-                listScoped: async () => succeed([]),
-                asRecordSource: () => ({ list: async () => succeed([]) }),
-                dedupScopeFor: () => 'content',
-                put: async (record) => succeed(record),
-                delete: async () => fail('unused')
-            };
-            const tool = toolByName(createMemoryTools({
-                store: failingStore,
-                retriever: makeRetriever([]),
-                registry: registryWith([{ kind: knowledgeKind }]),
-                codecs,
-                tools: ['memory_write']
-            }), 'memory_write');
-            expect(await write(tool, { kind: 'knowledge', entityId: 'doc-1', body: 'x' })).toFailWith(/disk fault/i);
-        });
-        test('rejects a versioned/temporal kind', async () => {
-            const versionedCodec = {
-                encode: (entityId) => succeed({ scope: 'knowledge', idStem: entityId, isVersioned: true }),
-                decode: () => fail('unused'),
-                verifyRoundTrip: () => succeed(true)
-            };
-            const tool = toolByName(createMemoryTools({
-                store: makeStore(),
-                retriever: makeRetriever([]),
-                registry: registryWith([{ kind: knowledgeKind }]),
-                codecs: new Map([[knowledgeKind, versionedCodec]]),
-                tools: ['memory_write']
-            }), 'memory_write');
-            expect(await write(tool, { kind: 'knowledge', entityId: 'doc-1', body: 'x' })).toFailWith(/versioned\/temporal kind .* is not supported/i);
-        });
-        test('rejects malformed arguments', async () => {
-            const tool = toolByName(allTools(), 'memory_write');
-            expect(await write(tool, { kind: 'knowledge', entityId: 'doc-1' })).toFailWith(/invalid arguments/i);
-        });
-    });
-    describe('memory_read', () => {
-        test('returns found:false when the record is absent', async () => {
-            const tool = toolByName(allTools(), 'memory_read');
-            expect(await tool.execute({ kind: 'knowledge', entityId: 'missing' })).toSucceedWith({ found: false });
-        });
-        test('applies the handleFor hook to the returned item', async () => {
-            const store = makeStore();
-            const tools = createMemoryTools({
-                store,
-                retriever: makeRetriever([]),
-                registry: registryWith([{ kind: knowledgeKind }]),
-                codecs,
-                tools: ['memory_write', 'memory_read'],
-                handleFor: (r) => `mnemonic:${r.envelope.id}`
-            });
-            await toolByName(tools, 'memory_write').execute({ kind: 'knowledge', entityId: 'doc-1', body: 'b' });
-            expect(await toolByName(tools, 'memory_read').execute({ kind: 'knowledge', entityId: 'doc-1' })).toSucceedAndSatisfy((value) => {
-                const read = value;
-                expect(read.item.handle).toBe('mnemonic:doc-1');
-            });
-        });
-        test('propagates a store failure (bad entityId)', async () => {
-            const tool = toolByName(allTools(), 'memory_read');
-            expect(await tool.execute({ kind: 'knowledge', entityId: '   ' })).toFail();
-        });
-    });
-    describe('memory_search', () => {
-        test('returns projected results keyed by raw MemoryId when no handleFor is supplied', async () => {
-            const retriever = makeRetriever([
-                { id: 'doc-1', tags: ['topic'] },
-                { id: 'doc-2', tags: ['topic'] }
-            ]);
-            const tool = toolByName(createMemoryTools({
-                store: makeStore(),
-                retriever,
-                registry: registryWith([{ kind: knowledgeKind }])
-            }), 'memory_search');
-            expect(await tool.execute({ tag: 'topic' })).toSucceedAndSatisfy((value) => {
-                const out = value;
-                expect(out.count).toBe(2);
-                expect(out.results.map((r) => r.handle).sort()).toEqual(['doc-1', 'doc-2']);
-            });
-        });
-        test('uses the host handle (mnemonic) as the agent-visible key when handleFor is supplied', async () => {
-            const retriever = makeRetriever([{ id: 'doc-1', tags: ['topic'] }]);
-            const tool = toolByName(createMemoryTools({
-                store: makeStore(),
-                retriever,
-                registry: registryWith([{ kind: knowledgeKind }]),
-                handleFor: (r) => `@${r.envelope.id}`
-            }), 'memory_search');
-            expect(await tool.execute({ tag: 'topic', limit: 5 })).toSucceedAndSatisfy((value) => {
-                const out = value;
-                expect(out.results[0].handle).toBe('@doc-1');
-            });
-        });
-        test('falls back to the raw id when a throwing handleFor would otherwise escape', async () => {
-            const retriever = makeRetriever([{ id: 'doc-1', tags: ['topic'] }]);
-            const tool = toolByName(createMemoryTools({
-                store: makeStore(),
-                retriever,
-                registry: registryWith([{ kind: knowledgeKind }]),
-                handleFor: () => {
-                    throw new Error('host handle hook blew up');
-                }
-            }), 'memory_search');
-            // A throwing host callback must not crash the search; the item degrades to the raw id.
-            expect(await tool.execute({ tag: 'topic', limit: 5 })).toSucceedAndSatisfy((value) => {
-                const out = value;
-                expect(out.results[0].handle).toBe('doc-1');
-            });
-        });
-        test('loud-degrades on the unwired semantic axis', async () => {
-            const retriever = makeRetriever([{ id: 'doc-1' }]);
-            const tool = toolByName(createMemoryTools({
-                store: makeStore(),
-                retriever,
-                registry: registryWith([{ kind: knowledgeKind }])
-            }), 'memory_search');
-            expect(await tool.execute({ semantic: 'find me' })).toFailWith(/semantic recall requires a vector index/i);
-        });
-        test('rejects a kind outside the kinds whitelist', async () => {
-            const retriever = makeRetriever([{ id: 'doc-1' }]);
-            const tool = toolByName(createMemoryTools({
-                store: makeStore(),
-                retriever,
-                registry: registryWith([{ kind: knowledgeKind }]),
-                kinds: [knowledgeKind]
-            }), 'memory_search');
-            expect(await tool.execute({ kind: 'mtm' })).toFailWith(/no registered body converter|not enabled/i);
-        });
-        test('filters by a validated kind', async () => {
-            const retriever = makeRetriever([
-                { id: 'doc-1', kind: 'knowledge' },
-                { id: 'turn-0', kind: 'mtm', scope: 'conversations/conv-1' }
-            ]);
-            const tool = toolByName(createMemoryTools({
-                store: makeStore(),
-                retriever,
-                registry: registryWith([{ kind: knowledgeKind }, { kind: mtmKind }])
-            }), 'memory_search');
-            expect(await tool.execute({ kind: 'knowledge' })).toSucceedAndSatisfy((value) => {
-                const out = value;
-                expect(out.results.map((r) => r.handle)).toEqual(['doc-1']);
-            });
-        });
-        test('rejects malformed arguments', async () => {
-            const tool = toolByName(allTools(), 'memory_search');
-            expect(await tool.execute({ limit: 'nope' })).toFailWith(/invalid arguments/i);
-        });
-    });
-    describe('memory_context', () => {
-        test('returns the neighbors reachable from a seed', async () => {
-            const retriever = makeLinkRetriever([
-                { id: 'a', links: ['b', 'c'] },
-                { id: 'b', updated: 20 },
-                { id: 'c', updated: 10 }
-            ]);
-            const tool = toolByName(createMemoryTools({
-                store: makeStore(),
-                retriever,
-                registry: registryWith([{ kind: knowledgeKind }])
-            }), 'memory_context');
-            expect(await tool.execute({ from: { id: 'a', scope: 'knowledge' } })).toSucceedAndSatisfy((value) => {
-                const out = value;
-                expect(out.seed).toEqual({ scope: 'knowledge', id: 'a' });
-                expect(out.results.map((r) => r.handle)).toEqual(['b', 'c']);
-            });
-        });
-        test('honors hops, kind, tag, and limit filters', async () => {
-            const retriever = makeLinkRetriever([
-                { id: 'a', links: ['b'] },
-                { id: 'b', links: ['c'], tags: ['keep'] },
-                { id: 'c', tags: ['keep'] }
-            ]);
-            const tool = toolByName(createMemoryTools({
-                store: makeStore(),
-                retriever,
-                registry: registryWith([{ kind: knowledgeKind }])
-            }), 'memory_context');
-            expect(await tool.execute({
-                from: { id: 'a', scope: 'knowledge' },
-                hops: 2,
-                tag: 'keep',
-                kind: 'knowledge',
-                limit: 5
-            })).toSucceedAndSatisfy((value) => {
-                const out = value;
-                expect(out.results.map((r) => r.handle).sort()).toEqual(['b', 'c']);
-            });
-        });
-        test('rejects an invalid seed id', async () => {
-            const tool = toolByName(allTools(), 'memory_context');
-            expect(await tool.execute({ from: { id: 'a/b', scope: 'knowledge' } })).toFail();
-        });
-        test('fails at the schema when the seed omits its required scope', async () => {
-            // scope is schema-required, so an omitted scope is rejected as an invalid
-            // argument (the wire schema and the runtime contract agree — no lie).
-            const tool = toolByName(allTools(), 'memory_context');
-            expect(await tool.execute({ from: { id: 'a' } })).toFailWith(/invalid arguments/i);
-        });
-        test('a scoped seed reaches ONLY the correctly-scoped graph', async () => {
-            // Two conversations reuse the stem `turn-0`; each links a same-scope `turn-1`.
-            // Seeding conv-a must reach conv-a's turn-1 and NEVER conv-b's.
-            const retriever = makeLinkRetriever([
-                { id: 'turn-0', scope: 'conversations/conv-a', links: ['turn-1'] },
-                { id: 'turn-1', scope: 'conversations/conv-a', tags: ['in-a'] },
-                { id: 'turn-0', scope: 'conversations/conv-b', links: ['turn-1'] },
-                { id: 'turn-1', scope: 'conversations/conv-b', tags: ['in-b'] }
-            ]);
-            const tool = toolByName(createMemoryTools({
-                store: makeStore(),
-                retriever,
-                registry: registryWith([{ kind: knowledgeKind }])
-            }), 'memory_context');
-            expect(await tool.execute({ from: { id: 'turn-0', scope: 'conversations/conv-a' } })).toSucceedAndSatisfy((value) => {
-                const out = value;
-                expect(out.results).toHaveLength(1);
-                expect(out.results[0].tags).toEqual(['in-a']);
-            });
-        });
-        test('rejects malformed arguments', async () => {
-            const tool = toolByName(allTools(), 'memory_context');
-            expect(await tool.execute({ hops: 1 })).toFailWith(/invalid arguments/i);
-        });
-    });
-    describe('memory_delete', () => {
-        test('deletes an existing record', async () => {
-            const store = makeStore();
-            const tools = createMemoryTools({
-                store,
-                retriever: makeRetriever([]),
-                registry: registryWith([{ kind: knowledgeKind }]),
-                codecs,
-                tools: ['memory_write', 'memory_delete', 'memory_read']
-            });
-            await toolByName(tools, 'memory_write').execute({ kind: 'knowledge', entityId: 'doc-1', body: 'b' });
-            expect(await toolByName(tools, 'memory_delete').execute({ kind: 'knowledge', entityId: 'doc-1' })).toSucceedWith({ deleted: true, id: 'doc-1', entityId: 'doc-1', kind: 'knowledge' });
-            expect(await toolByName(tools, 'memory_read').execute({ kind: 'knowledge', entityId: 'doc-1' })).toSucceedWith({ found: false });
-        });
-        test('propagates a store failure when the record is absent', async () => {
-            const tool = toolByName(allTools(), 'memory_delete');
-            expect(await tool.execute({ kind: 'knowledge', entityId: 'missing' })).toFailWith(/no record found/i);
-        });
-        test('rejects a kind outside the whitelist', async () => {
-            const tool = toolByName(allTools({ kinds: [knowledgeKind] }), 'memory_delete');
-            expect(await tool.execute({ kind: 'mtm', entityId: 'conv-1:0' })).toFailWith(/not enabled/i);
-        });
-        test('rejects malformed arguments', async () => {
-            const tool = toolByName(allTools(), 'memory_delete');
-            expect(await tool.execute({ kind: 'knowledge' })).toFailWith(/invalid arguments/i);
-        });
-    });
-});
-describe('result projection (projectItem host projector + detail tier)', () => {
-    /**
-     * A host projector that bounds the `'gist'` body to a sentinel and passes the
-     * full body through only for `'full'` — the shape a real host uses to keep the
-     * default (gist) path bounded.
-     */
-    const boundingProjector = (record, detail) => ({
-        handle: `h:${record.envelope.id}`,
-        kind: record.envelope.kind,
-        entityId: record.envelope.entityId,
-        tags: record.envelope.tags,
-        body: detail === 'full' ? record.body : '<<gist>>'
-    });
-    function searchToolWith(overrides) {
-        return toolByName(createMemoryTools(Object.assign({ store: makeStore(), retriever: makeRetriever([{ id: 'doc-1', tags: ['topic'] }]), registry: registryWith([{ kind: knowledgeKind }]) }, overrides)), 'memory_search');
-    }
-    describe('schema surface', () => {
-        test('memory_search declares optional detail + offset properties', () => {
-            const props = schemaProperties(toolByName(allTools(), 'memory_search'));
-            expect(props).toContain('detail');
-            expect(props).toContain('offset');
-        });
-        test('memory_context declares an optional detail property', () => {
-            const props = schemaProperties(toolByName(allTools(), 'memory_context'));
-            expect(props).toContain('detail');
-        });
-        test('memory_read declares an optional detail property', () => {
-            const props = schemaProperties(toolByName(allTools(), 'memory_read'));
-            expect(props).toContain('detail');
-        });
-        test('memory_search accepts detail and offset, and rejects an out-of-enum detail', () => {
-            const schema = toolByName(allTools(), 'memory_search').config.parametersSchema;
-            expect(schema.convert({ detail: 'full', offset: 2 })).toSucceed();
-            expect(schema.convert({ detail: 'gist' })).toSucceed();
-            expect(schema.convert({ offset: 'nope' })).toFail();
-            // detail is now an enum ('gist' | 'full') at the wire-schema level.
-            expect(schema.convert({ detail: 'verbose' })).toFail();
-        });
-    });
-    describe('absent projector = byte-identical default projection', () => {
-        test('returns the full body and the default handle (raw id) when no projector is supplied', async () => {
-            const tool = searchToolWith({});
-            expect(await tool.execute({ tag: 'topic' })).toSucceedAndSatisfy((value) => {
-                const out = value;
-                expect(out.results[0].handle).toBe('doc-1');
-                expect(out.results[0].body).toBe('body-doc-1');
-            });
-        });
-        test('the detail tier is inert without a projector (gist and full both yield the full body)', async () => {
-            const tool = searchToolWith({});
-            for (const detail of ['gist', 'full']) {
-                expect(await tool.execute({ tag: 'topic', detail })).toSucceedAndSatisfy((value) => {
-                    expect(value.results[0].body).toBe('body-doc-1');
-                });
-            }
-        });
-    });
-    describe('host projector + detail tier', () => {
-        test('defaults to the bounded gist projection when detail is absent', async () => {
-            const tool = searchToolWith({ projectItem: boundingProjector });
-            expect(await tool.execute({ tag: 'topic' })).toSucceedAndSatisfy((value) => {
-                const out = value;
-                expect(out.results[0].handle).toBe('h:doc-1');
-                expect(out.results[0].body).toBe('<<gist>>');
-            });
-        });
-        test('opts into the full body only when detail=full is requested', async () => {
-            const tool = searchToolWith({ projectItem: boundingProjector });
-            expect(await tool.execute({ tag: 'topic', detail: 'full' })).toSucceedAndSatisfy((value) => {
-                expect(value.results[0].body).toBe('body-doc-1');
-            });
-        });
-        test('an out-of-enum detail is rejected at the schema boundary', async () => {
-            // detail is a JsonSchema.enumOf(['gist','full']); the tool re-validates args
-            // on execute, so an out-of-enum value fails loudly rather than reaching the projector.
-            const tool = searchToolWith({ projectItem: boundingProjector });
-            expect(await tool.execute({ tag: 'topic', detail: 'verbose' })).toFailWith(/invalid arguments/i);
-        });
-        test('an explicit detail=gist stays bounded (the non-full branch)', async () => {
-            const tool = searchToolWith({ projectItem: boundingProjector });
-            expect(await tool.execute({ tag: 'topic', detail: 'gist' })).toSucceedAndSatisfy((value) => {
-                expect(value.results[0].body).toBe('<<gist>>');
-            });
-        });
-        test('memory_context routes its results through the host projector', async () => {
-            const tool = toolByName(createMemoryTools({
-                store: makeStore(),
-                retriever: makeLinkRetriever([{ id: 'a', links: ['b'] }, { id: 'b' }]),
-                registry: registryWith([{ kind: knowledgeKind }]),
-                projectItem: boundingProjector
-            }), 'memory_context');
-            expect(await tool.execute({ from: { id: 'a', scope: 'knowledge' }, detail: 'full' })).toSucceedAndSatisfy((value) => {
-                const out = value;
-                expect(out.results.map((r) => r.handle)).toEqual(['h:b']);
-                expect(out.results[0].body).toBe('body-b');
-            });
-        });
-        test('a throwing host projector degrades to the default full-body projection (does not crash search)', async () => {
-            const tool = searchToolWith({
-                projectItem: () => {
-                    throw new Error('host projector blew up');
-                }
-            });
-            expect(await tool.execute({ tag: 'topic' })).toSucceedAndSatisfy((value) => {
-                const out = value;
-                // Degraded to the built-in default: raw-id handle + full body.
-                expect(out.results[0].handle).toBe('doc-1');
-                expect(out.results[0].body).toBe('body-doc-1');
-            });
-        });
-        test('a throwing projector still honors the handleFor hook in the fallback path', async () => {
-            const tool = searchToolWith({
-                handleFor: (r) => `@${r.envelope.id}`,
-                projectItem: () => {
-                    throw new Error('nope');
-                }
-            });
-            expect(await tool.execute({ tag: 'topic' })).toSucceedAndSatisfy((value) => {
-                expect(value.results[0].handle).toBe('@doc-1');
-            });
-        });
-    });
-    describe('offset threading (memory_search)', () => {
-        test('threads offset into the query to page the ordered result window', async () => {
-            const tool = toolByName(createMemoryTools({
-                store: makeStore(),
-                retriever: makeRetriever([
-                    { id: 'doc-1', tags: ['topic'], updated: 30 },
-                    { id: 'doc-2', tags: ['topic'], updated: 20 },
-                    { id: 'doc-3', tags: ['topic'], updated: 10 }
-                ]),
-                registry: registryWith([{ kind: knowledgeKind }])
-            }), 'memory_search');
-            // Recency-ordered [doc-1, doc-2, doc-3]; offset 1 + limit 1 → [doc-2].
-            expect(await tool.execute({ tag: 'topic', offset: 1, limit: 1 })).toSucceedAndSatisfy((value) => {
-                const out = value;
-                expect(out.count).toBe(1);
-                expect(out.results.map((r) => r.handle)).toEqual(['doc-2']);
-            });
-        });
-    });
-    describe('memory_read detail (explicit drill-in defaults to FULL)', () => {
-        async function readToolWith(projector) {
-            const tools = createMemoryTools(Object.assign({ store: makeStore(), retriever: makeRetriever([]), registry: registryWith([{ kind: knowledgeKind }]), codecs, tools: ['memory_write', 'memory_read'] }, (projector !== undefined ? { projectItem: projector } : {})));
-            await toolByName(tools, 'memory_write').execute({
-                kind: 'knowledge',
-                entityId: 'doc-1',
-                body: 'FULLBODY'
-            });
-            return toolByName(tools, 'memory_read');
-        }
-        test('defaults to the FULL body (drill-in) with a bounding projector', async () => {
-            const tool = await readToolWith(boundingProjector);
-            expect(await tool.execute({ kind: 'knowledge', entityId: 'doc-1' })).toSucceedAndSatisfy((value) => {
-                expect(value.item.body).toBe('FULLBODY');
-            });
-        });
-        test('opts down to gist only when detail=gist is requested', async () => {
-            const tool = await readToolWith(boundingProjector);
-            expect(await tool.execute({ kind: 'knowledge', entityId: 'doc-1', detail: 'gist' })).toSucceedAndSatisfy((value) => {
-                expect(value.item.body).toBe('<<gist>>');
-            });
-        });
-        test('is byte-identical for a no-projector consumer (full body regardless of detail)', async () => {
-            const tool = await readToolWith(undefined);
-            for (const args of [
-                { kind: 'knowledge', entityId: 'doc-1' },
-                { kind: 'knowledge', entityId: 'doc-1', detail: 'gist' }
-            ]) {
-                expect(await tool.execute(args)).toSucceedAndSatisfy((value) => {
-                    expect(value.item.body).toBe('FULLBODY');
-                });
-            }
-        });
-    });
-});
-//# sourceMappingURL=memoryTools.test.js.map