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

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

@@ -1,226 +0,0 @@
-/*
- * 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

@@ -1,158 +0,0 @@
-/*
- * 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');
-    });
-  });
-});