@fgv/ts-agent-memory 5.1.0-37 → 5.1.0-39

package/dist/test/unit/ingest/orchestrator.test.js

@@ -0,0 +1,913 @@
+/*
+ * 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, CONTRADICTS_LINK_TYPE, DEFAULT_SIMILARITY_THRESHOLD, DEFAULT_SIMILARITY_TOP_K, FileTreeMemoryStore, HOST_INGEST_PROVENANCE_SOURCE, InMemoryCosineIndex, KnowledgeIdentityCodec, LtmIdentityCodec, MemoryIngestOrchestrator, TemporalIdentityCodec, TemporalVersionedPolicy, serializeMemoryFile } from '../../../index';
+// --- kinds --------------------------------------------------------------------
+const noteKind = 'note';
+const factKind = 'fact';
+const numKind = 'num';
+const orphanKind = 'orphan';
+const ltmKind = 'ltm';
+// --- shared fixtures ----------------------------------------------------------
+let clockValue;
+const clock = () => clockValue;
+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 registry() {
+    const reg = BodyConverterRegistry.create().orThrow();
+    reg.register(noteKind, Converters.string);
+    reg.register(factKind, Converters.string);
+    reg.register(numKind, Converters.number);
+    reg.register(orphanKind, Converters.string);
+    reg.register(ltmKind, Converters.string);
+    return reg;
+}
+const codecs = new Map([
+    [noteKind, new KnowledgeIdentityCodec()],
+    [numKind, new KnowledgeIdentityCodec()],
+    [ltmKind, new LtmIdentityCodec()],
+    [factKind, TemporalIdentityCodec.create('facts').orThrow()]
+]);
+const policies = new Map([
+    [factKind, TemporalVersionedPolicy.create().orThrow()]
+]);
+// A deterministic embedder keyed by body text (three-dimensional vectors so
+// cosine relationships are controllable). Unknown bodies map to a distinct axis.
+const VECTORS = new Map([
+    ['apple pie', [1, 0, 0]],
+    ['apple tart', [0.99, 0.14, 0]],
+    ['banana bread', [0, 1, 0]]
+]);
+const embed = (record) => {
+    var _a;
+    if (record.body === 'boom') {
+        return Promise.resolve(fail('embed boom'));
+    }
+    const vec = (_a = VECTORS.get(record.body)) !== null && _a !== void 0 ? _a : [0, 0, 1];
+    return Promise.resolve(succeed(Float32Array.from(vec)));
+};
+// --- mock host stages ---------------------------------------------------------
+function classifier(fn) {
+    return { classify: (item) => Promise.resolve(fn(item)) };
+}
+function throwingClassifier() {
+    return {
+        classify: () => {
+            throw new Error('classifier boom');
+        }
+    };
+}
+function extractor(fn) {
+    return { extract: (item, c) => Promise.resolve(fn(item, c)) };
+}
+function resolver(fn) {
+    return { resolve: (candidate, similar) => Promise.resolve(fn(candidate, similar)) };
+}
+function relater(fn) {
+    return { relate: (ctx) => Promise.resolve(fn(ctx)) };
+}
+const noEdges = relater(() => succeed([]));
+const classifyNote = classifier(() => succeed({ kind: noteKind, confidence: 0.9 }));
+/** Extractor that emits one note candidate per item, body = item.content, entityId = item.id. */
+function oneNoteExtractor() {
+    return extractor((item) => succeed([candidate(noteKind, item.id, item.content)]));
+}
+function candidate(kind, entityId, body, opts = {}) {
+    var _a, _b, _c;
+    return {
+        envelope: Object.assign({ entityId: entityId, kind, tags: ((_a = opts.tags) !== null && _a !== void 0 ? _a : []), links: (_b = opts.links) !== null && _b !== void 0 ? _b : [], provenance: (_c = opts.provenance) !== null && _c !== void 0 ? _c : { source: 'agent' } }, (opts.temporal !== undefined ? { temporal: opts.temporal } : {})),
+        body
+    };
+}
+function candEdge(source, type, target, confidence) {
+    return {
+        source: source,
+        edge: Object.assign({ type: type, target: target }, (confidence !== undefined ? { confidence } : {}))
+    };
+}
+function buildStore(params = {}) {
+    var _a;
+    return FileTreeMemoryStore.create({
+        root: mutableRoot(params.files),
+        registry: (_a = params.registry) !== null && _a !== void 0 ? _a : registry(),
+        codecs,
+        writePolicies: policies,
+        clock,
+        vectorIndex: params.vectorIndex,
+        embed: params.embed
+    }).orThrow();
+}
+function buildOrchestrator(params) {
+    var _a, _b, _c, _d;
+    return MemoryIngestOrchestrator.create({
+        store: params.store,
+        registry: (_a = params.registry) !== null && _a !== void 0 ? _a : registry(),
+        codecs,
+        classifier: (_b = params.classifier) !== null && _b !== void 0 ? _b : classifyNote,
+        extractor: (_c = params.extractor) !== null && _c !== void 0 ? _c : oneNoteExtractor(),
+        relationExtractor: (_d = params.relationExtractor) !== null && _d !== void 0 ? _d : noEdges,
+        entityResolver: params.entityResolver,
+        vectorIndex: params.vectorIndex,
+        embed: params.embed,
+        similarityThreshold: params.similarityThreshold,
+        cycleGuard: params.cycleGuard
+    }).orThrow();
+}
+/** A seeded note file with only `source` provenance (the additive-provenance baseline). */
+function seedNote(id, body, provenance = { source: 'agent' }) {
+    const envelope = {
+        id: id,
+        entityId: id,
+        kind: noteKind,
+        tags: [],
+        links: [],
+        created: 1,
+        updated: 1,
+        seq: 4,
+        contentHash: 'seed',
+        provenance: provenance
+    };
+    return { path: `knowledge/${id}.md`, contents: serializeMemoryFile(envelope, body).orThrow() };
+}
+beforeEach(() => {
+    clockValue = 1000;
+});
+describe('MemoryIngestOrchestrator', () => {
+    describe('create', () => {
+        test('constructs via the factory', () => {
+            expect(MemoryIngestOrchestrator.create({
+                store: buildStore(),
+                registry: registry(),
+                codecs,
+                classifier: classifyNote,
+                extractor: oneNoteExtractor(),
+                relationExtractor: noEdges
+            })).toSucceed();
+        });
+        test('exposes the documented similarity defaults', () => {
+            expect(DEFAULT_SIMILARITY_THRESHOLD).toBe(0.85);
+            expect(DEFAULT_SIMILARITY_TOP_K).toBe(5);
+        });
+    });
+    describe('single-item ingest (first-class path)', () => {
+        test('classifies, extracts, and writes one record end-to-end with host-ingest provenance + derivedFrom', async () => {
+            const store = buildStore();
+            const orch = buildOrchestrator({ store });
+            const sourceId = 'turn-3';
+            const result = await orch.ingestItem({ id: 'doc-1', content: 'the sky is blue', sourceId });
+            expect(result).toSucceedAndSatisfy((r) => {
+                var _a, _b, _c;
+                expect(r.item.id).toBe('doc-1');
+                expect(r.records).toHaveLength(1);
+                const rec = r.records[0];
+                expect(rec.disposition).toBe('written');
+                expect(rec.resolution.verdict).toBe('new');
+                expect(rec.id).toBe('doc-1');
+                expect((_a = rec.record) === null || _a === void 0 ? void 0 : _a.envelope.provenance.source).toBe(HOST_INGEST_PROVENANCE_SOURCE);
+                expect((_b = rec.record) === null || _b === void 0 ? void 0 : _b.envelope.provenance.derivedFrom).toBe('turn-3');
+                expect((_c = rec.record) === null || _c === void 0 ? void 0 : _c.body).toBe('the sky is blue');
+                expect(rec.interlock).toBeUndefined();
+            });
+            expect(await store.get(noteKind, 'doc-1')).toSucceedAndSatisfy((rec) => {
+                expect(rec === null || rec === void 0 ? void 0 : rec.body).toBe('the sky is blue');
+            });
+        });
+        test('omits derivedFrom when the item carries no sourceId', async () => {
+            const store = buildStore();
+            const orch = buildOrchestrator({ store });
+            const result = await orch.ingestItem({ id: 'doc-1', content: 'a fact' });
+            expect(result).toSucceedAndSatisfy((r) => {
+                var _a, _b;
+                expect((_a = r.records[0].record) === null || _a === void 0 ? void 0 : _a.envelope.provenance.derivedFrom).toBeUndefined();
+                expect((_b = r.records[0].record) === null || _b === void 0 ? void 0 : _b.envelope.provenance.source).toBe(HOST_INGEST_PROVENANCE_SOURCE);
+            });
+        });
+        test('yields an empty record set when the extractor finds nothing memorable', async () => {
+            const store = buildStore();
+            const orch = buildOrchestrator({ store, extractor: extractor(() => succeed([])) });
+            expect(await orch.ingestItem({ id: 'doc-1', content: 'noise' })).toSucceedAndSatisfy((r) => {
+                expect(r.records).toEqual([]);
+            });
+        });
+    });
+    describe('host-stage failures abort loudly', () => {
+        test('classifier failure', async () => {
+            const orch = buildOrchestrator({
+                store: buildStore(),
+                classifier: classifier(() => fail('cannot classify'))
+            });
+            expect(await orch.ingestItem({ id: 'doc-1', content: 'x' })).toFailWith(/cannot classify/);
+        });
+        test('classifier throw is captured as a failure', async () => {
+            const orch = buildOrchestrator({ store: buildStore(), classifier: throwingClassifier() });
+            expect(await orch.ingestItem({ id: 'doc-1', content: 'x' })).toFailWith(/classify threw.*classifier boom/);
+        });
+        test('extractor failure', async () => {
+            const orch = buildOrchestrator({
+                store: buildStore(),
+                extractor: extractor(() => fail('extract error'))
+            });
+            expect(await orch.ingestItem({ id: 'doc-1', content: 'x' })).toFailWith(/extract error/);
+        });
+        test('relation-extractor failure', async () => {
+            const orch = buildOrchestrator({
+                store: buildStore(),
+                relationExtractor: relater(() => fail('relate error'))
+            });
+            expect(await orch.ingestItem({ id: 'doc-1', content: 'x' })).toFailWith(/relate error/);
+        });
+    });
+    describe('stage 3b — typed validation boundary', () => {
+        test('rejects a candidate whose body fails the kind converter', async () => {
+            const orch = buildOrchestrator({
+                store: buildStore(),
+                extractor: extractor(() => succeed([candidate(noteKind, 'doc-1', 42)]))
+            });
+            expect(await orch.ingestItem({ id: 'doc-1', content: 'x' })).toFailWith(/candidate body for kind 'note' is invalid/);
+        });
+        test('rejects a non-string body even when the converter accepts it', async () => {
+            const orch = buildOrchestrator({
+                store: buildStore(),
+                extractor: extractor(() => succeed([candidate(numKind, 'n-1', 42)]))
+            });
+            expect(await orch.ingestItem({ id: 'n-1', content: 'x' })).toFailWith(/must be a string/);
+        });
+        test('fails when no identity codec is registered for the candidate kind', async () => {
+            const orch = buildOrchestrator({
+                store: buildStore(),
+                extractor: extractor(() => succeed([candidate(orphanKind, 'o-1', 'body')]))
+            });
+            expect(await orch.ingestItem({ id: 'o-1', content: 'x' })).toFailWith(/no identity codec/);
+        });
+    });
+    describe('stage 4 — exact dedup (layer 1)', () => {
+        test('an exact {kind,body} match in scope is duplicate-of (no resolver)', async () => {
+            const store = buildStore({ files: [seedNote('doc-a', 'hello')] });
+            const orch = buildOrchestrator({
+                store,
+                extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'hello')]))
+            });
+            expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+                expect(r.records[0].disposition).toBe('deduped');
+                expect(r.records[0].resolution).toEqual({ verdict: 'duplicate-of', target: 'doc-a' });
+                expect(r.records[0].id).toBe('doc-a');
+            });
+            // doc-b was never written.
+            expect(await store.get(noteKind, 'doc-b')).toSucceedWith(undefined);
+        });
+        test('exact dedup takes precedence over the resolver (resolver never called)', async () => {
+            const vectorIndex = InMemoryCosineIndex.create().orThrow();
+            const store = buildStore({ files: [seedNote('doc-a', 'hello')] });
+            const orch = buildOrchestrator({
+                store,
+                entityResolver: resolver(() => fail('resolver must not be called')),
+                vectorIndex,
+                embed,
+                extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'hello')]))
+            });
+            expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+                expect(r.records[0].disposition).toBe('deduped');
+            });
+        });
+        test('a distinct body is a fresh write (no resolver → exact-only fall-back)', async () => {
+            const store = buildStore({ files: [seedNote('doc-a', 'hello')] });
+            const orch = buildOrchestrator({
+                store,
+                extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'goodbye')]))
+            });
+            expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+                expect(r.records[0].disposition).toBe('written');
+                expect(r.records[0].resolution.verdict).toBe('new');
+            });
+        });
+    });
+});
+// --- similarity + resolver fixtures ------------------------------------------
+const classifyFact = classifier(() => succeed({ kind: factKind }));
+function oneFactExtractor() {
+    return extractor((item) => succeed([candidate(factKind, item.id, item.content)]));
+}
+async function putNote(store, id, body) {
+    const rec = {
+        envelope: {
+            id: id,
+            entityId: id,
+            kind: noteKind,
+            tags: [],
+            links: [],
+            created: 0,
+            updated: 0,
+            seq: 0,
+            contentHash: '',
+            provenance: { source: 'agent' }
+        },
+        body
+    };
+    (await store.put(rec)).orThrow();
+}
+function mockStore(overrides) {
+    var _a, _b, _c, _d, _e;
+    return {
+        get: (_a = overrides.get) !== null && _a !== void 0 ? _a : (() => Promise.resolve(succeed(undefined))),
+        getById: (_b = overrides.getById) !== null && _b !== void 0 ? _b : (() => Promise.resolve(succeed(undefined))),
+        list: (_c = overrides.list) !== null && _c !== void 0 ? _c : (() => Promise.resolve(succeed([]))),
+        put: (_d = overrides.put) !== null && _d !== void 0 ? _d : ((r) => Promise.resolve(succeed(r))),
+        delete: (_e = overrides.delete) !== null && _e !== void 0 ? _e : (() => Promise.resolve(fail('n/a')))
+    };
+}
+describe('MemoryIngestOrchestrator — stage 4 similarity (layer 2)', () => {
+    test('resolver verdict new writes the candidate despite a near-duplicate', async () => {
+        const vectorIndex = InMemoryCosineIndex.create().orThrow();
+        const store = buildStore({ vectorIndex, embed });
+        await putNote(store, 'doc-a', 'apple pie');
+        const orch = buildOrchestrator({
+            store,
+            vectorIndex,
+            embed,
+            entityResolver: resolver(() => succeed({ verdict: 'new' })),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'apple tart')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+            expect(r.records[0].disposition).toBe('written');
+            expect(r.records[0].resolution.verdict).toBe('new');
+        });
+    });
+    test('resolver verdict duplicate-of dedups against the surfaced neighbor', async () => {
+        const vectorIndex = InMemoryCosineIndex.create().orThrow();
+        const store = buildStore({ vectorIndex, embed });
+        await putNote(store, 'doc-a', 'apple pie');
+        const orch = buildOrchestrator({
+            store,
+            vectorIndex,
+            embed,
+            entityResolver: resolver((__c, similar) => succeed({ verdict: 'duplicate-of', target: similar[0].id })),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'apple tart')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+            expect(r.records[0].disposition).toBe('deduped');
+            expect(r.records[0].id).toBe('doc-a');
+        });
+        expect(await store.get(noteKind, 'doc-b')).toSucceedWith(undefined);
+    });
+    test('resolver verdict supersede writes the candidate and records the superseded target', async () => {
+        const vectorIndex = InMemoryCosineIndex.create().orThrow();
+        const store = buildStore({ vectorIndex, embed });
+        await putNote(store, 'doc-a', 'apple pie');
+        const orch = buildOrchestrator({
+            store,
+            vectorIndex,
+            embed,
+            entityResolver: resolver((__c, similar) => succeed({ verdict: 'supersede', target: similar[0].id })),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'apple tart')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+            expect(r.records[0].disposition).toBe('written');
+            expect(r.records[0].resolution).toEqual({ verdict: 'supersede', target: 'doc-a' });
+            expect(r.records[0].id).toBe('doc-b');
+        });
+        expect(await store.get(noteKind, 'doc-b')).toSucceedAndSatisfy((rec) => expect(rec === null || rec === void 0 ? void 0 : rec.body).toBe('apple tart'));
+    });
+    test('resolver verdict merge-into re-addresses the write to the target entity', async () => {
+        const vectorIndex = InMemoryCosineIndex.create().orThrow();
+        const store = buildStore({ vectorIndex, embed });
+        await putNote(store, 'doc-a', 'apple pie');
+        const orch = buildOrchestrator({
+            store,
+            vectorIndex,
+            embed,
+            entityResolver: resolver((__c, similar) => succeed({ verdict: 'merge-into', target: similar[0].id })),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'apple tart')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+            expect(r.records[0].disposition).toBe('merged');
+            expect(r.records[0].id).toBe('doc-a');
+        });
+        // The merge updated doc-a's body (LWW merge patch) and never minted doc-b.
+        expect(await store.get(noteKind, 'doc-a')).toSucceedAndSatisfy((rec) => expect(rec === null || rec === void 0 ? void 0 : rec.body).toBe('apple tart'));
+        expect(await store.get(noteKind, 'doc-b')).toSucceedWith(undefined);
+    });
+    test('merge-into with a non-existent target fails loudly', async () => {
+        const vectorIndex = InMemoryCosineIndex.create().orThrow();
+        const store = buildStore({ vectorIndex, embed });
+        await putNote(store, 'doc-a', 'apple pie');
+        const orch = buildOrchestrator({
+            store,
+            vectorIndex,
+            embed,
+            entityResolver: resolver(() => succeed({ verdict: 'merge-into', target: 'ghost' })),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'apple tart')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toFailWith(/merge-into target 'ghost' does not exist/);
+    });
+    test('a below-threshold neighbor is not surfaced (resolver not called)', async () => {
+        const vectorIndex = InMemoryCosineIndex.create().orThrow();
+        const store = buildStore({ vectorIndex, embed });
+        await putNote(store, 'doc-a', 'apple pie');
+        const orch = buildOrchestrator({
+            store,
+            vectorIndex,
+            embed,
+            entityResolver: resolver(() => fail('resolver must not be called')),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'banana bread')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+            expect(r.records[0].resolution.verdict).toBe('new');
+        });
+    });
+    test('the candidate self-hit is excluded from surfaced neighbors', async () => {
+        const vectorIndex = InMemoryCosineIndex.create().orThrow();
+        const store = buildStore({ vectorIndex, embed });
+        await putNote(store, 'doc-a', 'apple pie');
+        const orch = buildOrchestrator({
+            store,
+            vectorIndex,
+            embed,
+            entityResolver: resolver(() => fail('resolver must not be called')),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-a', 'apple tart')]))
+        });
+        // Re-ingesting the SAME entity: its own prior vector is the only over-threshold
+        // hit, and it is skipped as the self-hit, so no resolver dispatch occurs.
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+            expect(r.records[0].resolution.verdict).toBe('new');
+            expect(r.records[0].disposition).toBe('written');
+        });
+    });
+    test('a surfaced hit with no backing record is skipped', async () => {
+        const ghostIndex = {
+            add: (id) => Promise.resolve(succeed(id)),
+            remove: (id) => Promise.resolve(succeed(id)),
+            query: () => Promise.resolve(succeed([{ id: 'ghost', score: 0.99 }]))
+        };
+        const orch = buildOrchestrator({
+            store: buildStore(),
+            vectorIndex: ghostIndex,
+            embed,
+            entityResolver: resolver(() => fail('resolver must not be called')),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'apple tart')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+            expect(r.records[0].resolution.verdict).toBe('new');
+        });
+    });
+    test('an embedder failure surfaces loudly', async () => {
+        const vectorIndex = InMemoryCosineIndex.create().orThrow();
+        const orch = buildOrchestrator({
+            store: buildStore(),
+            vectorIndex,
+            embed,
+            entityResolver: resolver(() => succeed({ verdict: 'new' })),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'boom')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toFailWith(/embed boom/);
+    });
+    test('a similarity-query failure surfaces loudly', async () => {
+        const failingIndex = {
+            add: (id) => Promise.resolve(succeed(id)),
+            remove: (id) => Promise.resolve(succeed(id)),
+            query: () => Promise.resolve(fail('query kaput'))
+        };
+        const orch = buildOrchestrator({
+            store: buildStore(),
+            vectorIndex: failingIndex,
+            embed,
+            entityResolver: resolver(() => succeed({ verdict: 'new' })),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'apple tart')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toFailWith(/query kaput/);
+    });
+    test('a custom similarityThreshold gates the resolver dispatch', async () => {
+        const vectorIndex = InMemoryCosineIndex.create().orThrow();
+        const store = buildStore({ vectorIndex, embed });
+        await putNote(store, 'doc-a', 'apple pie');
+        const orch = buildOrchestrator({
+            store,
+            vectorIndex,
+            embed,
+            similarityThreshold: 0.999, // 0.99 neighbor now falls below threshold
+            entityResolver: resolver(() => fail('resolver must not be called')),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'apple tart')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+            expect(r.records[0].resolution.verdict).toBe('new');
+        });
+    });
+});
+describe('MemoryIngestOrchestrator — layer-2 wiring gates (exact-only fall-back)', () => {
+    const failResolver = resolver(() => fail('resolver must not be called'));
+    const almostSimilar = extractor(() => succeed([candidate(noteKind, 'doc-b', 'apple tart')]));
+    test('no resolver → exact-only', async () => {
+        const vectorIndex = InMemoryCosineIndex.create().orThrow();
+        const store = buildStore({ vectorIndex, embed });
+        await putNote(store, 'doc-a', 'apple pie');
+        const orch = buildOrchestrator({ store, vectorIndex, embed, extractor: almostSimilar });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => expect(r.records[0].resolution.verdict).toBe('new'));
+    });
+    test('resolver + embed but no vector index → exact-only', async () => {
+        const orch = buildOrchestrator({
+            store: buildStore(),
+            embed,
+            entityResolver: failResolver,
+            extractor: almostSimilar
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => expect(r.records[0].resolution.verdict).toBe('new'));
+    });
+    test('resolver + vector index but no embedder → exact-only', async () => {
+        const vectorIndex = InMemoryCosineIndex.create().orThrow();
+        const orch = buildOrchestrator({
+            store: buildStore(),
+            vectorIndex,
+            entityResolver: failResolver,
+            extractor: almostSimilar
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => expect(r.records[0].resolution.verdict).toBe('new'));
+    });
+});
+describe('MemoryIngestOrchestrator — stage 5 relate + cycle guard', () => {
+    test('attaches a valid edge to an existing record', async () => {
+        const store = buildStore();
+        await putNote(store, 'doc-a', 'anchor');
+        const orch = buildOrchestrator({
+            store,
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'goodbye')])),
+            relationExtractor: relater(() => succeed([candEdge('doc-b', 'mentions', 'doc-a', 0.7)]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+            var _a;
+            expect(r.records[0].edges).toHaveLength(1);
+            expect((_a = r.records[0].record) === null || _a === void 0 ? void 0 : _a.envelope.links).toEqual([
+                { type: 'mentions', target: 'doc-a', confidence: 0.7 }
+            ]);
+        });
+    });
+    test('attaches an edge between two sibling candidates', async () => {
+        const orch = buildOrchestrator({
+            store: buildStore(),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'first'), candidate(noteKind, 'doc-c', 'second')])),
+            relationExtractor: relater(() => succeed([candEdge('doc-b', 'rel', 'doc-c')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+            var _a;
+            expect(r.records).toHaveLength(2);
+            expect((_a = r.records[0].record) === null || _a === void 0 ? void 0 : _a.envelope.links).toEqual([{ type: 'rel', target: 'doc-c' }]);
+            expect(r.records[1].edges).toEqual([]);
+        });
+    });
+    test('rejects an edge whose source is not a candidate being written', async () => {
+        const orch = buildOrchestrator({
+            store: buildStore(),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'x')])),
+            relationExtractor: relater(() => succeed([candEdge('ghost', 'rel', 'doc-b')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toFailWith(/edge source 'ghost' is not a candidate being written/);
+    });
+    test('rejects an edge whose target resolves to nothing', async () => {
+        const orch = buildOrchestrator({
+            store: buildStore(),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'x')])),
+            relationExtractor: relater(() => succeed([candEdge('doc-b', 'rel', 'ghost')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toFailWith(/edge target 'ghost' resolves to neither/);
+    });
+    test('rejects a cycle-inducing edge (default guard)', async () => {
+        const orch = buildOrchestrator({
+            store: buildStore(),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'first'), candidate(noteKind, 'doc-c', 'second')])),
+            relationExtractor: relater(() => succeed([candEdge('doc-b', 'rel', 'doc-c'), candEdge('doc-c', 'rel', 'doc-b')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toFailWith(/would create a cycle/);
+    });
+    test('cycleGuard "off" admits an otherwise-cyclic edge set', async () => {
+        const orch = buildOrchestrator({
+            store: buildStore(),
+            cycleGuard: 'off',
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'first'), candidate(noteKind, 'doc-c', 'second')])),
+            relationExtractor: relater(() => succeed([candEdge('doc-b', 'rel', 'doc-c'), candEdge('doc-c', 'rel', 'doc-b')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+            var _a, _b;
+            expect((_a = r.records[0].record) === null || _a === void 0 ? void 0 : _a.envelope.links).toEqual([{ type: 'rel', target: 'doc-c' }]);
+            expect((_b = r.records[1].record) === null || _b === void 0 ? void 0 : _b.envelope.links).toEqual([{ type: 'rel', target: 'doc-b' }]);
+        });
+    });
+    test('a contradicts edge on a NON-temporal kind persists as a plain link (no interlock)', async () => {
+        const store = buildStore();
+        await putNote(store, 'doc-a', 'anchor');
+        const orch = buildOrchestrator({
+            store,
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'goodbye')])),
+            relationExtractor: relater(() => succeed([candEdge('doc-b', 'contradicts', 'doc-a')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+            var _a;
+            expect(r.records[0].interlock).toBeUndefined();
+            expect((_a = r.records[0].record) === null || _a === void 0 ? void 0 : _a.envelope.links).toEqual([{ type: 'contradicts', target: 'doc-a' }]);
+        });
+    });
+});
+describe('MemoryIngestOrchestrator — contradicts→temporal interlock', () => {
+    test('a contradicts edge on a temporal kind invalidates the prior version and writes a new one', async () => {
+        const store = buildStore();
+        const firstOrch = buildOrchestrator({
+            store,
+            classifier: classifyFact,
+            extractor: oneFactExtractor()
+        });
+        clockValue = 1000;
+        const first = await firstOrch.ingestItem({ id: 'fact-1', content: 'the sky is blue' });
+        const v1Id = first.orThrow().records[0].id;
+        expect(v1Id).toBe('fact-1-v1');
+        clockValue = 2000;
+        const secondOrch = buildOrchestrator({
+            store,
+            classifier: classifyFact,
+            extractor: extractor(() => succeed([candidate(factKind, 'fact-1', 'the sky is grey')])),
+            relationExtractor: relater(() => succeed([candEdge('fact-1', 'contradicts', v1Id)]))
+        });
+        expect(await secondOrch.ingestItem({ id: 'fact-1', content: 'the sky is grey' })).toSucceedAndSatisfy((r) => {
+            var _a;
+            expect(r.records[0].interlock).toBe('temporal-versioned');
+            expect(r.records[0].disposition).toBe('written');
+            expect((_a = r.records[0].record) === null || _a === void 0 ? void 0 : _a.envelope.links).toEqual([{ type: CONTRADICTS_LINK_TYPE, target: v1Id }]);
+        });
+        // The current version is the new (contradicting) one.
+        expect(await store.get(factKind, 'fact-1')).toSucceedAndSatisfy((rec) => expect(rec === null || rec === void 0 ? void 0 : rec.body).toBe('the sky is grey'));
+        // The prior version is invalidated (invalidate-don't-delete).
+        expect(await store.list()).toSucceedAndSatisfy((all) => {
+            var _a;
+            const v1 = all.find((rec) => rec.envelope.id === v1Id);
+            expect((_a = v1 === null || v1 === void 0 ? void 0 : v1.envelope.temporal) === null || _a === void 0 ? void 0 : _a.invalid_at).toBe(2000);
+        });
+    });
+    test('an invalidated version does not exact-dedup a later candidate that repeats its body', async () => {
+        const store = buildStore();
+        clockValue = 1000;
+        const o1 = buildOrchestrator({ store, classifier: classifyFact, extractor: oneFactExtractor() });
+        const first = await o1.ingestItem({ id: 'fact-1', content: 'blue' });
+        const v1Id = first.orThrow().records[0].id;
+        clockValue = 2000;
+        const o2 = buildOrchestrator({
+            store,
+            classifier: classifyFact,
+            extractor: extractor(() => succeed([candidate(factKind, 'fact-1', 'grey')])),
+            relationExtractor: relater(() => succeed([candEdge('fact-1', 'contradicts', v1Id)]))
+        });
+        (await o2.ingestItem({ id: 'fact-1', content: 'grey' })).orThrow();
+        // Re-introduce the ORIGINAL body: the invalidated v1 must be skipped by exact
+        // dedup, so this is a NEW version, not a duplicate-of.
+        clockValue = 3000;
+        const o3 = buildOrchestrator({
+            store,
+            classifier: classifyFact,
+            extractor: extractor(() => succeed([candidate(factKind, 'fact-1', 'blue')]))
+        });
+        expect(await o3.ingestItem({ id: 'fact-1', content: 'blue' })).toSucceedAndSatisfy((r) => {
+            expect(r.records[0].resolution.verdict).toBe('new');
+            expect(r.records[0].disposition).toBe('written');
+        });
+    });
+});
+describe('MemoryIngestOrchestrator — additive-provenance non-regression', () => {
+    test('a pre-existing record with only source provenance still loads and validates unchanged', async () => {
+        const store = buildStore({ files: [seedNote('legacy', 'old note', { source: 'human' })] });
+        // Loads at construction time.
+        expect(await store.getById('knowledge', 'legacy')).toSucceedAndSatisfy((rec) => {
+            expect(rec === null || rec === void 0 ? void 0 : rec.envelope.provenance).toEqual({ source: 'human' });
+            expect(rec === null || rec === void 0 ? void 0 : rec.envelope.provenance.by).toBeUndefined();
+            expect(rec === null || rec === void 0 ? void 0 : rec.envelope.provenance.derivedFrom).toBeUndefined();
+        });
+        // An unrelated ingest does not disturb it.
+        const orch = buildOrchestrator({ store });
+        (await orch.ingestItem({ id: 'fresh', content: 'new content' })).orThrow();
+        expect(await store.getById('knowledge', 'legacy')).toSucceedAndSatisfy((rec) => {
+            expect(rec === null || rec === void 0 ? void 0 : rec.envelope.provenance).toEqual({ source: 'human' });
+        });
+    });
+});
+describe('MemoryIngestOrchestrator — ingestBatch', () => {
+    test('ingests a batch in order', async () => {
+        const store = buildStore();
+        const orch = buildOrchestrator({ store });
+        const result = await orch.ingestBatch([
+            { id: 'doc-1', content: 'one' },
+            { id: 'doc-2', content: 'two' }
+        ]);
+        expect(result).toSucceedAndSatisfy((results) => {
+            expect(results).toHaveLength(2);
+            expect(results.map((r) => r.item.id)).toEqual(['doc-1', 'doc-2']);
+            expect(results.every((r) => r.records[0].disposition === 'written')).toBe(true);
+        });
+    });
+    test('aborts the batch on the first item failure', async () => {
+        const orch = buildOrchestrator({
+            store: buildStore(),
+            classifier: classifier((item) => item.id === 'bad' ? fail('classify bad') : succeed({ kind: noteKind }))
+        });
+        expect(await orch.ingestBatch([
+            { id: 'bad', content: 'one' },
+            { id: 'doc-2', content: 'two' }
+        ])).toFailWith(/classify bad/);
+    });
+});
+describe('MemoryIngestOrchestrator — store failure paths', () => {
+    test('a store snapshot (list) failure aborts the item', async () => {
+        const store = mockStore({ list: () => Promise.resolve(fail('list down')) });
+        const orch = buildOrchestrator({ store });
+        expect(await orch.ingestItem({ id: 'doc-1', content: 'x' })).toFailWith(/failed to snapshot store.*list down/);
+    });
+    test('a store put failure surfaces as a write failure', async () => {
+        const store = mockStore({ put: () => Promise.resolve(fail('put kaput')) });
+        const orch = buildOrchestrator({ store });
+        expect(await orch.ingestItem({ id: 'doc-1', content: 'x' })).toFailWith(/write failed.*put kaput/);
+    });
+});
+describe('MemoryIngestOrchestrator — optional constructor params', () => {
+    test('falls back to defaultCodec when no per-kind codec map is supplied', async () => {
+        const store = buildStore();
+        const orch = MemoryIngestOrchestrator.create({
+            store,
+            registry: registry(),
+            defaultCodec: new KnowledgeIdentityCodec(),
+            classifier: classifyNote,
+            extractor: oneNoteExtractor(),
+            relationExtractor: noEdges
+        }).orThrow();
+        expect(await orch.ingestItem({ id: 'doc-1', content: 'hello' })).toSucceedAndSatisfy((r) => expect(r.records[0].disposition).toBe('written'));
+    });
+    test('honors an explicit similarityTopK and logs a captured host throw to the supplied logger', async () => {
+        const logger = new Logging.InMemoryLogger('detail');
+        const orch = MemoryIngestOrchestrator.create({
+            store: buildStore(),
+            registry: registry(),
+            codecs,
+            classifier: throwingClassifier(),
+            extractor: oneNoteExtractor(),
+            relationExtractor: noEdges,
+            similarityTopK: 3,
+            logger
+        }).orThrow();
+        expect(await orch.ingestItem({ id: 'doc-1', content: 'x' })).toFailWith(/classifier boom/);
+        expect(logger.logged.some((m) => /classifier boom/.test(m))).toBe(true);
+    });
+});
+describe('MemoryIngestOrchestrator — review-punch-list fixes', () => {
+    test('a stored record with a non-string body fails the exact-dedup pass loudly', async () => {
+        const weird = {
+            envelope: {
+                id: 'weird',
+                entityId: 'weird',
+                kind: noteKind,
+                tags: [],
+                links: [],
+                created: 0,
+                updated: 0,
+                seq: 0,
+                contentHash: '',
+                provenance: { source: 'agent' }
+            },
+            body: 42
+        };
+        const store = mockStore({ list: () => Promise.resolve(succeed([weird])) });
+        const orch = buildOrchestrator({ store });
+        expect(await orch.ingestItem({ id: 'doc-1', content: 'hello' })).toFailWith(/stored record 'weird' has a non-string body/);
+    });
+    test('duplicate stage-5 edges are deduped on the written record', async () => {
+        const store = buildStore();
+        await putNote(store, 'doc-a', 'anchor');
+        const orch = buildOrchestrator({
+            store,
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'goodbye')])),
+            relationExtractor: relater(() => succeed([candEdge('doc-b', 'rel', 'doc-a'), candEdge('doc-b', 'rel', 'doc-a')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+            var _a;
+            expect((_a = r.records[0].record) === null || _a === void 0 ? void 0 : _a.envelope.links).toEqual([{ type: 'rel', target: 'doc-a' }]);
+        });
+    });
+    test('two candidates merging into the same target do not duplicate a shared edge', async () => {
+        const vectorIndex = InMemoryCosineIndex.create().orThrow();
+        const store = buildStore({ vectorIndex, embed });
+        await putNote(store, 'doc-a', 'apple pie');
+        await putNote(store, 'doc-x', 'target');
+        const orch = buildOrchestrator({
+            store,
+            vectorIndex,
+            embed,
+            entityResolver: resolver((__c, similar) => succeed({ verdict: 'merge-into', target: similar[0].id })),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'apple tart'), candidate(noteKind, 'doc-c', 'apple tart')])),
+            relationExtractor: relater(() => succeed([candEdge('doc-a', 'rel', 'doc-x')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceed();
+        expect(await store.get(noteKind, 'doc-a')).toSucceedAndSatisfy((rec) => {
+            expect(rec === null || rec === void 0 ? void 0 : rec.envelope.links).toEqual([{ type: 'rel', target: 'doc-x' }]);
+        });
+    });
+});
+describe('MemoryIngestOrchestrator — merge-into safety (second review)', () => {
+    // Seed a record with pre-existing tags + links under a flat codec (id === entityId).
+    async function putFull(store, kind, entityId, body, opts = {}) {
+        var _a, _b;
+        const rec = {
+            envelope: {
+                id: entityId,
+                entityId: entityId,
+                kind,
+                tags: ((_a = opts.tags) !== null && _a !== void 0 ? _a : []),
+                links: (_b = opts.links) !== null && _b !== void 0 ? _b : [],
+                created: 0,
+                updated: 0,
+                seq: 0,
+                contentHash: '',
+                provenance: { source: 'agent' }
+            },
+            body
+        };
+        (await store.put(rec)).orThrow();
+    }
+    test('merge-into UNIONs the target’s existing tags + links (never overwrites them)', async () => {
+        const vectorIndex = InMemoryCosineIndex.create().orThrow();
+        const store = buildStore({ vectorIndex, embed });
+        await putFull(store, noteKind, 'doc-a', 'apple pie', {
+            tags: ['old-tag'],
+            links: [{ type: 'existing', target: 'doc-z' }]
+        });
+        await putFull(store, noteKind, 'doc-x', 'target of stage-5');
+        const orch = buildOrchestrator({
+            store,
+            vectorIndex,
+            embed,
+            entityResolver: resolver((__c, similar) => succeed({ verdict: 'merge-into', target: similar[0].id })),
+            extractor: extractor(() => succeed([
+                candidate(noteKind, 'doc-b', 'apple tart', {
+                    tags: ['new-tag'],
+                    links: [{ type: 'candlink', target: 'doc-z' }]
+                })
+            ])),
+            relationExtractor: relater(() => succeed([candEdge('doc-a', 'stage5', 'doc-x')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r) => {
+            expect(r.records[0].disposition).toBe('merged');
+        });
+        expect(await store.get(noteKind, 'doc-a')).toSucceedAndSatisfy((rec) => {
+            var _a;
+            // Original tag preserved AND the candidate's tag gained, each once.
+            expect([...((_a = rec === null || rec === void 0 ? void 0 : rec.envelope.tags) !== null && _a !== void 0 ? _a : [])].sort()).toEqual(['new-tag', 'old-tag']);
+            // Original link + candidate link + stage-5 edge, each exactly once.
+            expect(rec === null || rec === void 0 ? void 0 : rec.envelope.links).toEqual([
+                { type: 'existing', target: 'doc-z' },
+                { type: 'candlink', target: 'doc-z' },
+                { type: 'stage5', target: 'doc-x' }
+            ]);
+        });
+    });
+    test('merge-into a different-kind target fails loudly', async () => {
+        const vectorIndex = InMemoryCosineIndex.create().orThrow();
+        const store = buildStore({ vectorIndex, embed });
+        // A DIFFERENT-kind (ltm) record embedded so it surfaces as a neighbor of a note candidate.
+        await putFull(store, ltmKind, 'conv-1', 'apple pie');
+        const orch = buildOrchestrator({
+            store,
+            vectorIndex,
+            embed,
+            entityResolver: resolver((__c, similar) => succeed({ verdict: 'merge-into', target: similar[0].id })),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'apple tart')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toFailWith(/merge-into target 'conv-1' is kind 'ltm' but the candidate is kind 'note'/);
+    });
+    test('supersede with a non-existent target fails loudly', async () => {
+        const vectorIndex = InMemoryCosineIndex.create().orThrow();
+        const store = buildStore({ vectorIndex, embed });
+        await putFull(store, noteKind, 'doc-a', 'apple pie');
+        const orch = buildOrchestrator({
+            store,
+            vectorIndex,
+            embed,
+            entityResolver: resolver(() => succeed({ verdict: 'supersede', target: 'ghost' })),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'apple tart')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toFailWith(/supersede target 'ghost' does not exist/);
+    });
+    test('duplicate-of with a non-existent target fails loudly', async () => {
+        const vectorIndex = InMemoryCosineIndex.create().orThrow();
+        const store = buildStore({ vectorIndex, embed });
+        await putFull(store, noteKind, 'doc-a', 'apple pie');
+        const orch = buildOrchestrator({
+            store,
+            vectorIndex,
+            embed,
+            entityResolver: resolver(() => succeed({ verdict: 'duplicate-of', target: 'ghost' })),
+            extractor: extractor(() => succeed([candidate(noteKind, 'doc-b', 'apple tart')]))
+        });
+        expect(await orch.ingestItem({ id: 'i', content: 'x' })).toFailWith(/duplicate-of target 'ghost' does not exist/);
+    });
+});
+//# sourceMappingURL=orchestrator.test.js.map