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

package/src/packlets/ingest/cycleGuard.ts

@@ -1,153 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import { Hash, Result, fail, mapResults, succeed } from '@fgv/ts-utils';
-import { IEdgeTarget, LinkType, edgeTargetKey } from '../types';
-
-/**
- * A directed edge in the link graph the cycle guard reasons over: scope-qualified
- * `source` links to scope-qualified `target` under relation `type`.
- * @public
- */
-export interface ICycleGuardEdge {
-  readonly source: IEdgeTarget;
-  readonly target: IEdgeTarget;
-  readonly type: LinkType;
-}
-
-/** Human-readable `scope/id` rendering of a scoped node, for cycle-guard diagnostics. */
-function formatNode(node: IEdgeTarget): string {
-  return `${node.scope}/${node.id}`;
-}
-
-/**
- * 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;
-        const sourceKey: string = edgeTargetKey(edge.source);
-        const targetKey: string = edgeTargetKey(edge.target);
-        // A self-loop is the degenerate one-node cycle.
-        if (sourceKey === targetKey) {
-          return fail(
-            `ingest cycle guard: edge '${formatNode(edge.source)}' -${edge.type}-> '${formatNode(
-              edge.target
-            )}' is a self-loop`
-          );
-        }
-        // Reachability: does `target` already reach `source`? If so, adding
-        // `source -> target` closes a directed cycle.
-        if (reaches(adjacency, targetKey, sourceKey)) {
-          return fail(
-            `ingest cycle guard: edge '${formatNode(edge.source)}' -${edge.type}-> '${formatNode(
-              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 = edgeTargetKey(keyed.edge.source);
-  const target: string = edgeTargetKey(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

@@ -1,111 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import { Result } from '@fgv/ts-utils';
-import { IEdgeTarget } 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 scope-qualified reference (codec `(scope, idStem)` — the stable entity address). */
-  readonly id: IEdgeTarget;
-}
-
-/**
- * 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

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

@@ -1,195 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import { IEdge, IEdgeTarget, 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 scope-qualified 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. A
-   * scope-qualified {@link IEdgeTarget} (not a bare {@link MemoryId}) because
-   * per-scope codecs legally reuse a stem across scopes, so a bare id would be
-   * ambiguous.
-   */
-  readonly sourceId?: IEdgeTarget;
-  /** 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 scope-qualified `(scope, id)` address. Scope-qualified
-   * (not a bare {@link MemoryId}) because per-scope codecs legally mint the same
-   * stem under different scopes — the {@link ResolutionVerdict} target the resolver
-   * returns must round-trip this exact address so the write binds the intended
-   * record.
-   */
-  readonly target: IEdgeTarget;
-  /** 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. Each target-bearing arm carries a scope-qualified
- * {@link IEdgeTarget} (not a bare {@link MemoryId}) so the verdict resolves to a
- * single record even when a filename stem is reused across scopes.
- * @public
- */
-export type ResolutionVerdict =
-  | { readonly verdict: 'new' }
-  | { readonly verdict: 'duplicate-of'; readonly target: IEdgeTarget }
-  | { readonly verdict: 'supersede'; readonly target: IEdgeTarget }
-  | { readonly verdict: 'merge-into'; readonly target: IEdgeTarget };
-
-/**
- * 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 scope-qualified reference (codec `(scope, idStem)`) of the candidate the edge originates from. */
-  readonly source: IEdgeTarget;
-  /** 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>;
-}