@fgv/ts-agent-memory 5.1.0-45 → 5.1.0-47

package/.rush/temp/{bc5b0f2098f7df2a5c498ea77b0de13316349b96.tar.log → 5667e36f1c0cc503a5c20a3ebff76e7b9a702d41.tar.log}

@@ -1,5 +1,5 @@
-Start time: Tue Jul 28 2026 04:22:12 GMT+0000 (Coordinated Universal Time)
-Invoking "/usr/bin/tar -c -f /home/runner/work/fgv/fgv/common/temp/build-cache/bc5b0f2098f7df2a5c498ea77b0de13316349b96-673fc6539337f6a1.temp -z --files-from=-"
+Start time: Fri Aug 07 2026 01:16:23 GMT+0000 (Coordinated Universal Time)
+Invoking "/usr/bin/tar -c -f /home/runner/work/fgv/fgv/common/temp/build-cache/5667e36f1c0cc503a5c20a3ebff76e7b9a702d41-f9816615898c604e.temp -z --files-from=-"
 
 ======= BEGIN PROCESS INPUT ======
 .rush/temp/operation/build/all.log
@@ -77,6 +77,8 @@ dist/packlets/types/temporal.js
 dist/packlets/types/temporal.js.map
 dist/packlets/types/writePolicy.js
 dist/packlets/types/writePolicy.js.map
+dist/packlets/vector/fragmentConverters.js
+dist/packlets/vector/fragmentConverters.js.map
 dist/packlets/vector/inMemoryCosineIndex.js
 dist/packlets/vector/inMemoryCosineIndex.js.map
 dist/packlets/vector/inMemoryFragmentCosineIndex.js
@@ -97,6 +99,8 @@ dist/test/unit/ingest/antagonistCycleAndParity.test.js
 dist/test/unit/ingest/antagonistCycleAndParity.test.js.map
 dist/test/unit/ingest/cycleGuard.test.js
 dist/test/unit/ingest/cycleGuard.test.js.map
+dist/test/unit/ingest/dedupScope.test.js
+dist/test/unit/ingest/dedupScope.test.js.map
 dist/test/unit/ingest/orchestrator.test.js
 dist/test/unit/ingest/orchestrator.test.js.map
 dist/test/unit/observe/memoryObservationStore.test.js
@@ -117,6 +121,8 @@ dist/test/unit/store/fileTreeMemoryStore.test.js
 dist/test/unit/store/fileTreeMemoryStore.test.js.map
 dist/test/unit/store/fragmentEmbedOnWrite.test.js
 dist/test/unit/store/fragmentEmbedOnWrite.test.js.map
+dist/test/unit/store/indexInjection.test.js
+dist/test/unit/store/indexInjection.test.js.map
 dist/test/unit/store/lenientOpen.test.js
 dist/test/unit/store/lenientOpen.test.js.map
 dist/test/unit/store/listScoped.test.js
@@ -141,6 +147,8 @@ dist/test/unit/types/temporalPolicy.test.js
 dist/test/unit/types/temporalPolicy.test.js.map
 dist/test/unit/types/writePolicy.test.js
 dist/test/unit/types/writePolicy.test.js.map
+dist/test/unit/vector/fragmentConverters.test.js
+dist/test/unit/vector/fragmentConverters.test.js.map
 dist/test/unit/vector/inMemoryCosineIndex.test.js
 dist/test/unit/vector/inMemoryCosineIndex.test.js.map
 dist/test/unit/vector/inMemoryFragmentCosineIndex.test.js
@@ -293,6 +301,10 @@ lib/packlets/types/writePolicy.d.ts
 lib/packlets/types/writePolicy.d.ts.map
 lib/packlets/types/writePolicy.js
 lib/packlets/types/writePolicy.js.map
+lib/packlets/vector/fragmentConverters.d.ts
+lib/packlets/vector/fragmentConverters.d.ts.map
+lib/packlets/vector/fragmentConverters.js
+lib/packlets/vector/fragmentConverters.js.map
 lib/packlets/vector/inMemoryCosineIndex.d.ts
 lib/packlets/vector/inMemoryCosineIndex.d.ts.map
 lib/packlets/vector/inMemoryCosineIndex.js
