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

package/src/test/unit/retrieve/temporalRetrievers.test.ts

@@ -0,0 +1,226 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import '@fgv/ts-utils-jest';
+import {
+  AsOfRetriever,
+  CurrentValidRetriever,
+  HistoryRetriever,
+  HybridRetriever,
+  IIndexedMemoryRecord,
+  IMemoryRecord,
+  Kind,
+  MemoryIndex,
+  MemoryScopeKey,
+  RecencyRetriever,
+  ScoreUnionMergeStrategy,
+  envelopeConverter
+} from '../../../index';
+
+const factKind: Kind = 'fact' as Kind;
+
+interface IVersionSpec {
+  readonly entityId: string;
+  readonly seq: number;
+  readonly validAt: number;
+  // eslint-disable-next-line @rushstack/no-new-null -- invalid_at null is the meaningful still-valid sentinel
+  readonly invalidAt?: number | null;
+  readonly kind?: string;
+}
+
+function versionEntry(spec: IVersionSpec): IIndexedMemoryRecord {
+  const temporal: Record<string, unknown> = { valid_at: spec.validAt };
+  if (spec.invalidAt !== undefined) {
+    temporal.invalid_at = spec.invalidAt;
+  }
+  const record: IMemoryRecord<unknown> = {
+    envelope: envelopeConverter
+      .convert({
+        id: `${spec.entityId}-v${spec.seq}`,
+        entityId: spec.entityId,
+        kind: spec.kind ?? 'fact',
+        tags: [],
+        links: [],
+        created: spec.validAt,
+        updated: spec.validAt,
+        seq: spec.seq,
+        contentHash: `h-${spec.entityId}-${spec.seq}`,
+        provenance: { source: 'agent' },
+        temporal
+      })
+      .orThrow(),
+    body: `${spec.entityId} v${spec.seq}`
+  };
+  return { scope: `facts/entities/${spec.entityId}` as MemoryScopeKey, record };
+}
+
+/** A flat (non-temporal) entry, to prove the temporal retrievers ignore it. */
+function flatEntry(id: string): IIndexedMemoryRecord {
+  const record: IMemoryRecord<unknown> = {
+    envelope: envelopeConverter
+      .convert({
+        id,
+        entityId: id,
+        kind: 'knowledge',
+        tags: [],
+        links: [],
+        created: 0,
+        updated: 0,
+        seq: 0,
+        contentHash: `h-${id}`,
+        provenance: { source: 'agent' }
+      })
+      .orThrow(),
+    body: id
+  };
+  return { scope: 'knowledge' as MemoryScopeKey, record };
+}
+
+function ids(records: ReadonlyArray<IMemoryRecord<unknown>>): string[] {
+  return records.map((r) => r.envelope.id as string);
+}
+
+// fact-1: v1 [100,200), v2 [200,∞) current. fact-2: v1 [150,∞) current. Plus a flat doc.
+function buildIndex(): MemoryIndex {
+  const index = MemoryIndex.create().orThrow();
+  index
+    .rebuild([
+      versionEntry({ entityId: 'fact-1', seq: 1, validAt: 100, invalidAt: 200 }),
+      versionEntry({ entityId: 'fact-1', seq: 2, validAt: 200 }),
+      versionEntry({ entityId: 'fact-2', seq: 3, validAt: 150 }),
+      flatEntry('doc-a')
+    ])
+    .orThrow();
+  return index;
+}
+
+describe('temporal retrievers', () => {
+  const index: MemoryIndex = buildIndex();
+
+  describe('CurrentValidRetriever', () => {
+    const retriever = CurrentValidRetriever.create(index).orThrow();
+
+    test('declares supportsTemporalQuery', () => {
+      expect(retriever.capabilities.supportsTemporalQuery).toBe(true);
+    });
+
+    test('returns the current version per temporal entity, ignoring flat records', async () => {
+      expect(await retriever.retrieve({})).toSucceedAndSatisfy((records) => {
+        expect(ids(records).sort()).toEqual(['fact-1-v2', 'fact-2-v3']);
+      });
+    });
+
+    test('honors scope / kind pre-filter and limit', async () => {
+      expect(await retriever.retrieve({ kind: factKind, limit: 1 })).toSucceedAndSatisfy((records) => {
+        expect(records).toHaveLength(1);
+      });
+    });
+  });
+
+  describe('AsOfRetriever', () => {
+    const retriever = AsOfRetriever.create(index).orThrow();
+
+    test('empty when no asOf axis is supplied', async () => {
+      expect(await retriever.retrieve({})).toSucceedWith([]);
+    });
+
+    test('returns the version valid at asOf per entity', async () => {
+      expect(await retriever.retrieve({ asOf: 150 })).toSucceedAndSatisfy((records) => {
+        // fact-1 v1 valid at 150; fact-2 v1 valid at 150.
+        expect(ids(records).sort()).toEqual(['fact-1-v1', 'fact-2-v3']);
+      });
+      expect(await retriever.retrieve({ asOf: 250 })).toSucceedAndSatisfy((records) => {
+        expect(ids(records).sort()).toEqual(['fact-1-v2', 'fact-2-v3']);
+      });
+      expect(await retriever.retrieve({ asOf: 50 })).toSucceedWith([]);
+    });
+  });
+
+  describe('HistoryRetriever', () => {
+    const retriever = HistoryRetriever.create(index).orThrow();
+
+    test('returns all versions ascending by valid_at', async () => {
+      expect(await retriever.retrieve({ kind: factKind })).toSucceedAndSatisfy((records) => {
+        expect(ids(records)).toEqual(['fact-1-v1', 'fact-2-v3', 'fact-1-v2']);
+      });
+    });
+
+    test('applies the limit after ordering', async () => {
+      expect(await retriever.retrieve({ kind: factKind, limit: 2 })).toSucceedAndSatisfy((records) => {
+        expect(ids(records)).toEqual(['fact-1-v1', 'fact-2-v3']);
+      });
+    });
+
+    test('orders by created when a version has no valid_at', async () => {
+      const idx = MemoryIndex.create().orThrow();
+      const noValidAt: IIndexedMemoryRecord = {
+        scope: 'facts/entities/nv' as MemoryScopeKey,
+        record: {
+          envelope: envelopeConverter
+            .convert({
+              id: 'nv-v1',
+              entityId: 'nv',
+              kind: 'fact',
+              tags: [],
+              links: [],
+              created: 700,
+              updated: 700,
+              seq: 1,
+              contentHash: 'h',
+              provenance: { source: 'agent' },
+              temporal: {}
+            })
+            .orThrow(),
+          body: 'nv'
+        }
+      };
+      idx.rebuild([noValidAt, versionEntry({ entityId: 'early', seq: 2, validAt: 100 })]).orThrow();
+      const r = HistoryRetriever.create(idx).orThrow();
+      // `nv` has no valid_at → its start defaults to created (700), after early (100).
+      expect(await r.retrieve({})).toSucceedAndSatisfy((records) => {
+        expect(ids(records)).toEqual(['early-v2', 'nv-v1']);
+      });
+    });
+
+    test('breaks an equal-valid_at tie by ascending seq', async () => {
+      // Two versions of one entity sharing a valid_at — the seq tiebreak orders them.
+      const tieIndex = MemoryIndex.create().orThrow();
+      tieIndex
+        .rebuild([
+          versionEntry({ entityId: 'tie', seq: 5, validAt: 500, invalidAt: 500 }),
+          versionEntry({ entityId: 'tie', seq: 4, validAt: 500 })
+        ])
+        .orThrow();
+      const tieRetriever = HistoryRetriever.create(tieIndex).orThrow();
+      expect(await tieRetriever.retrieve({})).toSucceedAndSatisfy((records) => {
+        expect(ids(records)).toEqual(['tie-v4', 'tie-v5']);
+      });
+    });
+  });
+
+  describe('loud-degrade + Hybrid composite', () => {
+    test('a non-temporal retriever loud-degrades on an asOf query', async () => {
+      const recency = RecencyRetriever.create(index).orThrow();
+      expect(await recency.retrieve({ asOf: 150 })).toFailWith(/temporal query requires temporal index/i);
+    });
+
+    test('a Hybrid of [Recency, AsOf] lights up temporal recall via the temporal child', async () => {
+      const recency = RecencyRetriever.create(index).orThrow();
+      const asOf = AsOfRetriever.create(index).orThrow();
+      const hybrid = HybridRetriever.create(
+        [recency, asOf],
+        ScoreUnionMergeStrategy.create().orThrow()
+      ).orThrow();
+      // The union supports temporal query, so the guard passes; Recency gets asOf
+      // stripped (returns everything), AsOf returns the valid-at versions.
+      expect(hybrid.capabilities.supportsTemporalQuery).toBe(true);
+      expect(await hybrid.retrieve({ asOf: 250, kind: factKind })).toSucceedAndSatisfy((records) => {
+        // fact-1-v2 is surfaced by BOTH (recency all + asOf), so it ranks first.
+        expect(ids(records)[0]).toBe('fact-1-v2');
+        expect(ids(records)).toContain('fact-2-v3');
+      });
+    });
+  });
+});

