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

package/src/packlets/ingest/cycleGuard.ts

@@ -0,0 +1,142 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Hash, Result, fail, mapResults, succeed } from '@fgv/ts-utils';
+import { LinkType, MemoryId } from '../types';
+
+/**
+ * A directed edge in the link graph the cycle guard reasons over: `source` links
+ * to `target` under relation `type`.
+ * @public
+ */
+export interface ICycleGuardEdge {
+  readonly source: MemoryId;
+  readonly target: MemoryId;
+  readonly type: LinkType;
+}
+
+/**
+ * Build the design's `buildCycleKey` — a deterministic, canonical (RFC-8785,
+ * via `Crc32Normalizer` from `@fgv/ts-utils`) identity for a directed edge. Used
+ * to de-duplicate proposed edges so a repeated `(source, target, type)` proposal
+ * contributes a single graph edge (and never spuriously "re-closes" a cycle).
+ * @public
+ */
+export function buildCycleKey(edge: ICycleGuardEdge): Result<string> {
+  return new Hash.Crc32Normalizer().computeHash({
+    source: edge.source,
+    target: edge.target,
+    type: edge.type
+  });
+}
+
+/**
+ * Write-time cycle guard. Given the graph's EXISTING directed edges plus a set of
+ * PROPOSED edges, verify that adding the proposed edges keeps the union graph a
+ * DAG. Fails loudly, naming the first proposed edge that would close a directed
+ * cycle.
+ *
+ * @remarks
+ * Distinct from the read-time BFS in `LinkTraversalRetriever` (which tolerates
+ * cycles via a visited-set): this is a WRITE-time admission check. Cycle
+ * detection is DFS reachability — a proposed `source -> target` edge closes a
+ * cycle iff `target` already reaches `source` in the graph built so far. Proposed
+ * edges are folded in one at a time (in order), so an intra-batch cycle
+ * (`A->B`, `B->A` both proposed) is caught as well as a batch-vs-existing cycle.
+ *
+ * See the design note §4: this enforces GLOBAL directed-acyclicity over all link
+ * types (conservative — a mutual associative pair is rejected). Callers that need
+ * mutual links disable the guard.
+ * @public
+ */
+export function assertNoCycles(
+  existing: ReadonlyArray<ICycleGuardEdge>,
+  proposed: ReadonlyArray<ICycleGuardEdge>
+): Result<true> {
+  // Canonically key every edge up front (the only fallible step); the graph
+  // building + cycle detection below is then pure.
+  return keyEdges(existing).onSuccess((existingKeyed) =>
+    keyEdges(proposed).onSuccess((proposedKeyed) => {
+      // Adjacency map, de-duplicated by canonical edge key so a repeated edge is
+      // one arc. Seed with the existing edges, then fold in each proposed edge,
+      // checking reachability BEFORE inserting it.
+      const adjacency: Map<string, Set<string>> = new Map<string, Set<string>>();
+      const seenKeys: Set<string> = new Set<string>();
+      for (const keyed of existingKeyed) {
+        addEdge(adjacency, seenKeys, keyed);
+      }
+      for (const keyed of proposedKeyed) {
+        const edge: ICycleGuardEdge = keyed.edge;
+        // A self-loop is the degenerate one-node cycle.
+        if (edge.source === edge.target) {
+          return fail(
+            `ingest cycle guard: edge '${edge.source}' -${edge.type}-> '${edge.target}' is a self-loop`
+          );
+        }
+        // Reachability: does `target` already reach `source`? If so, adding
+        // `source -> target` closes a directed cycle.
+        if (reaches(adjacency, edge.target, edge.source)) {
+          return fail(
+            `ingest cycle guard: edge '${edge.source}' -${edge.type}-> '${edge.target}' would create a cycle`
+          );
+        }
+        addEdge(adjacency, seenKeys, keyed);
+      }
+      return succeed(true);
+    })
+  );
+}
+
+/** An edge paired with its canonical cycle key. */
+interface IKeyedEdge {
+  readonly edge: ICycleGuardEdge;
+  readonly key: string;
+}
+
+/** Canonically key a set of edges (the guard's only fallible step). */
+function keyEdges(edges: ReadonlyArray<ICycleGuardEdge>): Result<ReadonlyArray<IKeyedEdge>> {
+  return mapResults(edges.map((edge) => buildCycleKey(edge).onSuccess((key) => succeed({ edge, key }))));
+}
+
+/** Add an edge to the adjacency map, de-duplicated by its canonical key. */
+function addEdge(adjacency: Map<string, Set<string>>, seenKeys: Set<string>, keyed: IKeyedEdge): void {
+  if (seenKeys.has(keyed.key)) {
+    return;
+  }
+  seenKeys.add(keyed.key);
+  const source: string = keyed.edge.source;
+  const target: string = keyed.edge.target;
+  const targets: Set<string> | undefined = adjacency.get(source);
+  if (targets === undefined) {
+    adjacency.set(source, new Set<string>([target]));
+  } else {
+    targets.add(target);
+  }
+}
+
+/** DFS reachability: is `to` reachable from `from` over `adjacency`? */
+function reaches(adjacency: ReadonlyMap<string, Set<string>>, from: string, to: string): boolean {
+  const visited: Set<string> = new Set<string>();
+  const stack: string[] = [from];
+  while (stack.length > 0) {
+    const node: string = stack.pop() as string;
+    if (node === to) {
+      return true;
+    }
+    if (visited.has(node)) {
+      continue;
+    }
+    visited.add(node);
+    const neighbors: Set<string> | undefined = adjacency.get(node);
+    if (neighbors !== undefined) {
+      for (const neighbor of neighbors) {
+        if (!visited.has(neighbor)) {
+          stack.push(neighbor);
+        }
+      }
+    }
+  }
+  return false;
+}