@@ -333,6 +345,10 @@ lib/test/unit/ingest/cycleGuard.test.d.ts
 lib/test/unit/ingest/cycleGuard.test.d.ts.map
 lib/test/unit/ingest/cycleGuard.test.js
 lib/test/unit/ingest/cycleGuard.test.js.map
+lib/test/unit/ingest/dedupScope.test.d.ts
+lib/test/unit/ingest/dedupScope.test.d.ts.map
+lib/test/unit/ingest/dedupScope.test.js
+lib/test/unit/ingest/dedupScope.test.js.map
 lib/test/unit/ingest/orchestrator.test.d.ts
 lib/test/unit/ingest/orchestrator.test.d.ts.map
 lib/test/unit/ingest/orchestrator.test.js
@@ -373,6 +389,10 @@ lib/test/unit/store/fragmentEmbedOnWrite.test.d.ts
 lib/test/unit/store/fragmentEmbedOnWrite.test.d.ts.map
 lib/test/unit/store/fragmentEmbedOnWrite.test.js
 lib/test/unit/store/fragmentEmbedOnWrite.test.js.map
+lib/test/unit/store/indexInjection.test.d.ts
+lib/test/unit/store/indexInjection.test.d.ts.map
+lib/test/unit/store/indexInjection.test.js
+lib/test/unit/store/indexInjection.test.js.map
 lib/test/unit/store/lenientOpen.test.d.ts
 lib/test/unit/store/lenientOpen.test.d.ts.map
 lib/test/unit/store/lenientOpen.test.js
@@ -421,6 +441,10 @@ lib/test/unit/types/writePolicy.test.d.ts
 lib/test/unit/types/writePolicy.test.d.ts.map
 lib/test/unit/types/writePolicy.test.js
 lib/test/unit/types/writePolicy.test.js.map
+lib/test/unit/vector/fragmentConverters.test.d.ts
+lib/test/unit/vector/fragmentConverters.test.d.ts.map
+lib/test/unit/vector/fragmentConverters.test.js
+lib/test/unit/vector/fragmentConverters.test.js.map
 lib/test/unit/vector/inMemoryCosineIndex.test.d.ts
 lib/test/unit/vector/inMemoryCosineIndex.test.d.ts.map
 lib/test/unit/vector/inMemoryCosineIndex.test.js

package/.rush/temp/chunked-rush-logs/ts-agent-memory.build.chunks.jsonl

@@ -5,5 +5,5 @@
 {"kind":"O","text":"[build:lint] Using ESLint version 9.39.5\n"}
 {"kind":"O","text":"[build:api-extractor] Using API Extractor version 7.58.9\n"}
 {"kind":"O","text":"[build:api-extractor] Analysis will use the bundled TypeScript version 5.9.3\n"}
-{"kind":"O","text":" ---- build finished (21.343s) ---- \n"}
-{"kind":"O","text":"-------------------- Finished (21.348s) --------------------\n"}
+{"kind":"O","text":" ---- build finished (26.047s) ---- \n"}
+{"kind":"O","text":"-------------------- Finished (26.053s) --------------------\n"}

package/.rush/temp/operation/build/all.log

@@ -5,5 +5,5 @@ Invoking: heft build --clean
 [build:lint] Using ESLint version 9.39.5
 [build:api-extractor] Using API Extractor version 7.58.9
 [build:api-extractor] Analysis will use the bundled TypeScript version 5.9.3
- ---- build finished (21.343s) ---- 
--------------------- Finished (21.348s) --------------------
+ ---- build finished (26.047s) ---- 
+-------------------- Finished (26.053s) --------------------

package/.rush/temp/operation/build/log-chunks.jsonl

@@ -5,5 +5,5 @@
 {"kind":"O","text":"[build:lint] Using ESLint version 9.39.5\n"}
 {"kind":"O","text":"[build:api-extractor] Using API Extractor version 7.58.9\n"}
 {"kind":"O","text":"[build:api-extractor] Analysis will use the bundled TypeScript version 5.9.3\n"}
