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

package/dist/ts-agent-memory.d.ts

@@ -271,6 +271,22 @@ export declare const edgeTargetConverter: Converter<IEdgeTarget>;
  */
 export declare function edgeTargetKey(target: IEdgeTarget): string;
 
+/**
+ * Converter for an {@link IEmbeddedFragment}, and the boundary that enforces the
+ * fragment-identifiability invariant: **at least one of `locator` / `fragmentId`
+ * must be present.**
+ *
+ * @remarks
+ * The invariant lives here rather than in the type. A conditional-required union
+ * (`{ locator; fragmentId? } | { locator?; fragmentId }`) was considered and
+ * declined: it costs at every construction site and buys nothing at the read site,
+ * where each field reads as `… | undefined` either way. What it must not cost is
+ * identifiability — a fragment carrying neither identity cannot be resolved back to
+ * anything by a consumer holding the query hit, so it is rejected here.
+ * @public
+ */
+export declare const embeddedFragmentConverter: Converter<IEmbeddedFragment>;
+
 /**
  * Consumer-supplied domain key. The stable entity identity across versions;
  * the package never mints identity. Equals {@link MemoryId} for non-temporal
@@ -360,11 +376,19 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      */
     get skippedRecords(): ReadonlyArray<ISkippedRecord>;
     /**
-     * Family-convention factory. Builds the derived index and a default LWW
-     * policy, then performs an initial FileTree walk so an existing vault is
-     * indexed (and the `seq` counter resumes past the highest persisted `seq`).
+     * Family-convention factory. Resolves the derived index (the caller's
+     * {@link IFileTreeMemoryStoreCreateParams.index | index} when supplied, a fresh
+     * {@link MemoryIndex} otherwise) and a default LWW policy, then performs an
+     * initial FileTree walk so an existing vault is indexed (and the `seq` counter
+     * resumes past the highest persisted `seq`).
      */
     static create(params: IFileTreeMemoryStoreCreateParams): Result<FileTreeMemoryStore>;