package/src/test/unit/store/antagonistTemporalBoundary.test.ts

@@ -0,0 +1,158 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Antagonist torture tests — bi-temporal / two-clock boundary math (target class
+ * 2), complementing `temporalCodec.test.ts` (which already covers the
+ * `invalid_at`-exclusive boundary and the future-dated-supersede no-gap case).
+ * This file targets two remaining gaps: the `valid_at`-inclusive boundary, and
+ * an out-of-order sequence of `valid_at` writes.
+ */
+
+import '@fgv/ts-utils-jest';
+import { Converters } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
+import {
+  BodyConverterRegistry,
+  EntityId,
+  FileTreeMemoryStore,
+  IBodyConverterRegistry,
+  IIdentityCodec,
+  IMemoryRecord,
+  IWritePolicy,
+  Kind,
+  MemoryScopeKey,
+  TemporalIdentityCodec,
+  TemporalVersionedPolicy,
+  envelopeConverter,
+  isVersionValidAt
+} from '../../../index';
+
+const factKind: Kind = 'fact' as Kind;
+const factScope: MemoryScopeKey = 'facts/entities/fact-1' as MemoryScopeKey;
+
+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(factKind, Converters.string);
+  return reg;
+}
+
+const codecs: ReadonlyMap<Kind, IIdentityCodec> = new Map<Kind, IIdentityCodec>([
+  [factKind, TemporalIdentityCodec.create('facts').orThrow()]
+]);
+const policies: ReadonlyMap<Kind, IWritePolicy> = new Map<Kind, IWritePolicy>([
+  [factKind, TemporalVersionedPolicy.create().orThrow()]
+]);
+
+function factRecordAt(entityId: string, body: string, validAt?: number): IMemoryRecord<unknown> {
+  return {
+    envelope: {
+      id: entityId as unknown as IMemoryRecord<unknown>['envelope']['id'],
+      entityId: entityId as EntityId,
+      kind: factKind,
+      tags: [],
+      links: [],
+      created: 0,
+      updated: 0,
+      seq: 0,
+      contentHash: '',
+      provenance: { source: 'agent' },
+      ...(validAt !== undefined ? { temporal: { valid_at: validAt } } : {})
+    },
+    body
+  };
+}
+
+describe('antagonist — isVersionValidAt: valid_at is INCLUSIVE (start-boundary parity with the exclusive end)', () => {
+  // Wrong impl this catches: a `>` (strict) comparison for the start boundary
+  // instead of `<=`, which would incorrectly exclude the instant a version FIRST
+  // became valid — an asymmetry with the already-tested exclusive end boundary.
+  test('a version is valid AT its own valid_at instant, not just strictly after it', () => {
+    const v1 = {
+      envelope: envelopeConverter
+        .convert({
+          id: 'fact-1-v1',
+          entityId: 'fact-1',
+          kind: 'fact',
+          tags: [],
+          links: [],
+          created: 100,
+          updated: 100,
+          seq: 1,
+          contentHash: 'h1',
+          provenance: { source: 'agent' },
+          temporal: { valid_at: 100, invalid_at: 200 }
+        })
+        .orThrow(),
+      body: 'v1'
+    };
+    expect(isVersionValidAt(v1, 99)).toBe(false); // strictly before
+    expect(isVersionValidAt(v1, 100)).toBe(true); // AT valid_at — inclusive start
+    expect(isVersionValidAt(v1, 199)).toBe(true); // just before invalid_at
+    expect(isVersionValidAt(v1, 200)).toBe(false); // AT invalid_at — exclusive end
+  });
+});
+
+describe('antagonist — out-of-order valid_at sequence (no gap/overlap regardless of write order)', () => {
+  let clockValue: number;
+  const clock = (): number => clockValue;
+
+  function createStore(): FileTreeMemoryStore {
+    return FileTreeMemoryStore.create({
+      root: mutableRoot(),
+      registry: registry(),
+      codecs,
+      writePolicies: policies,
+      clock
+    }).orThrow();
+  }
+
+  // Wrong impl this catches: an implementation that assumes valid_at is
+  // monotonically increasing with seq (e.g. sorts by valid_at instead of seq for
+  // "current" resolution), which breaks the moment a caller backdates a SECOND
+  // time after an earlier future-dated write.
+  test('two consecutive backdated writes still close each prior interval at the NEW valid_at, not now', async () => {
+    const store = createStore();
+    clockValue = 1000;
+    // v1: valid_at defaults to transaction time (1000).
+    expect(await store.put(factRecordAt('fact-1', 'blue'))).toSucceed();
+
+    clockValue = 2000;
+    // v2: backdated BEHIND v1's own valid_at (500 < 1000) — a correction asserting
+    // "actually, this was already true starting at t=500".
+    expect(await store.put(factRecordAt('fact-1', 'grey', 500))).toSucceedAndSatisfy((put) => {
+      expect(put.envelope.temporal).toEqual({ valid_at: 500 });
+    });
+    // v1's interval must close at v2's valid_at (500), not the transaction time (2000).
+    expect(await store.getById(factScope, 'fact-1-v1' as never)).toSucceedAndSatisfy((v1) => {
+      expect(v1?.envelope.temporal).toEqual({ valid_at: 1000, invalid_at: 500 });
+    });
+
+    clockValue = 3000;
+    // v3: backdated again, even further behind (100 < 500) — a SECOND correction.
+    expect(await store.put(factRecordAt('fact-1', 'black', 100))).toSucceedAndSatisfy((put) => {
+      expect(put.envelope.temporal).toEqual({ valid_at: 100 });
+    });
+    // v2's interval must close at v3's valid_at (100), not the transaction time (3000).
+    expect(await store.getById(factScope, 'fact-1-v2' as never)).toSucceedAndSatisfy((v2) => {
+      expect(v2?.envelope.temporal).toEqual({ valid_at: 500, invalid_at: 100 });
+    });
+    // `selectCurrentVersion` still resolves the newest write by `seq` (v3),
+    // regardless of `valid_at` no longer being seq-monotonic.
+    expect(await store.get(factKind, 'fact-1' as EntityId)).toSucceedAndSatisfy((cur) => {
+      expect(cur?.envelope.id).toBe('fact-1-v3');
+      expect(cur?.body).toBe('black');
+    });
+  });
+});