-{"kind":"O","text":" ---- build finished (21.343s) ---- \n"}
-{"kind":"O","text":"-------------------- Finished (21.348s) --------------------\n"}
+{"kind":"O","text":" ---- build finished (26.047s) ---- \n"}
+{"kind":"O","text":"-------------------- Finished (26.053s) --------------------\n"}

package/.rush/temp/operation/build/state.json

@@ -1,3 +1,3 @@
 {
-  "nonCachedDurationMs": 22097.002042000007
+  "nonCachedDurationMs": 26984.765819000007
 }

package/README.md

@@ -6,11 +6,12 @@ edges, content-hash dedup, and the optional-layer seams (vector / temporal /
 observe). It owns none of a consumer's processing, transformation, or
 composition logic.
 
-> **Status:** v0.1, under active development. The package is being built
-> knowledge-first. This tier (B0) ships the foundational type model and
-> converters only — no store, index, retrieval, observe, or vector code yet.
+> **Status:** under active development. The package is being built
+> knowledge-first. The surface listing below covers the foundational type model
+> and converters; the store, index, retrieval, observe, and vector layers ship
+> alongside them and are not itemized here.
 
-## B0 surface (this tier)
+## Foundational surface
 
 ### `types` packlet
 
@@ -34,6 +35,135 @@ composition logic.
   `joinFrontmatter` / `parseMemoryFile` / `serializeMemoryFile` helpers for
   the `---\n<yaml>\n---\n<body>` memory-file format.
 