package/src/packlets/ingest/hostStages.ts

@@ -0,0 +1,111 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Result } from '@fgv/ts-utils';
+import { MemoryId } from '../types';
+import {
+  ICandidateEdge,
+  ICandidateRecord,
+  IEntityResolutionCandidate,
+  IIngestItem,
+  IMemoryClassification,
+  ResolutionVerdict
+} from './model';
+
+/**
+ * Stage 2 — the host's classifier. Decides what {@link IIngestItem} maps to
+ * which memory {@link Kind} (and optional tags / confidence). LOCKED as a
+ * separate staged interface (OQ-10): the host plugs its existing classifier
+ * machinery in here rather than surrendering to an opaque ingestor.
+ * @public
+ */
+export interface IMemoryClassifier {
+  /**
+   * Classify one item. A `fail` aborts the item's ingest loudly (fgv never
+   * guesses a kind).
+   */
+  classify(item: IIngestItem): Promise<Result<IMemoryClassification>>;
+}
+
+/**
+ * Stage 3 — the host's fact extractor. Turns a classified item into zero or more
+ * {@link ICandidateRecord}s. Each candidate's body is validated against the
+ * kind's registered Converter by fgv before it can reach the store (the typed
+ * validation boundary — no unchecked host data is persisted).
+ * @public
+ */
+export interface IFactExtractor {
+  /**
+   * Extract candidate records from a classified item. An empty array is a valid
+   * result (the item yielded nothing memorable).
+   */
+  extract(
+    item: IIngestItem,
+    classification: IMemoryClassification
+  ): Promise<Result<ReadonlyArray<ICandidateRecord>>>;
+}
+
+/**
+ * Stage 4 (optional) — the host's entity resolver (OQ-13, LOCKED OPTIONAL). When
+ * supplied, fgv surfaces near-duplicate {@link IEntityResolutionCandidate}s (from
+ * layer-2 similarity search) and the resolver returns a
+ * {@link ResolutionVerdict}. When ABSENT, stage-4 dedup falls back to
+ * exact-`{ kind, body }`-hash only — the deterministic-identity host path.
+ * @public
+ */
+export interface IEntityResolver {
+  /**
+   * Decide whether `candidate` is new, a duplicate of / supersedes / merges into
+   * one of the surfaced `similar` records. `similar` is non-empty and ordered by
+   * descending score when the resolver is invoked (fgv only calls it when
+   * layer-2 surfaces at least one over-threshold neighbor).
+   */
+  resolve(
+    candidate: ICandidateRecord,
+    similar: ReadonlyArray<IEntityResolutionCandidate>
+  ): Promise<Result<ResolutionVerdict>>;
+}
+
+/**
+ * The context fgv hands the host's relation extractor (stage 5): the source item
+ * plus the candidates fgv is about to write, each paired with its resolved
+ * reference id (the codec `idStem`). The extractor proposes attributed edges over
+ * these ids and existing store records.
+ * @public
+ */
+export interface IRelationContext {
+  /** The item being ingested. */
+  readonly item: IIngestItem;
+  /** The candidates fgv is about to write, each with its resolved reference id. */
+  readonly candidates: ReadonlyArray<IRelationCandidate>;
+}
+
+/**
+ * A candidate paired with its resolved reference id, handed to the relation
+ * extractor so it can source edges from it.
+ * @public
+ */
+export interface IRelationCandidate {
+  /** The candidate about to be written. */
+  readonly candidate: ICandidateRecord;
+  /** Its resolved reference id (codec `idStem` — the stable entity reference). */
+  readonly id: MemoryId;
+}
+
+/**
+ * Stage 5 — the host's relation extractor. Proposes attributed edges among the
+ * candidates and existing records. fgv owns the validation, the write-time cycle
+ * guard, and the actual persistence of the edges (the host brings only the
+ * relationship judgment).
+ * @public
+ */
+export interface IRelationExtractor {
+  /**
+   * Propose the edges to attach for this ingest. An empty array is valid (no
+   * relations). Every proposed {@link ICandidateEdge.source | source} must be one
+   * of the context's candidate reference ids.
+   */
+  relate(context: IRelationContext): Promise<Result<ReadonlyArray<ICandidateEdge>>>;
+}

