@fgv/ts-agent-memory 5.1.0-46 → 5.1.0-48

package/src/test/unit/ingest/antagonistCycleAndParity.test.ts

@@ -1,367 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-/**
- * Antagonist torture tests — cycle guard adversarial graphs (target class 6) and
- * enum-branch parity (target class 7), exercised at the ORCHESTRATOR/integration
- * level over a real {@link FileTreeMemoryStore}, complementing the pure-function
- * unit tests in `cycleGuard.test.ts` and the per-verdict tests in
- * `orchestrator.test.ts`.
- */
-
-import '@fgv/ts-utils-jest';
-import { Converters, Result, succeed } from '@fgv/ts-utils';
-import { FileTree } from '@fgv/ts-json-base';
-import {
-  BodyConverterRegistry,
-  EntityId,
-  FileTreeMemoryStore,
-  IBodyConverterRegistry,
-  ICandidateEdge,
-  ICandidateRecord,
-  IEdgeTarget,
-  IEntityResolutionCandidate,
-  IEntityResolver,
-  IFactExtractor,
-  IIdentityCodec,
-  IIngestItem,
-  IIngestItemResult,
-  IMemoryClassification,
-  IMemoryClassifier,
-  IMemoryEnvelope,
-  IMemoryRecord,
-  IRelationContext,
-  IRelationExtractor,
-  InMemoryCosineIndex,
-  Kind,
-  KnowledgeIdentityCodec,
-  MemoryId,
-  MemoryIngestOrchestrator,
-  MemoryScopeKey,
-  ResolutionVerdict,
-  Tag
-} from '../../../index';
-
-const noteKind: Kind = 'note' as Kind;
-
-/** A scope-qualified target for the note fixtures (all under the knowledge scope). */
-function kt(id: string): IEdgeTarget {
-  return { scope: 'knowledge' as MemoryScopeKey, id: id as MemoryId };
-}
-
-function mutableRoot(): FileTree.IMutableFileTreeDirectoryItem {
-  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 registry(): IBodyConverterRegistry {
-  const reg = BodyConverterRegistry.create().orThrow();
-  reg.register(noteKind, Converters.string);
-  return reg;
-}
-
-const codecs: ReadonlyMap<Kind, IIdentityCodec> = new Map<Kind, IIdentityCodec>([
-  [noteKind, new KnowledgeIdentityCodec()]
-]);
-
-function buildStore(): FileTreeMemoryStore {
-  return FileTreeMemoryStore.create({ root: mutableRoot(), registry: registry(), codecs }).orThrow();
-}
-
-async function putFull(
-  store: FileTreeMemoryStore,
-  entityId: string,
-  body: string,
-  links: IMemoryEnvelope['links'] = []
-): Promise<void> {
-  const rec: IMemoryRecord<unknown> = {
-    envelope: {
-      id: entityId as MemoryId,
-      entityId: entityId as EntityId,
-      kind: noteKind,
-      tags: [],
-      links,
-      created: 0,
-      updated: 0,
-      seq: 0,
-      contentHash: '',
-      provenance: { source: 'agent' }
-    },
-    body
-  };
-  (await store.put(rec)).orThrow();
-}
-
-function classifier(fn: (item: IIngestItem) => Result<IMemoryClassification>): IMemoryClassifier {
-  return { classify: (item) => Promise.resolve(fn(item)) };
-}
-function extractor(
-  fn: (item: IIngestItem, c: IMemoryClassification) => Result<ReadonlyArray<ICandidateRecord>>
-): IFactExtractor {
-  return { extract: (item, c) => Promise.resolve(fn(item, c)) };
-}
-function relater(fn: (ctx: IRelationContext) => Result<ReadonlyArray<ICandidateEdge>>): IRelationExtractor {
-  return { relate: (ctx) => Promise.resolve(fn(ctx)) };
-}
-function resolver(
-  fn: (
-    candidate: ICandidateRecord,
-    similar: ReadonlyArray<IEntityResolutionCandidate>
-  ) => Result<ResolutionVerdict>
-): IEntityResolver {
-  return { resolve: (candidate, similar) => Promise.resolve(fn(candidate, similar)) };
-}
-
-const classifyNote: IMemoryClassifier = classifier(() => succeed({ kind: noteKind }));
-
-function candidate(
-  entityId: string,
-  body: unknown,
-  links: ICandidateRecord['envelope']['links'] = []
-): ICandidateRecord {
-  return {
-    envelope: {
-      entityId: entityId as EntityId,
-      kind: noteKind,
-      tags: [],
-      links,
-      provenance: { source: 'agent' }
-    },
-    body
-  };
-}
-
-function candEdge(source: string, type: string, target: string): ICandidateEdge {
-  return { source: kt(source), edge: { type: type as never, target: kt(target) } };
-}
-
-function buildOrchestrator(params: {
-  store: FileTreeMemoryStore;
-  extractor: IFactExtractor;
-  relationExtractor: IRelationExtractor;
-  entityResolver?: IEntityResolver;
-}): MemoryIngestOrchestrator {
-  return MemoryIngestOrchestrator.create({
-    store: params.store,
-    registry: registry(),
-    codecs,
-    classifier: classifyNote,
-    extractor: params.extractor,
-    relationExtractor: params.relationExtractor,
-    entityResolver: params.entityResolver
-  }).orThrow();
-}
-
-describe('antagonist — cycle guard through EXISTING store edges (integration)', () => {
-  // Wrong impl this catches: an orchestrator that only feeds the cycle guard the
-  // proposed-edge batch (as its own pure-function unit tests do) and forgets to
-  // fold in the store snapshot's existing edges, so a cycle that closes THROUGH
-  // an already-persisted edge is silently admitted.
-  test('a proposed edge that closes a cycle through a pre-existing on-disk edge is rejected', async () => {
-    const store = buildStore();
-    // Existing on-disk edge: doc-a -> doc-b (persisted before this ingest runs).
-    await putFull(store, 'doc-a', 'anchor-a', [{ type: 'rel' as never, target: kt('doc-b') }]);
-    await putFull(store, 'doc-b', 'anchor-b');
-
-    // This ingest re-writes doc-b (a 'new'-verdict same-id update, since no
-    // resolver is wired) and proposes doc-b -> doc-a, which — unioned with the
-    // EXISTING doc-a -> doc-b edge — closes a 2-cycle that exists ONLY because of
-    // the on-disk edge, not anything proposed in this batch.
-    const orch = buildOrchestrator({
-      store,
-      extractor: extractor(() => succeed([candidate('doc-b', 'anchor-b-v2')])),
-      relationExtractor: relater(() => succeed([candEdge('doc-b', 'rel', 'doc-a')]))
-    });
-    expect(await orch.ingestItem({ id: 'i', content: 'x' })).toFailWith(/would create a cycle/);
-
-    // Confirm the guard fired BEFORE any write — doc-b's content must be unchanged.
-    expect(await store.get(noteKind, 'doc-b' as EntityId)).toSucceedAndSatisfy(
-      (rec: IMemoryRecord<unknown> | undefined) => expect(rec?.body).toBe('anchor-b')
-    );
-  });
-
-  test('a long existing chain plus one proposed edge closing the loop is rejected', async () => {
-    const store = buildStore();
-    // Existing chain: a -> b -> c -> d (four pre-existing on-disk edges spanning
-    // three hops), persisted before this ingest.
-    await putFull(store, 'chain-a', 'a', [{ type: 'rel' as never, target: kt('chain-b') }]);
-    await putFull(store, 'chain-b', 'b', [{ type: 'rel' as never, target: kt('chain-c') }]);
-    await putFull(store, 'chain-c', 'c', [{ type: 'rel' as never, target: kt('chain-d') }]);
-    await putFull(store, 'chain-d', 'd');
-
-    // Proposed: chain-d -> chain-a, closing the whole loop through the existing chain.
-    const orch = buildOrchestrator({
-      store,
-      extractor: extractor(() => succeed([candidate('chain-d', 'd-v2')])),
-      relationExtractor: relater(() => succeed([candEdge('chain-d', 'rel', 'chain-a')]))
-    });
-    expect(await orch.ingestItem({ id: 'i', content: 'x' })).toFailWith(/would create a cycle/);
-  });
-
-  test('cycleGuard "off" admits a cycle that closes through an existing edge', async () => {
-    const store = buildStore();
-    await putFull(store, 'doc-a', 'anchor-a', [{ type: 'rel' as never, target: kt('doc-b') }]);
-    await putFull(store, 'doc-b', 'anchor-b');
-    const orch = MemoryIngestOrchestrator.create({
-      store,
-      registry: registry(),
-      codecs,
-      classifier: classifyNote,
-      extractor: extractor(() => succeed([candidate('doc-b', 'anchor-b-v2')])),
-      relationExtractor: relater(() => succeed([candEdge('doc-b', 'rel', 'doc-a')])),
-      cycleGuard: 'off'
-    }).orThrow();
-    expect(await orch.ingestItem({ id: 'i', content: 'x' })).toSucceedAndSatisfy((r: IIngestItemResult) => {
-      expect(r.records[0].record?.envelope.links).toEqual([{ type: 'rel', target: kt('doc-a') }]);
-    });
-  });
-});
-
-describe('antagonist — resolver target need not be a surfaced `similar` candidate (structural-only gate)', () => {
-  // Documents (and locks in) the actual contract: fgv validates a target-bearing
-  // verdict STRUCTURALLY (exists in the store + matching kind), uniformly across
-  // all three target-bearing verdicts, regardless of whether the resolver's
-  // choice was among the `similar` candidates it was shown. Wrong impl this
-  // guards against: fgv silently restricting itself to `similar` membership
-  // (which would incorrectly reject a host resolver with external knowledge), OR
-  // fgv skipping the structural check for one of the three verdicts.
-  test.each(['duplicate-of', 'supersede', 'merge-into'] as const)(
-    "verdict '%s' targeting a valid existing record OUTSIDE the surfaced similar set is accepted",
-    async (verdict) => {
-      const store = buildStore();
-      await putFull(store, 'doc-a', 'apple pie'); // will be surfaced as `similar`
-      await putFull(store, 'doc-q', 'unrelated target'); // exists, but never surfaced
-
-      const vectorIndex = InMemoryCosineIndex.create().orThrow();
-      const embed = (): Promise<Result<Float32Array>> =>
-        Promise.resolve(succeed(Float32Array.from([1, 0, 0])));
-      // Only doc-a is embedded/indexed; doc-q is never surfaced by similarity —
-      // it can only be reached by the resolver's own out-of-band choice.
-      (await vectorIndex.add(kt('doc-a'), Float32Array.from([1, 0, 0]))).orThrow();
-
-      const orch = MemoryIngestOrchestrator.create({
-        store,
-        registry: registry(),
-        codecs,
-        classifier: classifyNote,
-        extractor: extractor(() => succeed([candidate('doc-b', 'apple tart')])),
-        relationExtractor: relater(() => succeed([])),
-        vectorIndex,
-        embed,
-        entityResolver: resolver(() => succeed({ verdict, target: kt('doc-q') } as ResolutionVerdict))
-      }).orThrow();
-
-      const result = await orch.ingestItem({ id: 'i', content: 'x' });
-      if (verdict === 'duplicate-of') {
-        expect(result).toSucceedAndSatisfy((r: IIngestItemResult) => {
-          expect(r.records[0].disposition).toBe('deduped');
-          expect(r.records[0].id).toBe('doc-q');
-        });
-      } else if (verdict === 'supersede') {
-        expect(result).toSucceedAndSatisfy((r: IIngestItemResult) => {
-          expect(r.records[0].disposition).toBe('written');
-          expect(r.records[0].resolution).toEqual({ verdict: 'supersede', target: kt('doc-q') });
-        });
-      } else {
-        expect(result).toSucceedAndSatisfy((r: IIngestItemResult) => {
-          expect(r.records[0].disposition).toBe('merged');
-          expect(r.records[0].id).toBe('doc-q');
-        });
-      }
-    }
-  );
-});
-
-describe('antagonist — enum-branch parity: uniform structural rejection across target-bearing verdicts', () => {
-  // A single table-driven test locking in that EVERY target-bearing verdict arm
-  // shares the SAME two structural checks (existence, then kind match) in the
-  // SAME order — the exact class of hole ("only merge-into checked") that a
-  // prior review caught. Wrong impl this guards against: a future edit that adds
-  // a fourth verdict or refactors validation per-branch and re-introduces an
-  // asymmetric gap.
-  const verdicts = ['duplicate-of', 'supersede', 'merge-into'] as const;
-
-  test.each(verdicts)(
-    "verdict '%s' rejects a nonexistent target with the SAME message shape",
-    async (verdict) => {
-      const store = buildStore();
-      await putFull(store, 'doc-a', 'apple pie');
-      const vectorIndex = InMemoryCosineIndex.create().orThrow();
-      const embed = (): Promise<Result<Float32Array>> =>
-        Promise.resolve(succeed(Float32Array.from([1, 0, 0])));
-      const orch = MemoryIngestOrchestrator.create({
-        store,
-        registry: registry(),
-        codecs,
-        classifier: classifyNote,
-        extractor: extractor(() => succeed([candidate('doc-b', 'apple tart')])),
-        relationExtractor: relater(() => succeed([])),
-        vectorIndex,
-        embed,
-        entityResolver: resolver(() => succeed({ verdict, target: kt('ghost') } as ResolutionVerdict))
-      }).orThrow();
-      (await vectorIndex.add(kt('doc-a'), Float32Array.from([1, 0, 0]))).orThrow();
-      expect(await orch.ingestItem({ id: 'i', content: 'x' })).toFailWith(
-        `ingest 'i': ${verdict} target 'knowledge/ghost' does not exist in the store`
-      );
-    }
-  );
-
-  test.each(verdicts)(
-    "verdict '%s' rejects a foreign-kind target with the SAME message shape",
-    async (verdict) => {
-      const otherKind: Kind = 'other' as Kind;
-      const reg = registry();
-      reg.register(otherKind, Converters.string);
-      const otherCodecs: ReadonlyMap<Kind, IIdentityCodec> = new Map<Kind, IIdentityCodec>([
-        ...codecs,
-        [otherKind, new KnowledgeIdentityCodec()]
-      ]);
-      const store = FileTreeMemoryStore.create({
-        root: mutableRoot(),
-        registry: reg,
-        codecs: otherCodecs
-      }).orThrow();
-      const foreignRec: IMemoryRecord<unknown> = {
-        envelope: {
-          id: 'foreign-1' as MemoryId,
-          entityId: 'foreign-1' as EntityId,
-          kind: otherKind,
-          tags: [] as ReadonlyArray<Tag>,
-          links: [],
-          created: 0,
-          updated: 0,
-          seq: 0,
-          contentHash: '',
-          provenance: { source: 'agent' }
-        },
-        body: 'apple pie'
-      };
-      (await store.put(foreignRec)).orThrow();
-      const vectorIndex = InMemoryCosineIndex.create().orThrow();
-      const embed = (): Promise<Result<Float32Array>> =>
-        Promise.resolve(succeed(Float32Array.from([1, 0, 0])));
-      const orch = MemoryIngestOrchestrator.create({
-        store,
-        registry: reg,
-        codecs: otherCodecs,
-        classifier: classifyNote,
-        extractor: extractor(() => succeed([candidate('doc-b', 'apple tart')])),
-        relationExtractor: relater(() => succeed([])),
-        vectorIndex,
-        embed,
-        entityResolver: resolver(() => succeed({ verdict, target: kt('foreign-1') } as ResolutionVerdict))
-      }).orThrow();
-      (await vectorIndex.add(kt('foreign-1'), Float32Array.from([1, 0, 0]))).orThrow();
-      expect(await orch.ingestItem({ id: 'i', content: 'x' })).toFailWith(
-        `ingest 'i': ${verdict} target 'knowledge/foreign-1' is kind 'other' but the candidate is kind 'note'`
-      );
-    }
-  );
-});

package/src/test/unit/ingest/cycleGuard.test.ts

@@ -1,110 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import '@fgv/ts-utils-jest';
-import {
-  ICycleGuardEdge,
-  IEdgeTarget,
-  LinkType,
-  MemoryId,
-  MemoryScopeKey,
-  assertNoCycles,
-  buildCycleKey
-} from '../../../index';
-
-const rel: LinkType = 'rel' as LinkType;
-const DEFAULT_SCOPE: string = 'exp';
-
-/** A scope-qualified node, `scope#id` or a bare id defaulting to {@link DEFAULT_SCOPE}. */
-function node(spec: string): IEdgeTarget {
-  const hash: number = spec.indexOf('#');
-  const scope: string = hash >= 0 ? spec.slice(0, hash) : DEFAULT_SCOPE;
-  const id: string = hash >= 0 ? spec.slice(hash + 1) : spec;
-  return { scope: scope as MemoryScopeKey, id: id as MemoryId };
-}
-
-function edge(source: string, target: string, type: LinkType = rel): ICycleGuardEdge {
-  return { source: node(source), target: node(target), type };
-}
-
-describe('buildCycleKey', () => {
-  test('is deterministic for the same edge', () => {
-    expect(buildCycleKey(edge('a', 'b'))).toSucceedAndSatisfy((key: string) => {
-      expect(buildCycleKey(edge('a', 'b'))).toSucceedWith(key);
-    });
-  });
-
-  test('differs by direction and type', () => {
-    const forward = buildCycleKey(edge('a', 'b')).orThrow();
-    const reverse = buildCycleKey(edge('b', 'a')).orThrow();
-    const typed = buildCycleKey(edge('a', 'b', 'other' as LinkType)).orThrow();
-    expect(forward).not.toBe(reverse);
-    expect(forward).not.toBe(typed);
-  });
-});
-
-describe('assertNoCycles', () => {
-  test('accepts an acyclic graph', () => {
-    expect(assertNoCycles([edge('a', 'b')], [edge('b', 'c'), edge('c', 'd')])).toSucceed();
-  });
-
-  test('rejects a proposed edge that closes a cycle against existing edges', () => {
-    expect(assertNoCycles([edge('a', 'b'), edge('b', 'c')], [edge('c', 'a')])).toFailWith(
-      /would create a cycle/
-    );
-  });
-
-  test('rejects a cycle formed entirely within the proposed batch', () => {
-    expect(assertNoCycles([], [edge('a', 'b'), edge('b', 'a')])).toFailWith(/would create a cycle/);
-  });
-
-  test('rejects a self-loop', () => {
-    expect(assertNoCycles([], [edge('a', 'a')])).toFailWith(/self-loop/);
-  });
-
-  test('tolerates a duplicate proposed edge (deduped by canonical key)', () => {
-    expect(assertNoCycles([], [edge('a', 'b'), edge('a', 'b')])).toSucceed();
-  });
-
-  test('tolerates a duplicate existing edge', () => {
-    expect(assertNoCycles([edge('a', 'b'), edge('a', 'b')], [edge('b', 'c')])).toSucceed();
-  });
-
-  test('accepts a diamond (shared descendant is not a cycle)', () => {
-    expect(assertNoCycles([], [edge('a', 'b'), edge('a', 'c'), edge('b', 'd'), edge('c', 'd')])).toSucceed();
-  });
-
-  test('reachability tolerates a frontier node reached by two paths (revisit guard)', () => {
-    // Existing graph: a->c, a->b, b->c. A proposed edge z->a runs reachability
-    // from `a`, whose DFS pushes `c` twice before it is visited — exercising the
-    // visited-node skip in the traversal.
-    expect(assertNoCycles([edge('a', 'c'), edge('a', 'b'), edge('b', 'c')], [edge('z', 'a')])).toSucceed();
-  });
-
-  describe('scope-qualified nodes', () => {
-    test('does NOT conflate a stem shared across scopes into one node', () => {
-      // ca#x -> cb#y and cb#x -> ca#z reuse the stem `x` across scopes ca/cb.
-      // If the guard keyed on bare id, the two `x` nodes would merge and a false
-      // cycle could appear; with scoped keys they are distinct and the graph is acyclic.
-      expect(assertNoCycles([], [edge('ca#x', 'cb#y'), edge('cb#x', 'ca#z')])).toSucceed();
-    });
-
-    test('still rejects a genuine within-scope cycle across the same stems', () => {
-      expect(assertNoCycles([], [edge('ca#x', 'ca#y'), edge('ca#y', 'ca#x')])).toFailWith(
-        /would create a cycle/
-      );
-    });
-
-    test('a self-loop is detected on the full scoped identity', () => {
-      expect(assertNoCycles([], [edge('ca#x', 'ca#x')])).toFailWith(/self-loop/);
-      // Same stem, different scope is NOT a self-loop.
-      expect(assertNoCycles([], [edge('ca#x', 'cb#x')])).toSucceed();
-    });
-
-    test('names the scope in the diagnostic', () => {
-      expect(assertNoCycles([], [edge('ca#x', 'ca#x')])).toFailWith(/ca\/x/);
-    });
-  });
-});