+## Record updates — the merge contract
+
+When a `put` targets an `entityId` that already exists, the write is an
+**update**, not a replace. The store projects the incoming record's mutable
+fields into a patch and hands it to the kind's `IWritePolicy.applyUpdate`, which
+applies it as an **RFC-7386 JSON Merge Patch** over the policy's declared
+mutable surface. This is a **pinned contract**, not an artifact of the current
+merge configuration — the shipped policies compose `@fgv/ts-json`'s `JsonEditor`
+with `{ nullAsDelete: true, arrayMergeBehavior: 'replace' }` specifically to get
+RFC-7386 semantics, and `applyUpdate` documents them as the interface contract.
+
+Within the policy's declared mutable surface:
+
+- **Objects merge per key.** Keys you supply overwrite; keys you omit are
+  **preserved**, not dropped. An update that sets one provenance field leaves
+  every sibling field intact.
+- **An explicit `null` on a sub-key clears that sub-key.** This is the
+  sanctioned way to remove a single key from a nested object such as
+  `provenance`. The cleared key is gone from the persisted record and does not
+  reappear on reload.
+- **Arrays replace wholesale.** `tags` and `links` are not element-merged.
+- **A whole-block `null` on a required field is rejected loudly**, never
+  silently accepted. `body`, `tags`, `links`, and `provenance` are required; a
+  patch that deletes one fails with
+  `... merge patch may not delete required field(s): <names>`. (`embeddingRef`
+  is optional and *may* be cleared by a `null`, which restores it to absent
+  rather than to `null`.)
+- **Keys outside the mutable surface are ignored.** Identity and
+  transaction-time envelope fields (`id`, `entityId`, `kind`, `created`,
+  `updated`, `seq`, `contentHash`) are preserved verbatim; the store stamps
+  `updated` / `seq` / `contentHash` on write.
+
+### `provenance` is on the pinned surface
+
+`KnowledgeLwwPolicy` and `TemporalVersionedPolicy` both hard-code their mutable
+surface as `['body', 'tags', 'links', 'provenance', 'embeddingRef']`. For those
+policies the guarantees above apply to `provenance` specifically: per-key merge,
+sub-key clearing via `null`, and loud rejection of a whole-block delete are all
+part of the contract and are pinned by tests.
+
+```ts
+// existing.envelope.provenance: { source: 'agent', confidence: 0.9, note: 'stale' }
+
+// clear one sub-key; siblings survive
+policy.applyUpdate(existing, { provenance: { note: null } });
+// => provenance: { source: 'agent', confidence: 0.9 }
+
+// revise one sub-key; siblings survive
+policy.applyUpdate(existing, { provenance: { confidence: 0.5 } });
+// => provenance: { source: 'agent', confidence: 0.5, note: 'stale' }
+
+// delete the whole block — rejected, not silently accepted
+policy.applyUpdate(existing, { provenance: null });
+// => Result.fail('knowledge LWW: merge patch may not delete required field(s): provenance')
+```
+
+Going through the store rather than calling a policy directly, the same three
+cases are expressed as the `provenance` value on the record you `put`: include a
+key to set it, set a key to `null` to clear it, and omit a key to leave it
+alone. A whole-block delete is not expressible there at all —
+`IMemoryEnvelope.provenance` is non-nullable and `envelopeConverter` rejects
+`null` — so that case fails at the converter instead of at the policy. Either
+way it fails loudly.
+
+### The surface is policy-dependent
+
+`MemoryCapCullPolicy` takes its `mutableFields` from the caller, so **what it
+guarantees depends on what you declared**. A field you did not declare mutable
+is not merged at all: patch keys naming it are dropped before the merge runs, so
+a `null` on it neither clears anything nor raises an error — it is simply inert,
+and the existing value is preserved verbatim. If you want the guarantees above
+for `provenance` under a cap-cull policy, `provenance` must appear in the
+`mutableFields` you pass to `MemoryCapCullPolicy.create`.
+
+## Dedup granularity — `dedupScope`
+
+Each kind's `IWritePolicy` declares the granularity at which a write
+deduplicates against the existing vault:
+
+- **`'content'`** — scope-wide, cross-id. An identical body anywhere in the
+  scope, even under a different entity, is the same record. The knowledge
+  family (`KnowledgeLwwPolicy`) uses this.
+- **`'entity'`** — same-entity only. An identical re-put of one entity is a
+  no-op, but two *distinct* entities with coincidentally-identical bodies both
+  persist. `MemoryCapCullPolicy` and `TemporalVersionedPolicy` declare this, so
+  every experience and versioned kind gets it.
+
+Read the effective value for a kind through **`IMemoryStore.dedupScopeFor(kind)`**.
+That accessor is the single owner: it resolves the registered policy, the store's
+default policy, the policy's declaration, and finally `DEFAULT_DEDUP_SCOPE` — and
+the store's own write path reads through it too, so nothing can drift out of
+agreement with it.
+
+> **Careful:** `DEFAULT_DEDUP_SCOPE` is `'entity'`, but it is only reached when a
+> policy declares no `dedupScope`. A kind with **no registered policy** falls back
+> to the store's default policy — a `KnowledgeLwwPolicy`, which declares
+> `'content'` explicitly. So an unpoliced kind gets `'content'`, not `'entity'`.
+
+### ⚠️ Behavior change: ingest now honors `dedupScope`
+
+**This changes results for existing hosts, deliberately, with no opt-in flag.**
+
+The ingest orchestrator's stage-4 layer-1 exact match previously ignored
+`dedupScope` entirely and always behaved as `'content'` — the declaration was
+dead code on that path. It now honors the declaration, so:
+
+- A kind declaring **`'entity'`** (i.e. anything using `MemoryCapCullPolicy` or
+  `TemporalVersionedPolicy`) **no longer collapses two distinct entities that
+  share a byte-identical body** during `ingestItem` / `ingestBatch`. Candidates
+  that used to come back `deduped` now come back `written`, and the records
+  genuinely persist. If your vault silently lost turns whose summaries happened
+  to match, it will stop doing that.
+- A kind declaring **`'content'`** is unchanged.
+- A kind with **no registered policy** is unchanged (it resolves to `'content'`,
+  as above).
+
+This is the intended fix, not a regression: the same declaration already governed
+the direct `put` path, and the two paths disagreeing was the bug. It is not
+flagged, because a flag would preserve the disagreement.
+
+Independently of `dedupScope`, a `duplicate-of` collapse no longer orphans
+sibling edges. An edge built against a collapsed candidate is **redirected** to
+the record that candidate collapsed into, instead of failing the entire ingest
+item. This also fixes `'content'` kinds, where the collapse is correct but the
+ingest still should not fail.
+
+See `.claude/project/agent-memory-ingest-design.md` §1 and §3 for the full
+treatment.
+
 ## Conventions
 
 `Result<T>` on every fallible operation; no `any`; Converters/Validators for

