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

package/config/jest.config.json

@@ -1,5 +1,5 @@
 {
-  "extends": "@rushstack/heft-node-rig/profiles/default/config/jest.config.json",
+  "extends": "@fgv/heft-dual-rig/profiles/default/config/jest.config.json",
   "coveragePathIgnorePatterns": ["index.js"],
   "coverageThreshold": {
     "global": {

package/dist/index.js

@@ -9,4 +9,6 @@ export * from './packlets/index';
 export * from './packlets/retrieve';
 export * from './packlets/observe';
 export * from './packlets/vector';
+export * from './packlets/tools';
+export * from './packlets/ingest';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './packlets/types';\nexport * from './packlets/converters';\nexport * from './packlets/store';\nexport * from './packlets/index';\nexport * from './packlets/retrieve';\nexport * from './packlets/observe';\nexport * from './packlets/vector';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './packlets/types';\nexport * from './packlets/converters';\nexport * from './packlets/store';\nexport * from './packlets/index';\nexport * from './packlets/retrieve';\nexport * from './packlets/observe';\nexport * from './packlets/vector';\nexport * from './packlets/tools';\nexport * from './packlets/ingest';\n"]}

package/dist/packlets/ingest/cycleGuard.js

@@ -0,0 +1,111 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+import { Hash, fail, mapResults, succeed } from '@fgv/ts-utils';
+/**
+ * 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) {
+    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, proposed) {
+    // 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 = new Map();
+        const seenKeys = new Set();
+        for (const keyed of existingKeyed) {
+            addEdge(adjacency, seenKeys, keyed);
+        }
+        for (const keyed of proposedKeyed) {
+            const edge = 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);
+    }));
+}
+/** Canonically key a set of edges (the guard's only fallible step). */
+function keyEdges(edges) {
+    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, seenKeys, keyed) {
+    if (seenKeys.has(keyed.key)) {
+        return;
+    }
+    seenKeys.add(keyed.key);
+    const source = keyed.edge.source;
+    const target = keyed.edge.target;
+    const targets = adjacency.get(source);
+    if (targets === undefined) {
+        adjacency.set(source, new Set([target]));
+    }
+    else {
+        targets.add(target);
+    }
+}
+/** DFS reachability: is `to` reachable from `from` over `adjacency`? */
+function reaches(adjacency, from, to) {
+    const visited = new Set();
+    const stack = [from];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (node === to) {
+            return true;
+        }
+        if (visited.has(node)) {
+            continue;
+        }
+        visited.add(node);
+        const neighbors = adjacency.get(node);
+        if (neighbors !== undefined) {
+            for (const neighbor of neighbors) {
+                if (!visited.has(neighbor)) {
+                    stack.push(neighbor);
+                }
+            }
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=cycleGuard.js.map

package/dist/packlets/ingest/cycleGuard.js.map

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

package/dist/packlets/ingest/hostStages.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+export {};
+//# sourceMappingURL=hostStages.js.map

package/dist/packlets/ingest/hostStages.js.map

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

package/dist/packlets/ingest/index.js

@@ -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';
+//# sourceMappingURL=index.js.map

package/dist/packlets/ingest/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/ingest/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './model';\nexport * from './hostStages';\nexport * from './cycleGuard';\nexport * from './orchestrator';\n"]}

package/dist/packlets/ingest/model.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+export {};
+//# sourceMappingURL=model.js.map

package/dist/packlets/ingest/model.js.map

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

package/dist/packlets/ingest/orchestrator.js

@@ -0,0 +1,438 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+import { Hash, Logging, fail, mapResults, succeed } from '@fgv/ts-utils';
+import { Convert, isTemporalRecord, isVersionCurrent } from '../types';
+import { assertNoCycles } from './cycleGuard';
+/**
+ * The provenance source stamped on every record the ingest pipeline writes.
+ * @public
+ */
+export const HOST_INGEST_PROVENANCE_SOURCE = 'host-ingest';
+/**
+ * The link type whose presence on a temporal-kind candidate fires the
+ * contradicts→temporal-versioned interlock.
+ * @public
+ */
+export const CONTRADICTS_LINK_TYPE = 'contradicts';
+/**
+ * The default stage-4 layer-2 cosine similarity threshold (design note §2). A
+ * near-duplicate candidate is surfaced to the {@link IEntityResolver} only when
+ * its nearest neighbor scores `>= 0.85`.
+ * @public
+ */
+export const DEFAULT_SIMILARITY_THRESHOLD = 0.85;
+/**
+ * The default top-K for stage-4 layer-2 similarity candidate generation.
+ * @public
+ */
+export const DEFAULT_SIMILARITY_TOP_K = 5;
+/**
+ * Default {@link IMemoryIngestOrchestrator}.
+ * @public
+ */
+export class MemoryIngestOrchestrator {
+    constructor(params) {
+        var _a, _b, _c, _d, _e;
+        this._store = params.store;
+        this._registry = params.registry;
+        this._codecs = (_a = params.codecs) !== null && _a !== void 0 ? _a : new Map();
+        this._defaultCodec = params.defaultCodec;
+        this._classifier = params.classifier;
+        this._extractor = params.extractor;
+        this._relationExtractor = params.relationExtractor;
+        this._similarity =
+            params.entityResolver !== undefined && params.vectorIndex !== undefined && params.embed !== undefined
+                ? { resolver: params.entityResolver, vectorIndex: params.vectorIndex, embed: params.embed }
+                : undefined;
+        this._similarityThreshold = (_b = params.similarityThreshold) !== null && _b !== void 0 ? _b : DEFAULT_SIMILARITY_THRESHOLD;
+        this._similarityTopK = (_c = params.similarityTopK) !== null && _c !== void 0 ? _c : DEFAULT_SIMILARITY_TOP_K;
+        this._cycleGuard = (_d = params.cycleGuard) !== null && _d !== void 0 ? _d : 'reject';
+        this._logger = (_e = params.logger) !== null && _e !== void 0 ? _e : new Logging.NoOpLogger();
+        this._hasher = new Hash.Crc32Normalizer();
+    }
+    /** Family-convention factory. */
+    static create(params) {
+        return succeed(new MemoryIngestOrchestrator(params));
+    }
+    /** {@inheritDoc IMemoryIngestOrchestrator.ingestItem} */
+    async ingestItem(item) {
+        return (await this._classify(item))
+            .thenOnSuccess((classification) => this._extract(item, classification))
+            .thenOnSuccess((candidates) => this._processCandidates(item, candidates));
+    }
+    /** {@inheritDoc IMemoryIngestOrchestrator.ingestBatch} */
+    async ingestBatch(items) {
+        const results = [];
+        for (const item of items) {
+            const result = await this.ingestItem(item);
+            if (result.isFailure()) {
+                return fail(result.message);
+            }
+            results.push(result.value);
+        }
+        return succeed(results);
+    }
+    /** Stage 2 — classify (host), normalizing a rejected promise into a Failure. */
+    async _classify(item) {
+        return this._capture(() => this._classifier.classify(item), `ingest '${item.id}': classify`);
+    }
+    /** Stage 3 — extract (host), normalizing a rejected promise into a Failure. */
+    async _extract(item, classification) {
+        return this._capture(() => this._extractor.extract(item, classification), `ingest '${item.id}': extract`);
+    }
+    /**
+     * Stages 3b-6 over the extracted candidates: validate bodies, resolve/dedup
+     * (stage 4), relate + cycle guard (stage 5), and load-with-provenance (stage 6).
+     */
+    async _processCandidates(item, candidates) {
+        // Snapshot the store once; stage-4 resolution and the cycle guard reason over
+        // the pre-ingest state.
+        const snapshotResult = await this._store.list();
+        if (snapshotResult.isFailure()) {
+            return fail(`ingest '${item.id}': failed to snapshot store: ${snapshotResult.message}`);
+        }
+        const snapshot = snapshotResult.value;
+        const byId = MemoryIngestOrchestrator._indexById(snapshot);
+        // Stage 3b + 4: validate each body and resolve a verdict/plan.
+        const plans = [];
+        for (const candidate of candidates) {
+            const planResult = await this._planCandidate(item, candidate, snapshot, byId);
+            if (planResult.isFailure()) {
+                return fail(planResult.message);
+            }
+            plans.push(planResult.value);
+        }
+        // Stage 5: relate over the writable candidates, validate + cycle-guard.
+        const writablePlans = plans.filter((plan) => plan.verdict.verdict !== 'duplicate-of');
+        const edgesResult = await this._relate(item, writablePlans, snapshot, byId);
+        if (edgesResult.isFailure()) {
+            return fail(edgesResult.message);
+        }
+        const edges = edgesResult.value;
+        // Stage 6: load-with-provenance, in extraction order.
+        const records = [];
+        for (const plan of plans) {
+            const outcome = await this._loadCandidate(item, plan, edges);
+            if (outcome.isFailure()) {
+                return fail(outcome.message);
+            }
+            records.push(outcome.value);
+        }
+        return succeed({ item, records });
+    }
+    /** Stage 3b + 4 for one candidate: validate body, resolve address, resolve verdict. */
+    async _planCandidate(item, candidate, snapshot, byId) {
+        const kind = candidate.envelope.kind;
+        // Stage 3b: the typed validation boundary — no unchecked host body reaches the store.
+        const bodyResult = this._registry
+            .convert(kind, candidate.body)
+            .withErrorFormat((msg) => `ingest '${item.id}': candidate body for kind '${kind}' is invalid: ${msg}`)
+            .onSuccess(() => MemoryIngestOrchestrator._asStringBody(item, candidate));
+        if (bodyResult.isFailure()) {
+            return fail(bodyResult.message);
+        }
+        const body = bodyResult.value;
+        const addrResult = this._resolveAddress(candidate.envelope.entityId, kind);
+        if (addrResult.isFailure()) {
+            return fail(`ingest '${item.id}': ${addrResult.message}`);
+        }
+        const addr = addrResult.value;
+        return (await this._resolveVerdict(candidate, kind, body, addr, snapshot, byId)).onSuccess((verdict) => this._planFromVerdict(item, candidate, addr, verdict, byId));
+    }
+    /**
+     * Turn a resolved verdict into a candidate plan. A `new` verdict writes under the
+     * candidate's own address. Every TARGET-bearing verdict
+     * (`duplicate-of` / `supersede` / `merge-into`) is validated uniformly: the
+     * target must be a real store record (fgv owns validation — a non-compliant host
+     * resolver never smuggles a bogus id through) AND its kind must equal the
+     * candidate's kind (a cross-kind target would write to the wrong scope). Only
+     * `merge-into` re-addresses the write to the target's entity.
+     */
+    _planFromVerdict(item, candidate, addr, verdict, byId) {
+        if (verdict.verdict === 'new') {
+            return Convert.memoryId.convert(addr.idStem).onSuccess((refId) => succeed({
+                candidate,
+                writeAddress: addr,
+                writeEntityId: candidate.envelope.entityId,
+                refId,
+                verdict
+            }));
+        }
+        // duplicate-of | supersede | merge-into: the target must exist and share the
+        // candidate's kind.
+        const target = byId.get(verdict.target);
+        if (target === undefined) {
+            return fail(`ingest '${item.id}': ${verdict.verdict} target '${verdict.target}' does not exist in the store`);
+        }
+        if (target.envelope.kind !== candidate.envelope.kind) {
+            return fail(`ingest '${item.id}': ${verdict.verdict} target '${verdict.target}' is kind '${target.envelope.kind}' but the candidate is kind '${candidate.envelope.kind}'`);
+        }
+        if (verdict.verdict === 'merge-into') {
+            // Re-address the write to the target's entity, carrying the target record so
+            // stage 6 can UNION its existing tags/links (never overwrite them).
+            const targetEntityId = target.envelope.entityId;
+            return this._resolveAddress(targetEntityId, target.envelope.kind)
+                .withErrorFormat((msg) => `ingest '${item.id}': ${msg}`)
+                .onSuccess((targetAddr) => Convert.memoryId.convert(targetAddr.idStem).onSuccess((refId) => succeed({
+                candidate,
+                writeAddress: targetAddr,
+                writeEntityId: targetEntityId,
+                refId,
+                verdict,
+                mergeTarget: target
+            })));
+        }
+        // duplicate-of | supersede: write under the candidate's own address.
+        return Convert.memoryId.convert(addr.idStem).onSuccess((refId) => succeed({
+            candidate,
+            writeAddress: addr,
+            writeEntityId: candidate.envelope.entityId,
+            refId,
+            verdict
+        }));
+    }
+    /**
+     * Stage 4 — resolve a dedup verdict. Layer 1: an exact `{ kind, body }` match in
+     * the candidate's scope is a `duplicate-of` (design note §1). Layer 2 (only when
+     * a resolver + vector index + embedder are all wired): embed the candidate,
+     * surface over-threshold neighbors, and dispatch to the {@link IEntityResolver}.
+     * Otherwise the verdict is `new` (the exact-only fall-back path).
+     */
+    async _resolveVerdict(candidate, kind, body, addr, snapshot, byId) {
+        return this._findExactMatch(kind, body, addr.scope, snapshot).thenOnSuccess(async (matchId) => {
+            if (matchId !== undefined) {
+                return succeed({ verdict: 'duplicate-of', target: matchId });
+            }
+            const layer2 = this._similarity;
+            if (layer2 === undefined) {
+                // No layer-2: exact-only fall-back (the deterministic-identity host path).
+                return succeed({ verdict: 'new' });
+            }
+            return this._resolveViaSimilarity(candidate, addr, body, layer2, byId);
+        });
+    }
+    /** Layer-2 similarity candidate-gen + resolver dispatch. */
+    async _resolveViaSimilarity(candidate, addr, body, wiring, byId) {
+        return MemoryIngestOrchestrator._provisionalRecord(candidate, addr.idStem, body).thenOnSuccess((provisional) => this._resolveViaSimilarityEmbedded(candidate, addr, wiring, byId, provisional));
+    }
+    /** Layer-2 continuation once the candidate has a provisional record to embed. */
+    async _resolveViaSimilarityEmbedded(candidate, addr, wiring, byId, provisional) {
+        const embedded = await this._capture(() => wiring.embed(provisional), `ingest '${candidate.envelope.entityId}': embed candidate`);
+        if (embedded.isFailure()) {
+            return fail(embedded.message);
+        }
+        const queried = await this._capture(() => wiring.vectorIndex.query(embedded.value, this._similarityTopK), `ingest '${candidate.envelope.entityId}': similarity query`);
+        if (queried.isFailure()) {
+            return fail(queried.message);
+        }
+        const similar = [];
+        for (const hit of queried.value) {
+            if (hit.score < this._similarityThreshold || hit.id === addr.idStem) {
+                continue;
+            }
+            const record = byId.get(hit.id);
+            if (record !== undefined) {
+                similar.push({ id: hit.id, record, score: hit.score });
+            }
+        }
+        if (similar.length === 0) {
+            return succeed({ verdict: 'new' });
+        }
+        return this._capture(() => wiring.resolver.resolve(candidate, similar), `ingest '${candidate.envelope.entityId}': resolve`);
+    }
+    /**
+     * Find an existing record in `scope` whose `{ kind, body }` hash matches the
+     * candidate's (layer-1 exact dedup). Invalidated temporal versions are excluded
+     * — only a live (non-temporal or current) record deduplicates a candidate.
+     */
+    _findExactMatch(kind, body, scope, snapshot) {
+        // Same-kind, same-scope, LIVE (non-temporal or current) records are the exact
+        // cohort. `_resolveAddress(...).map(...).orDefault()` collapses an unresolved
+        // codec to a non-matching scope with no explicit failure branch.
+        const cohort = snapshot.filter((record) => record.envelope.kind === kind &&
+            !(isTemporalRecord(record) && !isVersionCurrent(record)) &&
+            this._resolveAddress(record.envelope.entityId, record.envelope.kind)
+                .onSuccess((addr) => succeed(addr.scope))
+                .orDefault() === scope);
+        return this._exactKey(kind, body).onSuccess((key) => mapResults(cohort.map((record) => MemoryIngestOrchestrator._recordBodyString(record).onSuccess((recordBody) => this._exactKey(record.envelope.kind, recordBody).onSuccess((recordKey) => succeed({ id: record.envelope.id, key: recordKey }))))).onSuccess((keyed) => { var _a; return succeed((_a = keyed.find((entry) => entry.key === key)) === null || _a === void 0 ? void 0 : _a.id); }));
+    }
+    /**
+     * The body of a persisted record, required to be a string (the store persists
+     * only string bodies). Fails loudly rather than blind-casting an `unknown` body
+     * into the exact-dedup hash — a non-string existing body is a store-integrity
+     * fault, surfaced with context, not a silent miscompute.
+     */
+    static _recordBodyString(record) {
+        if (typeof record.body !== 'string') {
+            return fail(`ingest: stored record '${record.envelope.id}' has a non-string body (got ${typeof record.body})`);
+        }
+        return succeed(record.body);
+    }
+    /** The stage-4 exact-dedup key over `{ kind, body }` (design note §1). */
+    _exactKey(kind, body) {
+        return this._hasher.computeHash({ kind, body });
+    }
+    /** Stage 5 — relate (host), validate edges, and run the write-time cycle guard. */
+    async _relate(item, writablePlans, snapshot, byId) {
+        const relationCandidates = writablePlans.map((plan) => ({
+            candidate: plan.candidate,
+            id: plan.refId
+        }));
+        const proposed = await this._capture(() => this._relationExtractor.relate({ item, candidates: relationCandidates }), `ingest '${item.id}': relate`);
+        if (proposed.isFailure()) {
+            return proposed;
+        }
+        const refIds = new Set(writablePlans.map((plan) => plan.refId));
+        const validation = this._validateEdges(item, proposed.value, refIds, byId);
+        if (validation.isFailure()) {
+            return fail(validation.message);
+        }
+        if (this._cycleGuard === 'reject') {
+            const guard = assertNoCycles(MemoryIngestOrchestrator._existingEdges(snapshot), proposed.value.map((e) => ({ source: e.source, target: e.edge.target, type: e.edge.type })));
+            if (guard.isFailure()) {
+                return fail(`ingest '${item.id}': ${guard.message}`);
+            }
+        }
+        return succeed(proposed.value);
+    }
+    /**
+     * Validate stage-5 edges: each `source` must be a candidate being written; each
+     * `target` must resolve to a sibling candidate or an existing store record.
+     */
+    _validateEdges(item, edges, refIds, byId) {
+        return mapResults(edges.map((edge) => {
+            if (!refIds.has(edge.source)) {
+                return fail(`ingest '${item.id}': edge source '${edge.source}' is not a candidate being written`);
+            }
+            if (!refIds.has(edge.edge.target) && byId.get(edge.edge.target) === undefined) {
+                return fail(`ingest '${item.id}': edge target '${edge.edge.target}' resolves to neither a sibling candidate nor an existing record`);
+            }
+            return succeed(true);
+        })).onSuccess(() => succeed(true));
+    }
+    /** Stage 6 — stamp provenance + edges, admit through the store, record the outcome. */
+    async _loadCandidate(item, plan, allEdges) {
+        const myEdges = allEdges.filter((e) => e.source === plan.refId);
+        if (plan.verdict.verdict === 'duplicate-of') {
+            // No write: the existing target satisfied the candidate. The target id is a
+            // typed field of the narrowed `duplicate-of` verdict — no cast, no guard.
+            return succeed({
+                candidate: plan.candidate,
+                resolution: plan.verdict,
+                disposition: 'deduped',
+                id: plan.verdict.target,
+                edges: myEdges
+            });
+        }
+        return this._buildRecord(item, plan, myEdges).thenOnSuccess(async (record) => (await this._store.put(record))
+            .withErrorFormat((msg) => `ingest '${item.id}': write failed: ${msg}`)
+            .onSuccess((persisted) => {
+            const disposition = plan.verdict.verdict === 'merge-into' ? 'merged' : 'written';
+            const interlock = plan.writeAddress.isVersioned && myEdges.some((e) => e.edge.type === CONTRADICTS_LINK_TYPE)
+                ? 'temporal-versioned'
+                : undefined;
+            return succeed(Object.assign({ candidate: plan.candidate, resolution: plan.verdict, disposition, id: persisted.envelope.id, record: persisted, edges: myEdges }, (interlock !== undefined ? { interlock } : {})));
+        }));
+    }
+    /** Build the fully-stamped record to persist (provenance + edges + placeholder txn fields). */
+    _buildRecord(item, plan, myEdges) {
+        const base = plan.candidate.envelope;
+        // For merge-into the store's `applyUpdate` REPLACES array fields wholesale, so
+        // the persisted envelope must already carry the UNION of the target's existing
+        // tags/links/provenance and the candidate's — otherwise the merge silently
+        // wipes the target's prior links/tags.
+        const target = plan.mergeTarget;
+        const priorLinks = target !== undefined ? target.envelope.links : [];
+        const priorTags = target !== undefined ? target.envelope.tags : [];
+        const priorProvenance = target !== undefined ? target.envelope.provenance : { source: '' };
+        return Convert.memoryId.convert(plan.writeAddress.idStem).onSuccess((id) => 
+        // Dedup the combined links by canonical edge key: the target's prior links, the
+        // candidate's own links, and the stage-5 edges (two candidates that resolve
+        // merge-into the SAME target share a `refId` — hence the same `myEdges` — and a
+        // relation extractor may repeat an edge) each appear exactly once.
+        this._dedupEdges([...priorLinks, ...base.links, ...myEdges.map((e) => e.edge)]).onSuccess((links) => {
+            const provenance = Object.assign(Object.assign(Object.assign(Object.assign({}, (target !== undefined ? priorProvenance : {})), base.provenance), { source: HOST_INGEST_PROVENANCE_SOURCE }), (item.sourceId !== undefined ? { derivedFrom: item.sourceId } : {}));
+            const envelope = Object.assign(Object.assign({}, base), { id, entityId: plan.writeEntityId, seq: 0, contentHash: '', created: 0, updated: 0, provenance, tags: MemoryIngestOrchestrator._unionTags(priorTags, base.tags), links });
+            return succeed({ envelope, body: plan.candidate.body });
+        }));
+    }
+    /** Union two tag lists, de-duplicated, preserving first-occurrence order. */
+    static _unionTags(prior, incoming) {
+        const seen = new Set();
+        const out = [];
+        for (const tag of [...prior, ...incoming]) {
+            if (!seen.has(tag)) {
+                seen.add(tag);
+                out.push(tag);
+            }
+        }
+        return out;
+    }
+    /** De-duplicate a link list by canonical edge hash, preserving first-occurrence order. */
+    _dedupEdges(edges) {
+        const seen = new Set();
+        const deduped = [];
+        return mapResults(edges.map((edge) => this._hasher.computeHash(edge).onSuccess((key) => {
+            if (!seen.has(key)) {
+                seen.add(key);
+                deduped.push(edge);
+            }
+            return succeed(key);
+        }))).onSuccess(() => succeed(deduped));
+    }
+    /** Resolve a `(kind, entityId)` to its storage address via the registered codec. */
+    _resolveAddress(entityId, kind) {
+        var _a;
+        const codec = (_a = this._codecs.get(kind)) !== null && _a !== void 0 ? _a : this._defaultCodec;
+        if (codec === undefined) {
+            return fail(`no identity codec registered for kind '${kind}'`);
+        }
+        return codec.encode(entityId);
+    }
+    /** Run a host hook, normalizing a thrown/rejected hook into a Failure (never throws across the seam). */
+    async _capture(op, label) {
+        try {
+            return await op();
+        }
+        catch (err) {
+            const message = `${label} threw: ${String(err)}`;
+            this._logger.warn(message);
+            return fail(message);
+        }
+    }
+    /** Index a record snapshot by id (last write wins on an id collision across scopes). */
+    static _indexById(records) {
+        const byId = new Map();
+        for (const record of records) {
+            byId.set(record.envelope.id, record);
+        }
+        return byId;
+    }
+    /** Every existing outbound edge in the snapshot, as cycle-guard edges. */
+    static _existingEdges(records) {
+        const edges = [];
+        for (const record of records) {
+            for (const edge of record.envelope.links) {
+                edges.push({ source: record.envelope.id, target: edge.target, type: edge.type });
+            }
+        }
+        return edges;
+    }
+    /** A provisional record for embedding a candidate (placeholder txn-time fields). */
+    static _provisionalRecord(candidate, idStem, body) {
+        return Convert.memoryId.convert(idStem).onSuccess((id) => {
+            const envelope = Object.assign(Object.assign({}, candidate.envelope), { id, seq: 0, contentHash: '', created: 0, updated: 0 });
+            return succeed({ envelope, body });
+        });
+    }
+    /** Require a candidate body to be a string (the store persists only string bodies). */
+    static _asStringBody(item, candidate) {
+        if (typeof candidate.body !== 'string') {
+            return fail(`ingest '${item.id}': candidate body for kind '${candidate.envelope.kind}' must be a string (got ${typeof candidate.body})`);
+        }
+        return succeed(candidate.body);
+    }
+}
+//# sourceMappingURL=orchestrator.js.map