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

package/src/packlets/types/identityCodec.ts

@@ -51,6 +51,190 @@ export interface IIdentityCodec {
 }
 
 /**
+ * The `(entityId, version seq)` an {@link ITemporalIdentityCodec.decodeVersion}
+ * recovers from a version file address.
+ * @public
+ */
+export interface ITemporalVersionAddress {
+  /** The stable consumer-supplied domain key. */
+  readonly entityId: EntityId;
+  /** The version's monotonic `seq` (the `v<seq>` component of the file stem). */
+  readonly seq: number;
+}
+
+/**
+ * Additive extension of {@link IIdentityCodec} for versioned (temporal) kinds. A
+ * codec whose {@link IIdentityCodec.encode | encode} reports `isVersioned: true`
+ * implements this so the store can form and parse per-version filenames without
+ * knowing the layout. Non-versioned codecs do NOT implement it (probe with
+ * {@link isTemporalIdentityCodec}).
+ * @public
+ */
+export interface ITemporalIdentityCodec extends IIdentityCodec {
+  /**
+   * Form the version filename stem for a specific `(entityId, seq)`. The store
+   * appends the extension and writes it under the entity subtree returned by
+   * {@link IIdentityCodec.encode | encode}.
+   */
+  encodeVersion(entityId: EntityId, seq: number): Result<string>;
+
+  /**
+   * Parse a `(subtree scope, version stem)` back to its
+   * {@link ITemporalVersionAddress}. The subtree scope is authoritative for the
+   * `entityId`, disambiguating a stem whose `entityId` itself ends in
+   * `-v<digits>`.
+   */
+  decodeVersion(scope: MemoryScopeKey, stem: string): Result<ITemporalVersionAddress>;
+}
+
+/**
+ * Narrow an {@link IIdentityCodec} to {@link ITemporalIdentityCodec} by probing
+ * for the versioned methods. Used by the store when an `encode` result reports
+ * `isVersioned: true`.
+ * @public
+ */
+export function isTemporalIdentityCodec(codec: IIdentityCodec): codec is ITemporalIdentityCodec {
+  const candidate: Partial<ITemporalIdentityCodec> = codec as Partial<ITemporalIdentityCodec>;
+  return typeof candidate.encodeVersion === 'function' && typeof candidate.decodeVersion === 'function';
+}
+
+/**
+ * Identity codec for a versioned (temporal) kind family, resolving OQ-11 to the
+ * subtree-per-entity layout: every version of an entity is a distinct file under
+ * a per-entity subtree.
+ *
+ * @remarks
+ * - `encode`: scope = `<baseScope>/entities/<entityId>`, idStem = `<entityId>`,
+ *   `isVersioned = true`. The idStem is the stable entity prefix; the store forms
+ *   each version's filename via {@link TemporalIdentityCodec.encodeVersion}.
+ * - `encodeVersion`: version stem = `<entityId>-v<seq>`.
+ * - `decode` / `decodeVersion`: recover `entityId` (and `seq`) from a
+ *   `(subtree scope, version stem)` pair; the scope is authoritative for the
+ *   `entityId`.
+ * - Escaping: `baseScope` and `entityId` must each match the POSIX portable
+ *   filename set (they become path segments); `seq` is a non-negative integer.
+ * - Layout: `vault/<baseScope>/entities/<entityId>/<entityId>-v<seq>.md`.
+ * @public
+ */
+export class TemporalIdentityCodec implements ITemporalIdentityCodec {
+  /** The fixed subtree segment separating an entity's versions from its scope. */
+  public static readonly entitiesSegment: string = 'entities';
+  /** The version-stem infix: `<entityId>` + this + `<seq>`. */
+  public static readonly versionInfix: string = '-v';
+
+  /** A non-negative integer string (the version seq). */
+  private static readonly _versionSeqRe: RegExp = /^\d+$/;
+
+  /** The base scope segment this codec's entities live under. */
+  public readonly baseScope: string;
+
+  private constructor(baseScope: string) {
+    this.baseScope = baseScope;
+  }
+
+  /**
+   * Family-convention factory. Validates that `baseScope` is a single portable
+   * filename segment (it becomes the top-level path component).
+   */
+  public static create(baseScope: string): Result<TemporalIdentityCodec> {
+    return assertPortableFilenameStem(baseScope)
+      .withErrorFormat((msg) => `temporal codec: baseScope '${baseScope}': ${msg}`)
+      .onSuccess(() => succeed(new TemporalIdentityCodec(baseScope)));
+  }
+
+  /** {@inheritDoc IIdentityCodec.encode} */
+  public encode(entityId: EntityId): Result<IIdentityCodecResult> {
+    return assertPortableFilenameStem(entityId)
+      .withErrorFormat((msg) => `temporal codec: entityId '${entityId}': ${msg}`)
+      .onSuccess((stem) =>
+        succeed({
+          scope: `${this.baseScope}/${TemporalIdentityCodec.entitiesSegment}/${stem}` as MemoryScopeKey,
+          idStem: stem,
+          isVersioned: true
+        })
+      );
+  }
+
+  /** {@inheritDoc ITemporalIdentityCodec.encodeVersion} */
+  public encodeVersion(entityId: EntityId, seq: number): Result<string> {
+    return assertPortableFilenameStem(entityId)
+      .withErrorFormat((msg) => `temporal codec: entityId '${entityId}': ${msg}`)
+      .onSuccess((stem) => {
+        if (!Number.isInteger(seq) || seq < 0) {
+          return fail(`temporal codec: version seq '${seq}' must be a non-negative integer`);
+        }
+        return succeed(`${stem}${TemporalIdentityCodec.versionInfix}${seq}`);
+      });
+  }
+
+  /** {@inheritDoc IIdentityCodec.decode} */
+  public decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId> {
+    return this.decodeVersion(scope, encodedStem).onSuccess((addr) =>
+      Convert.entityId.convert(addr.entityId)
+    );
+  }
+
+  /** {@inheritDoc ITemporalIdentityCodec.decodeVersion} */
+  public decodeVersion(scope: MemoryScopeKey, stem: string): Result<ITemporalVersionAddress> {
+    return this._entityIdFromScope(scope).onSuccess((entityId) => {
+      const prefix: string = `${entityId}${TemporalIdentityCodec.versionInfix}`;
+      if (!stem.startsWith(prefix)) {
+        return fail(
+          `temporal codec: version stem '${stem}' must begin with '${prefix}' (from scope '${scope}')`
+        );
+      }
+      const seqText: string = stem.slice(prefix.length);
+      if (!TemporalIdentityCodec._versionSeqRe.test(seqText)) {
+        return fail(`temporal codec: version stem '${stem}' has a non-integer version suffix '${seqText}'`);
+      }
+      // The regex admits digit strings of unbounded length; `parseInt` would silently
+      // lose precision past MAX_SAFE_INTEGER, decoding a corrupt/tampered filename to a
+      // plausible-but-wrong `seq` that drives version ordering. Reject rather than corrupt.
+      const seq: number = Number.parseInt(seqText, 10);
+      if (!Number.isSafeInteger(seq)) {
+        return fail(
+          `temporal codec: version stem '${stem}' has a version suffix '${seqText}' outside the safe integer range`
+        );
+      }
+      return Convert.entityId.convert(entityId).onSuccess((branded) => succeed({ entityId: branded, seq }));
+    });
+  }
+
+  /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */
+  public verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true> {
+    return this.decodeVersion(scope, stem).onSuccess((addr) =>
+      this.encode(addr.entityId).onSuccess((encoded) =>
+        this.encodeVersion(addr.entityId, addr.seq).onSuccess((reStem) => {
+          if (encoded.scope !== scope || reStem !== stem) {
+            return fail(
+              `temporal codec: round-trip mismatch for scope '${scope}' stem '${stem}' (re-encoded to scope '${encoded.scope}' stem '${reStem}')`
+            );
+          }
+          return succeed(true);
+        })
+      )
+    );
+  }
+
+  /** Validate and extract the `entityId` from a `<baseScope>/entities/<entityId>` scope. */
+  private _entityIdFromScope(scope: MemoryScopeKey): Result<string> {
+    const segments: string[] = scope.split('/');
+    if (
+      segments.length !== 3 ||
+      segments[0] !== this.baseScope ||
+      segments[1] !== TemporalIdentityCodec.entitiesSegment
+    ) {
+      return fail(
+        `temporal codec: scope '${scope}' must be '${this.baseScope}/${TemporalIdentityCodec.entitiesSegment}/<entityId>'`
+      );
+    }
+    const entityId: string = segments[2];
+    return assertPortableFilenameStem(entityId)
+      .withErrorFormat((msg) => `temporal codec: entityId '${entityId}': ${msg}`)
+      .onSuccess(() => succeed(entityId));
+  }
+}
+
 /**
  * Identity codec for the knowledge kind family. A knowledge entity is keyed
  * by its consumer-supplied `docId`, which is used verbatim as the filename

package/src/packlets/types/index.ts

@@ -7,4 +7,5 @@ export * from './ids';
 export * from './envelope';
 export * from './filenameSafety';
 export * from './identityCodec';
+export * from './temporal';
 export * from './writePolicy';

package/src/packlets/types/temporal.ts

@@ -0,0 +1,96 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { IMemoryRecord } from './envelope';
+
+/**
+ * Whether a record participates in the versioned (temporal) layout. A temporal
+ * record always carries a {@link ITemporalBlock | temporal} block (the store
+ * stamps `valid_at` on every versioned write); an atemporal record never does,
+ * so presence of `temporal` is the discriminator. Independent of `id`/`entityId`
+ * divergence (MTM is flat yet has `entityId !== id`).
+ * @public
+ */
+export function isTemporalRecord(record: IMemoryRecord<unknown>): boolean {
+  return record.envelope.temporal !== undefined;
+}
+
+/**
+ * Whether a temporal record is a *current* version — its `temporal.invalid_at`
+ * is `null` or absent (the still-valid sentinel). A non-temporal record is never
+ * current in this sense (returns `false`).
+ * @public
+ */
+export function isVersionCurrent(record: IMemoryRecord<unknown>): boolean {
+  const temporal: IMemoryRecord<unknown>['envelope']['temporal'] = record.envelope.temporal;
+  if (temporal === undefined) {
+    return false;
+  }
+  return temporal.invalid_at === null || temporal.invalid_at === undefined;
+}
+
+/**
+ * Whether a temporal record's validity interval contains `asOf` (epoch ms):
+ * `valid_at <= asOf` and (`invalid_at` is null/absent OR `asOf < invalid_at`).
+ * The version's `valid_at` defaults to its `created` when absent; a non-temporal
+ * record is never "valid at" a point (returns `false`).
+ * @public
+ */
+export function isVersionValidAt(record: IMemoryRecord<unknown>, asOf: number): boolean {
+  const temporal: IMemoryRecord<unknown>['envelope']['temporal'] = record.envelope.temporal;
+  if (temporal === undefined) {
+    return false;
+  }
+  const start: number = temporal.valid_at ?? record.envelope.created;
+  if (start > asOf) {
+    return false;
+  }
+  const end: number | null | undefined = temporal.invalid_at;
+  if (end === null || end === undefined) {
+    return true;
+  }
+  return asOf < end;
+}
+
+/**
+ * The version with the highest `seq` among `candidates` (undefined when empty).
+ * `seq` is the store's monotonic write counter, so highest `seq` is the newest
+ * version. Shared tiebreak for {@link selectCurrentVersion} /
+ * {@link selectVersionAsOf}.
+ */
+function highestSeq(candidates: ReadonlyArray<IMemoryRecord<unknown>>): IMemoryRecord<unknown> | undefined {
+  let best: IMemoryRecord<unknown> | undefined;
+  for (const candidate of candidates) {
+    if (best === undefined || candidate.envelope.seq > best.envelope.seq) {
+      best = candidate;
+    }
+  }
+  return best;
+}
+
+/**
+ * Select the current version from a set of an entity's versions: the newest
+ * (highest `seq`) version whose `invalid_at` is null/absent. `undefined` when the
+ * entity has no current version (fully invalidated / soft-deleted, or empty).
+ * @public
+ */
+export function selectCurrentVersion(
+  versions: ReadonlyArray<IMemoryRecord<unknown>>
+): IMemoryRecord<unknown> | undefined {
+  return highestSeq(versions.filter(isVersionCurrent));
+}
+
+/**
+ * Select the version of an entity valid at `asOf` (epoch ms): the newest
+ * (highest `seq`) version whose validity interval contains `asOf`. `undefined`
+ * when no version was valid at that instant.
+ * @public
+ */
+export function selectVersionAsOf(
+  versions: ReadonlyArray<IMemoryRecord<unknown>>,
+  asOf: number
+): IMemoryRecord<unknown> | undefined {
+  return highestSeq(versions.filter((version) => isVersionValidAt(version, asOf)));
+}