package/dist/packlets/ingest/orchestrator.js

@@ -115,7 +115,7 @@ export class MemoryIngestOrchestrator {
         }
         // 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, scoped, byKey);
+        const edgesResult = await this._relate(item, writablePlans, MemoryIngestOrchestrator._collapseRedirects(plans), scoped, byKey);
         if (edgesResult.isFailure()) {
             return fail(edgesResult.message);
         }
@@ -211,13 +211,15 @@ export class MemoryIngestOrchestrator {
     }
     /**
      * 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
+     * the candidate's scope is a `duplicate-of`, at the granularity the kind's
+     * {@link DedupScope} declares — scope-wide for `'content'`, restricted to the
+     * candidate's own entity for `'entity'` (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, byKey) {
-        return this._findExactMatch(kind, body, addr.scope, snapshot).thenOnSuccess(async (matchId) => {
+        return this._findExactMatch(kind, body, addr, snapshot).thenOnSuccess(async (matchId) => {
             if (matchId !== undefined) {
                 // The exact-match cohort is filtered to `addr.scope`, so the match lives
                 // under that scope — its scope-qualified target is `(addr.scope, matchId)`.
@@ -269,19 +271,44 @@ export class MemoryIngestOrchestrator {
         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.
+     * Find an existing record whose `{ kind, body }` hash matches the candidate's
+     * (layer-1 exact dedup, design note §1). Invalidated temporal versions are
+     * excluded — only a live (non-temporal or current) record deduplicates a
+     * candidate.
+     *
+     * @remarks
+     * The cohort's granularity is the kind's DECLARED {@link DedupScope}, read
+     * through {@link IMemoryStore.dedupScopeFor} so this layer and the store's own
+     * write path can never disagree:
+     *
+     * - `'content'` — every live same-kind record in the candidate's scope,
+     *   regardless of entity. A cross-id body collision IS a duplicate (the
+     *   knowledge family; unchanged behavior).
+     * - `'entity'` — only records at the candidate's OWN entity address. Two
+     *   distinct entities with byte-identical bodies never collapse into one
+     *   another, which is what the declaration has always meant on the direct-put
+     *   path and now means here too.
+     *
+     * The same-id collapse itself remains the store's job — this layer only decides
+     * whether a cross-id body collision is eligible to be a `duplicate-of` at all.
      */