package/src/test/unit/store/fileTreeMemoryStore.test.ts

@@ -165,6 +165,20 @@ describe('FileTreeMemoryStore', () => {
       const root = mutableRoot([{ path: 'elsewhere/doc.md', contents: knowledgeFile('doc', 'body') }]);
       expect(createStore({ root })).toFailWith(/does not match expected scope/i);
     });
+
+    test('fails loudly when a seeded file envelope entityId disagrees with its subtree scope', () => {
+      // The id matches the filename stem and the scope round-trips, but the
+      // envelope's own entityId is foreign — a tamper/corruption the codec
+      // round-trip alone (which derives entityId from the scope path, never
+      // reading the envelope field) would not catch. entityId is trusted
+      // verbatim downstream, so the load must reject it.
+      const root = mutableRoot([
+        { path: 'knowledge/doc-a.md', contents: knowledgeFile('doc-a', 'body', { entityId: 'doc-999' }) }
+      ]);
+      expect(createStore({ root })).toFailWith(
+        /entityId 'doc-999' does not match scope-derived entityId 'doc-a'/i
+      );
+    });
   });
 
   describe('factory defaults', () => {
@@ -297,6 +311,56 @@ describe('FileTreeMemoryStore', () => {
       // doc-b was never written.
       expect(await store.get(knowledgeKind, 'doc-b' as EntityId)).toSucceedWith(undefined);
     });
+
+    test('a same-id re-put with unchanged body but revised tags applies the update (content dedup must not swallow it)', async () => {
+      // Content-scoped dedup collapses identical content across DIFFERENT ids,
+      // but a same-id re-put whose body/links are unchanged while tags change is
+      // a real LWW update: tags are outside the content hash yet inside the
+      // policy's mutableFields, so the metadata revision must reach applyUpdate.
+      const store = createStore().orThrow();
+      let firstSeq: number = -1;
+      expect(await store.put(makeRecord({ id: 'doc', body: 'same', tags: ['orig'] }))).toSucceedAndSatisfy(
+        (first: IMemoryRecord<unknown>) => {
+          firstSeq = first.envelope.seq;
+          expect(first.envelope.tags).toEqual(['orig']);
+        }
+      );
+      clockValue = 2000;
+      expect(
+        await store.put(makeRecord({ id: 'doc', body: 'same', tags: ['orig', 'added'] }))
+      ).toSucceedAndSatisfy((second: IMemoryRecord<unknown>) => {
+        expect(second.envelope.tags).toEqual(['orig', 'added']);
+        expect(second.envelope.seq).toBe(firstSeq + 1);
+        expect(second.envelope.updated).toBe(2000);
+      });
+      // The persisted record reflects the metadata update.
+      expect(await store.get(knowledgeKind, 'doc' as EntityId)).toSucceedAndSatisfy(
+        (r: IMemoryRecord<unknown> | undefined) => {
+          expect(r?.envelope.tags).toEqual(['orig', 'added']);
+        }
+      );
+    });
+
+    test('a same-id re-put with unchanged body AND unchanged metadata stays a no-op', async () => {
+      // The idempotence guard: identical content AND identical mutable metadata
+      // must not bump seq/updated (regression guard alongside the fix above).
+      const store = createStore().orThrow();
+      let firstSeq: number = -1;
+      let firstUpdated: number = -1;
+      expect(await store.put(makeRecord({ id: 'doc', body: 'same', tags: ['a'] }))).toSucceedAndSatisfy(
+        (first: IMemoryRecord<unknown>) => {
+          firstSeq = first.envelope.seq;
+          firstUpdated = first.envelope.updated;
+        }
+      );
+      clockValue = 2000;
+      expect(await store.put(makeRecord({ id: 'doc', body: 'same', tags: ['a'] }))).toSucceedAndSatisfy(
+        (second: IMemoryRecord<unknown>) => {
+          expect(second.envelope.seq).toBe(firstSeq);
+          expect(second.envelope.updated).toBe(firstUpdated);
+        }
+      );
+    });
   });
 
   describe('last-write-wins update', () => {
@@ -546,8 +610,11 @@ describe('FileTreeMemoryStore', () => {
     });
   });
 