package/src/packlets/types/writePolicy.ts

@@ -445,3 +445,130 @@ export class MemoryCapCullPolicy implements IWritePolicy {
     return succeed({ envelope, body: 'body' in merged ? merged.body : existing.body });
   }
 }
+
+/**
+ * Write policy for a versioned (temporal) kind family, implementing
+ * invalidate-don't-delete. Admission always accepts — history is retained, never
+ * culled — and updates apply the same RFC-7386 merge patch as
+ * {@link KnowledgeLwwPolicy}, restricted to the temporal mutable surface.
+ *
+ * @remarks
+ * The policy does NOT perform the version file writes or set `invalid_at` — that
+ * is the store's versioned write branch, driven by the kind's
+ * {@link ITemporalIdentityCodec}. The policy's role is limited to admission and
+ * the merge that forms the **new version's** content from the **current**
+ * version plus the incoming patch (the merge-patch-under-versioning contract).
+ *
+ * - **Dedup scope.** `'entity'` — an identical re-put of the current content is a
+ *   no-op (the store compares the incoming content hash against the current
+ *   version), so identical writes do not spawn redundant versions.
+ * - **Mutable surface.** `body` + the envelope metadata a consumer may revise
+ *   (`tags` / `links` / `provenance` / `embeddingRef`). `temporal` is NOT mutable
+ *   here — `valid_at` / `invalid_at` are set by the store's versioned branch.
+ * @public
+ */
+export class TemporalVersionedPolicy implements IWritePolicy {
+  /** The temporal mutable surface (mirrors {@link KnowledgeLwwPolicy}). */
+  public readonly mutableFields: ReadonlyArray<string> = [
+    'body',
+    'tags',
+    'links',
+    'provenance',
+    'embeddingRef'
+  ];
+
+  /** Versioned kinds dedup per-entity against the current version (see the class remarks). */
+  public readonly dedupScope: DedupScope = 'entity';
+
+  /** Deep-clones the mutable view without RFC-7386 null-deletion semantics. */
+  private readonly _cloneEditor: JsonEditor;
+  /** Applies the RFC-7386 merge patch. */
+  private readonly _mergeEditor: JsonEditor;
+
+  private constructor(cloneEditor: JsonEditor, mergeEditor: JsonEditor) {
+    this._cloneEditor = cloneEditor;
+    this._mergeEditor = mergeEditor;
+  }
+
+  /**
+   * Family-convention factory. Constructs the shared `JsonEditor` instances (one
+   * for cloning, one for the RFC-7386 merge), rules disabled — the same merge
+   * config as the shipped policies.
+   */
+  public static create(): Result<TemporalVersionedPolicy> {
+    return JsonEditor.create({}, []).onSuccess((cloneEditor) =>
+      JsonEditor.create(MERGE_PATCH_OPTIONS, []).onSuccess((mergeEditor) =>
+        succeed(new TemporalVersionedPolicy(cloneEditor, mergeEditor))
+      )
+    );
+  }
+
+  /** {@inheritDoc IWritePolicy.admit} */
+  public admit(
+    __incoming: IMemoryRecord<unknown>,
+    __existing: ReadonlyArray<IMemoryRecord<unknown>>
+  ): Result<AdmissionDecision> {
+    // Invalidate-don't-delete: always accept. Superseded versions are retained
+    // (invalidated), never culled.
+    return succeed({ decision: 'accept' });
+  }
+
+  /** {@inheritDoc IWritePolicy.applyUpdate} */
+  public applyUpdate(
+    existing: IMemoryRecord<unknown>,
+    patch: Record<string, unknown>
+  ): Result<IMemoryRecord<unknown>> {
+    // Project the mutable fields into a single record-level view, each sourced
+    // from its canonical location. `embeddingRef` is omitted when `undefined`.
+    const view: Record<string, unknown> = {
+      body: existing.body,
+      tags: existing.envelope.tags,
+      links: existing.envelope.links,
+      provenance: existing.envelope.provenance
+    };
+    if (existing.envelope.embeddingRef !== undefined) {
+      view.embeddingRef = existing.envelope.embeddingRef;
+    }
+
+    // Restrict the incoming patch to the declared mutable fields.
+    const scopedPatch: Record<string, unknown> = {};
+    for (const field of this.mutableFields) {
+      if (field in patch) {
+        scopedPatch[field] = patch[field];
+      }
+    }
+
+    // Clone the view (no null-deletion), then apply the RFC-7386 merge patch onto
+    // the clone so the current version is never mutated in place.
+    return this._cloneEditor
+      .mergeObjectInPlace({}, view as JsonObject)
+      .onSuccess((clone) => this._mergeEditor.mergeObjectInPlace(clone, scopedPatch as JsonObject))
+      .onSuccess((merged) => this._rebuild(existing, merged));
+  }
+
+  /**
+   * Reassemble a record from the merged mutable view. `body` / `tags` / `links` /
+   * `provenance` are required and may not be deleted by a patch; `embeddingRef`,
+   * when dropped by the merge, is restored as `undefined` (absent) — the same
+   * hash-stable semantics as {@link KnowledgeLwwPolicy}.
+   */
+  private _rebuild(existing: IMemoryRecord<unknown>, merged: JsonObject): Result<IMemoryRecord<unknown>> {
+    const required: ReadonlyArray<string> = ['body', 'tags', 'links', 'provenance'];
+    const missing: ReadonlyArray<string> = required.filter((field) => !(field in merged));
+    if (missing.length > 0) {
+      return fail(`temporal versioned: merge patch may not delete required field(s): ${missing.join(', ')}`);
+    }
+
+    // The merged values are JSON projections of the already-validated typed
+    // record; restore the domain types (structural restorations, not fresh
+    // untrusted input — mirrors KnowledgeLwwPolicy._rebuild).
+    const envelope: IMemoryEnvelope = {
+      ...existing.envelope,
+      tags: merged.tags as unknown as ReadonlyArray<Tag>,
+      links: merged.links as unknown as ReadonlyArray<IEdge>,
+      provenance: merged.provenance as unknown as IProvenance,
+      embeddingRef: 'embeddingRef' in merged ? (merged.embeddingRef as string | null) : undefined
+    };
+    return succeed({ envelope, body: merged.body });
+  }
+}