-    _findExactMatch(kind, body, scope, snapshot) {
+    _findExactMatch(kind, body, addr, snapshot) {
+        const dedupScope = this._store.dedupScopeFor(kind);
         // 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);
+        // cohort, narrowed to the candidate's own entity address under `'entity'`
+        // granularity. `_resolveAddress(...).orDefault()` collapses an unresolved
+        // codec to `undefined` — a non-matching address — with no explicit failure
+        // branch, exactly as the scope-only filter did before.
+        const cohort = snapshot.filter((record) => {
+            if (record.envelope.kind !== kind || (isTemporalRecord(record) && !isVersionCurrent(record))) {
+                return false;
+            }
+            const recordAddr = this._resolveAddress(record.envelope.entityId, record.envelope.kind).orDefault();
+            if (recordAddr === undefined || recordAddr.scope !== addr.scope) {
+                return false;
+            }
+            return dedupScope === 'content' || recordAddr.idStem === addr.idStem;
+        });
         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); }));
     }
     /**
@@ -300,8 +327,8 @@ export class MemoryIngestOrchestrator {
     _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, scoped, byKey) {
+    /** Stage 5 — relate (host), redirect collapsed targets, validate edges, and run the write-time cycle guard. */
+    async _relate(item, writablePlans, redirects, scoped, byKey) {
         const relationCandidates = writablePlans.map((plan) => ({
             candidate: plan.candidate,
             id: plan.refTarget
@@ -310,21 +337,79 @@ export class MemoryIngestOrchestrator {
         if (proposed.isFailure()) {
             return proposed;
         }
+        // Redirect BEFORE validation and BEFORE the cycle guard: an edge naming a
+        // collapsed candidate must be judged — and persisted — against the record it
+        // collapsed into, not against the address that no longer gets written.
+        const edges = MemoryIngestOrchestrator._redirectEdges(proposed.value, redirects);
         // refIds and the existing-record view (`byKey`, shared with the verdict path)
         // both key on the canonical scoped address, so a stem reused across scopes
         // never aliases.
         const refIds = new Set(writablePlans.map((plan) => edgeTargetKey(plan.refTarget)));
-        const validation = this._validateEdges(item, proposed.value, refIds, byKey);
+        const validation = this._validateEdges(item, edges, refIds, byKey);
         if (validation.isFailure()) {
             return fail(validation.message);
         }
         if (this._cycleGuard === 'reject') {
-            const guard = assertNoCycles(MemoryIngestOrchestrator._existingEdges(scoped), proposed.value.map((e) => ({ source: e.source, target: e.edge.target, type: e.edge.type })));
+            const guard = assertNoCycles(MemoryIngestOrchestrator._existingEdges(scoped), edges.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);
+        return succeed(edges);
+    }
+    /**
+     * The stage-5 edge-target redirect map for this pass: every `duplicate-of`
+     * candidate's OWN scoped address, mapped to the address of the record its
+     * verdict collapsed it into (design note §3).
+     *
+     * @remarks
+     * A `duplicate-of` verdict means "this candidate IS that record". The candidate
+     * is therefore not written, and its address never becomes a live reference — so
+     * a sibling edge built against it in the same pass would resolve to neither a
+     * written candidate nor an existing record and would fail the WHOLE ingest item.
+     * That is a second-order hazard of collapsing, not a defect in the edge: the
+     * host related two candidates it was correctly told about, and one of them
+     * turned out to already exist.
+     *
+     * Redirecting is the honest repair, and it is independent of {@link DedupScope}
+     * — it applies equally to a `'content'` kind, where the collapse is exactly
+     * right and the ingest still must not fail.
+     *
+     * The map cannot chain: {@link MemoryIngestOrchestrator._planFromVerdict}
+     * requires every target-bearing verdict's target to already exist in the store
+     * snapshot, so a redirect destination is always a persisted record and never
+     * another collapsed candidate. One pass is sufficient by construction.
+     */
+    static _collapseRedirects(plans) {
+        const redirects = new Map();
+        for (const plan of plans) {
+            if (plan.verdict.verdict === 'duplicate-of') {
+                redirects.set(edgeTargetKey(plan.refTarget), plan.verdict.target);
+            }
+        }
+        return redirects;
+    }
+    /**
+     * Rewrite each edge whose TARGET names a collapsed candidate to point at the
+     * record that candidate collapsed into.
+     *
+     * @remarks
+     * Only the target is redirected. An edge whose SOURCE is a collapsed candidate
+     * stays untouched and is still rejected by {@link
+     * MemoryIngestOrchestrator._validateEdges}: sources are the records an edge is
+     * written ONTO, a collapsed candidate is never written, and the relation
+     * extractor is only ever offered writable candidates as edge sources in the
+     * first place. Silently relocating such an edge onto an existing record would
+     * attribute a link the host never asked for — the loud failure is correct there.
+     */
+    static _redirectEdges(edges, redirects) {
+        if (redirects.size === 0) {
+            return edges;
+        }
+        return edges.map((e) => {
+            const to = redirects.get(edgeTargetKey(e.edge.target));
+            return to === undefined ? e : Object.assign(Object.assign({}, e), { edge: Object.assign(Object.assign({}, e.edge), { target: to }) });
+        });
     }
     /**
      * Validate stage-5 edges: each `source` must be a candidate being written; each