-  describe('versioned codec (loud degradation)', () => {
+  describe('versioned codec misconfiguration', () => {
     const versionedKind: Kind = 'versioned' as Kind;
+    // A codec that reports isVersioned:true but does NOT implement the temporal
+    // codec interface (no encodeVersion/decodeVersion) — a misconfiguration the
+    // store must reject loudly rather than mis-handle.
     const versionedCodec: IIdentityCodec = {
       encode: (entityId: EntityId): Result<IIdentityCodecResult> =>
         succeed({ scope: 'versioned' as MemoryScopeKey, idStem: entityId as string, isVersioned: true }),
@@ -566,21 +633,21 @@ describe('FileTreeMemoryStore', () => {
       }).orThrow();
     }
 
-    test('put fails loudly on a versioned layout', async () => {
+    test('put fails loudly when a versioned codec omits the temporal interface', async () => {
       expect(await versionedStore().put(makeRecord({ id: 'v', kind: 'versioned', body: 'x' }))).toFailWith(
-        /versioned\/temporal layout not yet supported/i
+        /does not implement the temporal codec interface/i
       );
     });
 
-    test('get fails loudly on a versioned layout', async () => {
+    test('get fails loudly when a versioned codec omits the temporal interface', async () => {
       expect(await versionedStore().get(versionedKind, 'v' as EntityId)).toFailWith(
-        /versioned\/temporal layout not yet supported/i
+        /does not implement the temporal codec interface/i
       );
     });
 
-    test('delete fails loudly on a versioned layout', async () => {
+    test('delete fails loudly when a versioned codec omits the temporal interface', async () => {
       expect(await versionedStore().delete(versionedKind, 'v' as EntityId)).toFailWith(
-        /versioned\/temporal layout not yet supported/i
+        /does not implement the temporal codec interface/i
       );
     });
   });
@@ -718,6 +785,30 @@ describe('FileTreeMemoryStore', () => {
       });
     });
 
+    test('entity-scoped dedup: a same-id re-put with unchanged body but revised tags applies the update', async () => {
+      // The metadata-unchanged gate on the same-id no-op is shared across BOTH
+      // dedup scopes; this asserts it on the entity (experience) family too, so a
+      // future split of the two branches cannot silently regress this side.
+      const store = memoryStore();
+      let firstSeq: number = -1;
+      expect(
+        await store.put(
+          makeRecord({ id: 'turn-5', entityId: 'conv-1:5', kind: 'mtm', body: 'same', tags: ['a'] })
+        )
+      ).toSucceedAndSatisfy((r) => {
+        firstSeq = r.envelope.seq;
+        expect(r.envelope.tags).toEqual(['a']);
+      });
+      expect(
+        await store.put(
+          makeRecord({ id: 'turn-5', entityId: 'conv-1:5', kind: 'mtm', body: 'same', tags: ['a', 'b'] })
+        )
+      ).toSucceedAndSatisfy((r) => {
+        expect(r.envelope.tags).toEqual(['a', 'b']);
+        expect(r.envelope.seq).toBe(firstSeq + 1);
+      });
+    });
+
     test('merge-patch updates the body of an existing memory entity (distinct content)', async () => {
       const store = memoryStore();
       let firstCreated: number = -1;