package/src/test/unit/converters/antagonistRoundTrip.test.ts

@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Antagonist torture test — convert/validate round-trip symmetry (target class
+ * 7): every OPTIONAL field the envelope/edge/provenance shapes carry must
+ * survive a full on-disk round-trip (serialize → YAML text → parse), not just a
+ * single `Converter.convert` pass in memory. This exercises the exact path a
+ * corrupted or field-dropping serializer/parser pair would break, mirroring the
+ * `aiClientToolConfig`/`annotations` field-drop class named in the brief.
+ */
+
+import '@fgv/ts-utils-jest';
+import { Converters } from '@fgv/ts-utils';
+import {
+  BodyConverterRegistry,
+  IBodyConverterRegistry,
+  IMemoryEnvelope,
+  parseMemoryFile,
+  serializeMemoryFile
+} from '../../../index';
+
+const kind = 'note' as IMemoryEnvelope['kind'];
+
+function registry(): IBodyConverterRegistry {
+  const reg = BodyConverterRegistry.create().orThrow();
+  reg.register(kind, Converters.string);
+  return reg;
+}
+
+describe('antagonist — full on-disk round-trip preserves every optional field', () => {
+  // Wrong impl this catches: a serializer/parser pair where one side silently
+  // drops an optional field (the exact class of bug the brief calls out for
+  // `aiClientToolConfig`/`annotations`-shaped converters) — e.g. omitting
+  // `temporal.invalid_at: null`, an edge's `valid_at`/`invalid_at`/`provenance`,
+  // a `null` `embeddingRef`, or a provenance extension key, because the author
+  // forgot to thread it through both the YAML emit AND the envelope Converter.
+  test('every optional envelope/edge/provenance field set simultaneously survives a full YAML round-trip', () => {
+    const envelope: IMemoryEnvelope = {
+      id: 'doc-1' as IMemoryEnvelope['id'],
+      entityId: 'doc-1' as IMemoryEnvelope['entityId'],
+      kind,
+      tags: ['t1', 't2'] as unknown as IMemoryEnvelope['tags'],
+      links: [
+        {
+          type: 'rel' as never,
+          target: 'doc-2' as never,
+          confidence: 0.42,
+          provenance: { source: 'agent', by: 'curator', extra: { nested: true } },
+          valid_at: 111,
+
+          invalid_at: null
+        }
+      ],
+      created: 1000,
+      updated: 2000,
+      seq: 7,
+      contentHash: 'abc123',
+      provenance: {
+        source: 'host-ingest',
+        by: 'erik',
+        model: 'gpt-5',
+        confidence: 0.87,
+        derivedFrom: 'turn-3' as never,
+        // Opaque extension keys (per IProvenance's `[key: string]: unknown` arm).
+        sentiment: { score: 0.5 },
+        epistemic: 'belief'
+      },
+
+      temporal: { valid_at: 500, invalid_at: null },
+
+      embeddingRef: null
+    };
+
+    const raw = serializeMemoryFile(envelope, 'the body text').orThrow();
+    expect(parseMemoryFile(raw, registry())).toSucceedAndSatisfy((record) => {
+      // Deep-equal the ENTIRE envelope, not field-by-field — a partial assertion
+      // list is exactly how a single dropped field slips through review.
+      expect(record.envelope).toEqual(envelope);
+      expect(record.body).toBe('the body text');
+    });
+  });
+
+  test('an absent temporal/embeddingRef/edge-optionals round-trips to fully absent (no null-vs-undefined drift)', () => {
+    const envelope: IMemoryEnvelope = {
+      id: 'doc-2' as IMemoryEnvelope['id'],
+      entityId: 'doc-2' as IMemoryEnvelope['entityId'],
+      kind,
+      tags: [],
+      links: [{ type: 'rel' as never, target: 'doc-3' as never }],
+      created: 0,
+      updated: 0,
+      seq: 0,
+      contentHash: '',
+      provenance: { source: 'agent' }
+    };
+    const raw = serializeMemoryFile(envelope, 'body').orThrow();
+    expect(parseMemoryFile(raw, registry())).toSucceedAndSatisfy((record) => {
+      expect(record.envelope.temporal).toBeUndefined();
+      expect(record.envelope.embeddingRef).toBeUndefined();
+      expect(record.envelope.links[0].confidence).toBeUndefined();
+      expect(record.envelope.links[0].provenance).toBeUndefined();
+      expect(record.envelope.links[0].valid_at).toBeUndefined();
+      expect(record.envelope.links[0].invalid_at).toBeUndefined();
+      expect(record.envelope).toEqual(envelope);
+    });
+  });
+});