+    /**
+     * Resolve the derived index for a `create()`: the caller's injected
+     * {@link IMemoryIndex} verbatim, or a fresh {@link MemoryIndex} when none was
+     * supplied (the default that keeps an omitting caller byte-identical).
+     */
+    private static _resolveIndex;
     /** {@inheritDoc IMemoryStore.get} */
     get(kind: Kind, entityId: EntityId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
     /** {@inheritDoc IMemoryStore.getById} */
@@ -625,6 +649,8 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
     private _stampRank;
     private _codecFor;
     private _policyFor;
+    /** {@inheritDoc IMemoryStore.dedupScopeFor} */
+    dedupScopeFor(kind: Kind): DedupScope;
     /**
      * Read and validate the record at `<scope>/<idStem>.md`, returning `undefined`
      * when the scope directory or file is absent. Verifies the on-disk id ↔
@@ -697,20 +723,31 @@ export declare const FRAGMENT_SEMANTIC_UNWIRED_MESSAGE: string;
  */
 export declare type FragmentEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<ReadonlyArray<IEmbeddedFragment>>>;
 
+/**
+ * Converter for an {@link IFragmentLocator}. Validates the two offsets only — the
+ * span's *meaning* (character / byte / token unit) is the consumer's, and the index
+ * never interprets it. Note the span is advisory: see {@link IFragmentLocator}.
+ * @public
+ */
+export declare const fragmentLocatorConverter: Converter<IFragmentLocator>;
+
 /**
  * The sub-document semantic-search retriever — the "discovery" half of a
  * search-then-read contract. It embeds a fragment query, queries the
  * {@link IFragmentVectorIndex}, and returns the raw per-fragment
- * {@link IVectorQueryHit | hits} (each carrying a record `target` AND the matched
- * `locator`), NOT resolved records: the consumer re-reads each record and slices it
- * by the locator on its own read side.
+ * {@link IVectorQueryHit | hits} (each carrying a record `target` AND whichever of
+ * `locator` / `fragmentId` the stored fragment was indexed with), NOT resolved
+ * records: the consumer re-reads each record and resolves the fragment on its own
+ * read side. Note the `locator` span is advisory — see {@link IFragmentLocator}; it
+ * is not a slice guaranteed to reproduce the fragment's text.
  *
  * @remarks
  * Deliberately NOT an {@link IMemoryRetriever}: memory recall is record-granular and
- * returns records; fragment discovery is span-granular and returns locators. Keeping
- * it a distinct surface matches the consumer contract (memory stays record-granular;
- * sub-document knowledge uses a separate fragment index) and avoids overloading the
- * record retriever's return type with a locator that only makes sense here.
+ * returns records; fragment discovery is fragment-granular and returns fragment
+ * identities. Keeping it a distinct surface matches the consumer contract (memory
+ * stays record-granular; sub-document knowledge uses a separate fragment index) and
+ * avoids overloading the record retriever's return type with identity fields that
+ * only make sense here.
  *
  * When no backend is wired, `supportsFragmentRecall` is `false` and any fragment
  * query degrades loudly ({@link FRAGMENT_SEMANTIC_UNWIRED_MESSAGE}) — it NEVER
@@ -1016,15 +1053,44 @@ export declare interface IEdgeTarget {
 }
 
 /**
- * One embedded fragment of a record: its in-record {@link IFragmentLocator | span}
- * and the vector for that span. Produced by a {@link FragmentEmbedder} and stored
- * via {@link IFragmentVectorIndex.addFragments}.
+ * One embedded fragment of a record: the fragment's vector, plus at least one of the
+ * two ways to identify it — its advisory in-record {@link IFragmentLocator | span}
+ * and/or an opaque consumer-minted {@link IEmbeddedFragment.fragmentId | fragmentId}.
+ * Produced by a {@link FragmentEmbedder} and stored via
+ * {@link IFragmentVectorIndex.addFragments}.
+ *
+ * @remarks
+ * Both identity fields are optional **in the type**, but the "at least one"
+ * requirement is real — a fragment carrying neither is unidentifiable at the read
+ * side. It is enforced by {@link embeddedFragmentConverter} (and re-checked by the
+ * in-package index implementations) rather than by a conditional-required union
+ * (`{ locator; fragmentId? } | { locator?; fragmentId }`), which was considered and
+ * declined: the union costs at every construction site and buys nothing at the read
+ * site, where each field reads as `… | undefined` either way.
  * @public
  */
 export declare interface IEmbeddedFragment {
-    /** The fragment's in-record span. */
-    readonly locator: IFragmentLocator;
-    /** The embedding vector for that span. */
+    /**
+     * The region of the record body this fragment was derived from, when one can be
+     * stated honestly. Advisory — see {@link IFragmentLocator}; it is NOT a slice that
+     * reproduces the fragment text. Omit it for a fragment with no honest body span (a
+     * rewriting segmenter), in which case `fragmentId` must be supplied.
+     */
+    readonly locator?: IFragmentLocator;
+    /**
+     * An opaque, consumer-minted identity for this fragment, carried verbatim through
+     * the index and returned on the corresponding {@link IVectorQueryHit}. The index
+     * **never parses it, never filters on it, and never assigns meaning to it** — it is
+     * a bytestring, not part of the query path. It exists so a fragment stays
+     * identifiable when its text is not re-derivable from the record body.
+     *
+     * The guarantee is "we never parse it", NOT "we keep it stable". Because
+     * `addFragments` is whole-record-replace, an updated record re-emits its entire
+     * fragment set, so **any stability of a fragment id across re-embeds is the
+     * consumer's responsibility**, not the index's.
+     */
+    readonly fragmentId?: string;
+    /** The embedding vector for this fragment. */
     readonly vector: Float32Array;
 }
 
@@ -1110,6 +1176,59 @@ export declare interface IFileTreeMemoryStoreCreateParams {
     readonly rankProjectors?: ReadonlyMap<Kind, RankProjector>;
     /** Default codec for kinds without an explicit entry. */
     readonly defaultCodec?: IIdentityCodec;
+    /**
+     * Optional derived-index implementation. Defaults to a fresh {@link MemoryIndex} —
+     * omitting this parameter is byte-identical to the store's behavior before the
+     * parameter existed. When supplied, the store uses it for EVERY index operation
+     * it performs and never holds a second index, so an injected index is the store's
+     * only view of its own records:
+     *
+     * - `rebuild` — once, from the initial vault walk in `create()`.
+     * - `patch` — on every persisted write, delete, version invalidation, and
+     *   cap-cull eviction.
+     * - `entries` — behind {@link IMemoryStore.list | list} /
+     *   {@link IMemoryStore.listScoped | listScoped}, the keyed temporal reads, the
+     *   write path's content-hash dedup and write-policy admission cohort, AND the
+     *   temporal (versioned) write and delete paths, which resolve an entity's
+     *   version history entirely from the index.
+     *
+     * That last group is the one to weigh before injecting anything other than a
+     * pass-through decorator: an index that filters, reorders, or otherwise reshapes
+     * `entries()` changes WRITE semantics, not just what reads return. Concretely,
+     * on a versioned kind the store derives an entity's whole version history from
+     * `entries()` filtered by scope, and that derivation decides which version a
+     * `put` treats as current (so what it dedups against and what it merges its
+     * patch over), which prior versions it stamps `invalid_at` on, what the
+     * admission cohort is, and which versions a `delete` tombstones. An index that
+     * hides a version makes it invisible to all of those — the FileTree still holds
+     * it, but the store will not supersede, invalidate, or tombstone it. On flat
+     * kinds the same reshaping changes what dedups and what a cap-cull policy
+     * evicts. A faithful delegating decorator — the intended use below — has no such
+     * effect. Note the store's keyed reads ({@link IMemoryStore.get | get} on a flat
+     * kind, and {@link IMemoryStore.getById | getById}) go to the FileTree, not the
+     * index; the FileTree remains the source of truth and the index stays a derived
+     * view.
+     *
+     * @remarks
+     * **This is an instrumentation seam, NOT a resident-memory fix.** The intended
+     * use is wrapping the shipped {@link MemoryIndex} in a decorator that counts and
+     * times the calls the store makes — resident bytes by kind, open cost against
+     * vault size, where the curve actually bends — so a decision about a partial-read
+     * redesign can be driven by measurements instead of estimates.
+     *
+     * It does NOT lower the store's resident-memory ceiling, and injecting a
+     * "persisted" or "lazy" index will not change that. {@link IMemoryIndex}'s read
+     * surface returns whole records by construction: `entries()` yields
+     * {@link IIndexedMemoryRecord}s and `byKind` / `byTag` / `byRecency` / `byRank`
+     * yield `IMemoryRecord<unknown>` — `{ envelope, body }` pairs with the body
+     * materialized. Any implementation satisfying the current contract must therefore
+     * be able to produce every body on demand. An injected index changes WHERE records
+     * come from; it does not change WHETHER bodies are held. Lowering the ceiling
+     * requires a partial-read (id-or-envelope-only) redesign of `IMemoryIndex` itself,
+     * which is separate, breaking, design-first work and is deliberately not part of
+     * this seam.
+     */
+    readonly index?: IMemoryIndex;
     /** Scope encoding. Defaults to {@link defaultMemoryScopeEncoding}. */
     readonly scopeEncoding?: (scope: MemoryScopeKey) => Result<string>;
     /**
@@ -1192,10 +1311,24 @@ export declare interface IFileTreeMemoryStoreCreateParams {
 
 /**
  * A half-open `[start, end)` span into a record's body — the in-record locator a
- * {@link IFragmentVectorIndex} carries on each fragment hit. `start` is inclusive,
+ * {@link IFragmentVectorIndex} may carry on a fragment. `start` is inclusive,
  * `end` exclusive. The unit (character / byte / token offsets) is the consumer's
  * choice: the index stores the two integers opaquely and never interprets them,
  * so they line up with whatever locator the consumer's own read side uses.
+ *
+ * @remarks
+ * **The span is advisory.** It names the region of the body a fragment was
+ * *derived from*; it is NOT a slice guaranteed to reproduce the fragment's text.
+ * `body.slice(start, end)` round-trips only under a segmenter that merely chooses
+ * boundaries. Under a **rewriting** segmenter — one that turns a span into a
+ * curated block, an increasingly common ingestion shape when a model both selects
+ * and rewrites — the fragment text is not a substring of the body at all, and the
+ * fragmentation is not re-derivable from the body. Treat the span as a pointer for
+ * locating context, never as an extraction recipe.
+ *
+ * A fragment whose provenance cannot honestly be expressed as a body span should
+ * omit the locator entirely and carry an {@link IEmbeddedFragment.fragmentId}
+ * instead.
  * @public
  */
 export declare interface IFragmentLocator {
@@ -1247,18 +1380,21 @@ export declare interface IFragmentSemanticBackend {
 
 /**
  * The fragment-granular sibling of {@link IVectorIndex}: instead of one vector per
- * record it holds many vectors per record, each tagged with an in-record
- * {@link IFragmentLocator}, and its `query` returns per-fragment hits carrying that
- * locator. This is the seam behind sub-document semantic search — the "discovery"
- * half of a search-then-read contract, where a hit's `(target, locator)` tells the
- * consumer which record AND which span to read.
+ * record it holds many vectors per record, each tagged with the identity its
+ * {@link IEmbeddedFragment} carried, and its `query` returns per-fragment hits
+ * carrying that identity back. This is the seam behind sub-document semantic search
+ * — the "discovery" half of a search-then-read contract, where a hit tells the
+ * consumer which record AND which fragment of it to read.
  *
  * @remarks
- * Deliberately NOT `extends IVectorIndex`: an index keyed by `(target, locator)`
- * has no well-defined single-vector `add(target, vector)`. It is a parallel
- * contract with three operations — `addFragments`, `remove`, `query` — reusing
- * {@link IVectorQueryHit} (whose `locator` is always populated here). Kept distinct
- * from the record-granular index per the consumer contract: memory recall stays
+ * Deliberately NOT `extends IVectorIndex`: an index holding many vectors per record
+ * has no well-defined single-vector `add(target, vector)`. It is a parallel contract
+ * with three operations — `addFragments`, `remove`, `query` — reusing
+ * {@link IVectorQueryHit}, on which both `locator` and `fragmentId` are optional. A
+ * fragment hit populates whichever of the two its stored fragment carried; see
+ * {@link IVectorQueryHit} for why that is not a discriminator and why fragment-ness
+ * is determined by the index queried, not by field presence. Kept distinct from the
+ * record-granular index per the consumer contract: memory recall stays
  * record-granular; sub-document knowledge uses a separate fragment index.
  * @public
  */
@@ -1277,7 +1413,8 @@ export declare interface IFragmentVectorIndex {
     remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
     /**
      * Return the `topK` nearest fragments to `vector`, in descending score order,
-     * each hit carrying its record `target` and fragment `locator`. When
+     * each hit carrying its record `target` plus whichever of `locator` /
+     * `fragmentId` the stored fragment was added with. When
      * `maxPerRecord` is supplied, no more than that many fragments of any single
      * record appear in the result — the cap is applied during selection (before the
      * `topK` cut) so one long document cannot crowd out others.
@@ -1441,6 +1578,15 @@ export declare interface IMemoryCapCullPolicyParams {
      * The fields a merge-patch update may touch (drawn from the record-level
      * mutable vocabulary: `body` / `tags` / `links` / `provenance` /
      * `embeddingRef`). Fields outside this list are immutable.
+     *
+     * @remarks
+     * This list — unlike {@link KnowledgeLwwPolicy}'s pinned surface — is
+     * caller-supplied, so it is what decides which fields get the RFC-7386
+     * guarantees documented on {@link IWritePolicy.applyUpdate}. Declare
+     * `provenance` here to get per-key provenance merging and `null` sub-key
+     * clearing; omit it and every provenance patch key is inert (dropped before
+     * the merge, so the existing value is preserved verbatim and even a
+     * whole-block `null` is a silent no-op rather than an error).
      */
     readonly mutableFields: ReadonlyArray<string>;
 }
@@ -1943,6 +2089,34 @@ export declare interface IMemoryStore {
      * seam's `list()` returns scope-qualified records.
      */
     asRecordSource(): IMemoryRecordSource;
+    /**
+     * The EFFECTIVE {@link DedupScope} for `kind` — the granularity at which a
+     * write for this kind deduplicates against the existing vault.
+     *
+     * @remarks
+     * This is a **read accessor over the store's already-injected write policies**,
+     * and it is the single place any caller — the store's own write path included —
+     * asks what a kind's dedup granularity is. It resolves the full chain the store
+     * applies on write: the kind's registered {@link IWritePolicy}, falling back to
+     * the store's default policy, then that policy's
+     * {@link IWritePolicy.dedupScope | dedupScope}, falling back to
+     * {@link DEFAULT_DEDUP_SCOPE}. Note the store's default policy is a
+     * {@link KnowledgeLwwPolicy}, which declares `'content'` — so a kind with NO
+     * registered policy resolves to `'content'`, not to `DEFAULT_DEDUP_SCOPE`.
+     *
+     * It exists so a caller that must agree with the store about dedup granularity
+     * — notably the ingest orchestrator's stage-4 layer-1 exact match — can read the
+     * declaration through this seam instead of being handed a second copy of the
+     * policy map. A second declaration site is precisely the defect this accessor
+     * was added to remove.
+     *
+     * Deliberately synchronous, total, and NOT `Result`-returning: it reads
+     * constructor-injected configuration, touches no I/O, and cannot fail (every
+     * link in the fallback chain has a total default). It exposes only the scope,
+     * never the {@link IWritePolicy} itself, so it can never become a back door for
+     * invoking admission or merge logic out of band.
+     */
+    dedupScopeFor(kind: Kind): DedupScope;
     /**
      * Write a record. Validates the body, computes a content hash, deduplicates
      * (scope-wide, before policy), applies the kind's {@link IWritePolicy}, stamps
@@ -2122,9 +2296,11 @@ export declare class InMemoryCosineIndex implements IVectorIndex {
 /**
  * The brute-force, in-memory cosine {@link IFragmentVectorIndex} — the
  * fragment-granular sibling of {@link InMemoryCosineIndex}. Stores many
- * `Float32Array`s per record (one per in-record {@link IFragmentLocator | span})
- * and answers a query by computing cosine similarity against every stored
- * fragment, returning the top-k fragment hits by descending score.
+ * `Float32Array`s per record (one per {@link IEmbeddedFragment | fragment}) and
+ * answers a query by computing cosine similarity against every stored fragment,
+ * returning the top-k fragment hits by descending score. Each hit carries back
+ * whichever of {@link IFragmentLocator | locator} / `fragmentId` its fragment was
+ * added with; a fragment must carry at least one of the two.
  *
  * @remarks
  * Same regime and same non-goals as {@link InMemoryCosineIndex}: no external
@@ -2452,9 +2628,27 @@ export declare interface IVectorIndex {
  * that share a stem. The caller re-resolves the hit against the record index by
  * the same scoped address.
  *
- * `locator` is present only on hits from a {@link IFragmentVectorIndex} — it
- * identifies WHICH fragment of the record matched. Record-granular
- * {@link IVectorIndex} hits omit it.
+ * **No single field discriminates a fragment hit from a record-granular hit.** A
+ * record hit carries neither `locator` nor `fragmentId`; a fragment hit carries at
+ * least one of the two, but not necessarily any particular one — a fragment with a
+ * body span but no consumer-minted id, and a fragment with an id but no honest span,
+ * are both legal. Testing one field for presence therefore cannot tell you which
+ * kind of hit you hold.
+ *
+ * That "at least one" requirement is enforced on the upsert side by
+ * {@link embeddedFragmentConverter} — a different boundary from this type — and is
+ * deliberately NOT offered here as a discriminator either. A caller keyed off it
+ * would be coupled to an invariant this type does not own, and would fail silently
+ * if the invariant were ever relaxed.
+ *
+ * **The robust rule is that fragment-ness is determined by which index produced the
+ * hit**: {@link IFragmentVectorIndex.query} returns fragment hits and
+ * {@link IVectorIndex.query} returns record hits. The caller chose the index it
+ * queried, so it already knows which kind it is holding.
+ *
+ * Note in particular that an absent `locator` now carries **two** distinct meanings
+ * — a record-granular hit, or a fragment with no honest body span (see
+ * {@link IFragmentLocator}) — which is precisely why presence-branching is unsafe.
  * @public
  */
 export declare interface IVectorQueryHit {
@@ -2462,8 +2656,18 @@ export declare interface IVectorQueryHit {
     readonly target: IEdgeTarget;
     /** Backend similarity score; higher is more similar. */
     readonly score: number;
-    /** The matched fragment's in-record span; present only for fragment-index hits. */
+    /**
+     * The advisory in-record span the matched fragment was derived from, when the
+     * producing fragment carried one. Absent on record-granular hits AND on fragment
+     * hits with no honest span — see the remarks above; do not branch on its presence.
+     */
     readonly locator?: IFragmentLocator;
+    /**
+     * The opaque identity the producing fragment was stored with, carried back
+     * verbatim. Absent on record-granular hits AND on fragment hits stored without
+     * one — see the remarks above; do not branch on its presence.
+     */
+    readonly fragmentId?: string;
 }
 
 /**
@@ -2504,6 +2708,27 @@ export declare interface IWritePolicy {
      * record. Called when admission is `accept` AND a record with the same
      * `entityId` already exists (an update, not a first write).
      *
+     * @remarks
+     * **RFC-7386 semantics are the contract here, not an artifact of the shipped
+     * policies' merge configuration.** Implementations are expected to honor them,
+     * and consumers may rely on them:
+     *
+     * - **Objects merge per key.** A supplied key overwrites; an omitted key is
+     *   PRESERVED, not dropped. Patching one key of a nested object (e.g. one
+     *   field of `provenance`) leaves its siblings intact.
+     * - **An explicit `null` on a sub-key clears exactly that sub-key.** This is
+     *   the sanctioned way to remove a single key from a nested object.
+     * - **Arrays replace wholesale** — `tags` / `links` are never element-merged.
+     * - **A whole-block `null` that would delete a REQUIRED field is rejected
+     *   loudly** (`Result.fail`), never silently accepted. `body` / `tags` /
+     *   `links` / `provenance` are required; `embeddingRef` is optional and a
+     *   `null` restores it to absent (NOT to `null`), so it stays hash-stable.
+     *
+     * Which fields these guarantees cover is **policy-dependent**: they apply to
+     * the fields the policy declares in {@link IWritePolicy.mutableFields}, and a
+     * field outside that list is inert — its patch key is dropped before the merge,
+     * so a `null` on it neither clears the value nor raises an error.
+     *
      * @param existing - The current persisted record.
      * @param patch - A partial JSON object in Merge Patch format. `null`
      * deletes the corresponding key; arrays replace wholesale; nested objects
@@ -2564,13 +2789,21 @@ export declare class KnowledgeIdentityCodec implements IIdentityCodec {
  * view, runs the merge over that view, then rebuilds a coherent record. The
  * identity and transaction-time envelope fields (`id`, `entityId`, `kind`,
  * `created`, `updated`, `seq`, `contentHash`) are NOT mutable and are
- * preserved verbatim; the store stamps `updated` / `seq` on write.
+ * preserved verbatim; the store stamps `updated` / `seq` / `contentHash` on write.
+ *
+ * Because the surface is pinned rather than caller-supplied, the RFC-7386
+ * guarantees documented on {@link IWritePolicy.applyUpdate} apply to every field
+ * listed above — in particular to `provenance`, whose keys merge individually, a
+ * `null` on any one of which clears that key alone, and a `null` on the whole
+ * block of which is rejected loudly (it is a required field). Consumers may
+ * depend on this; it is covered by tests.
  * @public
  */
 export declare class KnowledgeLwwPolicy implements IWritePolicy {
     /**
      * The knowledge mutable surface: the body plus the envelope metadata a
-     * consumer may revise without minting a new entity.
+     * consumer may revise without minting a new entity. Pinned, not
+     * caller-supplied — see the class remarks for what that guarantees.
      */
     readonly mutableFields: ReadonlyArray<string>;
     /**
@@ -2940,7 +3173,9 @@ export declare class MemoryIngestOrchestrator implements IMemoryIngestOrchestrat
     private _planFromVerdict;
     /**
      * 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).
@@ -2951,9 +3186,26 @@ export declare class MemoryIngestOrchestrator implements IMemoryIngestOrchestrat
     /** Layer-2 continuation once the candidate has a provisional record to embed. */
     private _resolveViaSimilarityEmbedded;
     /**
-     * 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.
      */
     private _findExactMatch;
     /**
@@ -2965,8 +3217,46 @@ export declare class MemoryIngestOrchestrator implements IMemoryIngestOrchestrat
     private static _recordBodyString;
     /** The stage-4 exact-dedup key over `{ kind, body }` (design note §1). */
     private _exactKey;
-    /** Stage 5 — relate (host), validate edges, and run the write-time cycle guard. */
+    /** Stage 5 — relate (host), redirect collapsed targets, validate edges, and run the write-time cycle guard. */
     private _relate;
+    /**
+     * 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.
+     */
+    private static _collapseRedirects;
+    /**
+     * 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.
+     */
+    private static _redirectEdges;
     /**
      * 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. All

package/etc/ts-agent-memory.api.md

@@ -102,6 +102,9 @@ export const edgeTargetConverter: Converter<IEdgeTarget>;
 // @public
 export function edgeTargetKey(target: IEdgeTarget): string;
 
+// @public
+export const embeddedFragmentConverter: Converter<IEmbeddedFragment>;
+
 // @public
 export type EntityId = Brand<string, 'EntityId'>;
 
@@ -115,6 +118,7 @@ export const envelopeYamlConverter: Converter<IMemoryEnvelope>;
 export class FileTreeMemoryStore implements IMemoryStore {
     asRecordSource(): IMemoryRecordSource;
     static create(params: IFileTreeMemoryStoreCreateParams): Result<FileTreeMemoryStore>;
+    dedupScopeFor(kind: Kind): DedupScope;
     delete(kind: Kind, entityId: EntityId): Promise<Result<MemoryId>>;
     get(kind: Kind, entityId: EntityId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
     getById(scope: MemoryScopeKey, id: MemoryId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
@@ -130,6 +134,9 @@ export const FRAGMENT_SEMANTIC_UNWIRED_MESSAGE: string;
 // @public
 export type FragmentEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<ReadonlyArray<IEmbeddedFragment>>>;
 
+// @public
+export const fragmentLocatorConverter: Converter<IFragmentLocator>;
+
 // @public
 export class FragmentSemanticRetriever {
     get capabilities(): IFragmentRetrieverCapabilities;
@@ -221,7 +228,8 @@ export interface IEdgeTarget {
 
 // @public
 export interface IEmbeddedFragment {
-    readonly locator: IFragmentLocator;
+    readonly fragmentId?: string;
+    readonly locator?: IFragmentLocator;
     readonly vector: Float32Array;
 }
 
@@ -250,6 +258,7 @@ export interface IFileTreeMemoryStoreCreateParams {
     readonly embed?: MemoryEmbedder;
     readonly fragmentEmbedder?: FragmentEmbedder;
     readonly fragmentIndex?: IFragmentVectorIndex;
+    readonly index?: IMemoryIndex;
     readonly logger?: Logging.ILogger;
     readonly observers?: ReadonlyArray<IMemoryObserver>;
     readonly onRecordError?: MemoryRecordErrorMode;
@@ -497,6 +506,7 @@ export interface IMemoryRetrieverCapabilities {
 // @public
 export interface IMemoryStore {
     asRecordSource(): IMemoryRecordSource;
+    dedupScopeFor(kind: Kind): DedupScope;
     delete(kind: Kind, entityId: EntityId): Promise<Result<MemoryId>>;
     get(kind: Kind, entityId: EntityId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
     getById(scope: MemoryScopeKey, id: MemoryId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
@@ -653,6 +663,7 @@ export interface IVectorIndex {
 
 // @public
 export interface IVectorQueryHit {
+    readonly fragmentId?: string;
     readonly locator?: IFragmentLocator;
     readonly score: number;
     readonly target: IEdgeTarget;