package/src/packlets/ingest/index.ts

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './model';
+export * from './hostStages';
+export * from './cycleGuard';
+export * from './orchestrator';

package/src/packlets/ingest/model.ts

@@ -0,0 +1,184 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { IEdge, IMemoryEnvelope, IMemoryRecord, Kind, MemoryId, Tag } from '../types';
+
+/**
+ * A single unit of raw source material handed to the ingest pipeline. The host
+ * owns the shape of {@link IIngestItem.content | content} — fgv never interprets
+ * it; it flows opaquely into the host's classifier and extractor (stages 2-3).
+ *
+ * Single-item ingest is FIRST-CLASS: the orchestrator's primary entry point
+ * takes one `IIngestItem` (per-turn streaming), and the batch entry point is a
+ * convenience loop over it.
+ * @public
+ */
+export interface IIngestItem {
+  /**
+   * Host-owned identity for this source item. Opaque to fgv; used only in
+   * diagnostics and echoed back on the {@link IIngestItemResult}.
+   */
+  readonly id: string;
+  /**
+   * The opaque source payload the host's classifier / extractor understand
+   * (e.g. a raw turn, a document, a tool-call transcript). Never interpreted by
+   * fgv.
+   */
+  readonly content: unknown;
+  /**
+   * Optional back-link to the memory record this item was derived from (e.g. the
+   * MTM turn an extracted fact came from). When present, fgv stamps it as
+   * {@link IProvenance.derivedFrom | provenance.derivedFrom} on every record
+   * ingested from this item (stage 6) — the cross-kind provenance spine.
+   */
+  readonly sourceId?: MemoryId;
+  /** Optional opaque metadata carried alongside the item; never interpreted by fgv. */
+  readonly metadata?: Record<string, unknown>;
+}
+
+/**
+ * The host classifier's verdict for an {@link IIngestItem} (stage 2). Guides the
+ * host's own extractor (stage 3) and supplies the default `kind` / `tags` /
+ * `confidence` fgv stamps when the extractor does not override them.
+ *
+ * Extensible: the `[key: string]: unknown` arm lets the host attach an opaque
+ * classification payload without changing this interface.
+ * @public
+ */
+export interface IMemoryClassification {
+  /** The record kind the item classifies as. */
+  readonly kind: Kind;
+  /** Optional tags the classifier assigns. */
+  readonly tags?: ReadonlyArray<Tag>;
+  /** Optional classifier confidence in `[0, 1]`; flows to `provenance.confidence`. */
+  readonly confidence?: number;
+  /** Opaque, host-owned extension payload — never interpreted by fgv. */
+  readonly [key: string]: unknown;
+}
+
+/**
+ * The store-owned envelope fields fgv derives or stamps: `id` (from the codec),
+ * and the transaction-time metadata (`seq` / `contentHash` / `created` /
+ * `updated`). A {@link ICandidateRecord} supplies everything EXCEPT these.
+ * @public
+ */
+export type StoreStampedEnvelopeField = 'id' | 'seq' | 'contentHash' | 'created' | 'updated';
+
+/**
+ * A host-extracted candidate record (stage 3 output). The host supplies the
+ * full envelope MINUS the {@link StoreStampedEnvelopeField | store-stamped
+ * fields} (fgv derives `id` from the codec; the store stamps the rest) plus the
+ * typed body. Every candidate body is validated against the kind's registered
+ * Converter before it can reach the store (the typed validation boundary).
+ * @public
+ */
+export interface ICandidateRecord {
+  /** The host-supplied envelope, minus the store-stamped fields. */
+  readonly envelope: Omit<IMemoryEnvelope, StoreStampedEnvelopeField>;
+  /** The per-kind body (a markdown string in v1), validated on ingest. */
+  readonly body: unknown;
+}
+
+/**
+ * A near-duplicate candidate surfaced to the {@link IEntityResolver} by stage-4
+ * layer-2 similarity search: an existing record whose embedding is within the
+ * similarity threshold of the incoming candidate.
+ * @public
+ */
+export interface IEntityResolutionCandidate {
+  /** The existing record's id. */
+  readonly id: MemoryId;
+  /** The existing record. */
+  readonly record: IMemoryRecord<unknown>;
+  /** The backend similarity score (higher = more similar). */
+  readonly score: number;
+}
+
+/**
+ * The four dedup verdicts a {@link IEntityResolver} (or fgv's exact-match layer)
+ * returns for a candidate. See the design note §3 for the verdict → write
+ * disposition mapping.
+ * @public
+ */
+export type ResolutionVerdict =
+  | { readonly verdict: 'new' }
+  | { readonly verdict: 'duplicate-of'; readonly target: MemoryId }
+  | { readonly verdict: 'supersede'; readonly target: MemoryId }
+  | { readonly verdict: 'merge-into'; readonly target: MemoryId };
+
+/**
+ * How a candidate was ultimately written (or not) after resolution.
+ *
+ * - `written` — persisted as a fresh record (verdict `new`), or as a superseding
+ *   record (verdict `supersede`).
+ * - `deduped` — not written; an existing record satisfied it (verdict
+ *   `duplicate-of`, incl. every layer-1 exact `{ kind, body }` match).
+ * - `merged` — merged into an existing target entity (verdict `merge-into`).
+ * @public
+ */
+export type IngestDisposition = 'written' | 'deduped' | 'merged';
+
+/**
+ * A stage-5 attributed edge proposal: the {@link ICandidateEdge.edge | edge} to
+ * add, sourced from {@link ICandidateEdge.source | source}. The source MUST be a
+ * candidate being written in this ingest (edges land on the source record's
+ * `envelope.links`); the edge's `target` must resolve to a sibling candidate or
+ * an existing store record.
+ * @public
+ */
+export interface ICandidateEdge {
+  /** The reference id (codec `idStem`) of the candidate the edge originates from. */
+  readonly source: MemoryId;
+  /** The attributed edge (type / target / optional confidence / provenance). */
+  readonly edge: IEdge;
+}
+
+/**
+ * Per-candidate outcome of an ingest run.
+ * @public
+ */
+export interface IIngestedRecordResult {
+  /** The candidate the outcome is for. */
+  readonly candidate: ICandidateRecord;
+  /** The resolution verdict fgv reached (or the resolver returned). */
+  readonly resolution: ResolutionVerdict;
+  /** What the write ultimately did. */
+  readonly disposition: IngestDisposition;
+  /**
+   * The stored record's id: the newly-written id (`written` / `merged`), or the
+   * existing target's id (`deduped`).
+   */
+  readonly id: MemoryId;
+  /** The persisted record, when a write happened (`written` / `merged`). */
+  readonly record?: IMemoryRecord<unknown>;
+  /** The stage-5 edges attached to this candidate before the write. */
+  readonly edges: ReadonlyArray<ICandidateEdge>;
+  /**
+   * Informational diagnostic, set to `'temporal-versioned'` when the
+   * contradicts→temporal interlock is recognized: a `contradicts` edge was
+   * attached to a candidate of a temporal kind.
+   *
+   * @remarks
+   * A temporal kind ALWAYS writes through the store's versioned put path (that is
+   * the codec's `isVersioned` behavior — the prior version is invalidated and a
+   * new version written on every write, contradicts edge or not). This flag does
+   * NOT cause that routing; it is a diagnostic marker that the contradicts-driven
+   * scenario occurred, so callers can distinguish a contradiction-superseding
+   * version from an ordinary revision.
+   */
+  readonly interlock?: 'temporal-versioned';
+}
+
+/**
+ * The result of ingesting a single {@link IIngestItem}: the item plus the
+ * per-candidate outcomes (one item can yield zero or many candidate records).
+ * @public
+ */
+export interface IIngestItemResult {
+  /** The item that was ingested. */
+  readonly item: IIngestItem;
+  /** The per-candidate outcomes, in extraction order. */
+  readonly records: ReadonlyArray<IIngestedRecordResult>;
+}