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

package/src/packlets/ingest/orchestrator.ts

@@ -6,6 +6,7 @@
 import { Hash, Logging, Result, fail, mapResults, succeed } from '@fgv/ts-utils';
 import {
   Convert,
+  DedupScope,
   EntityId,
   IEdge,
   IEdgeTarget,
@@ -17,7 +18,6 @@ import {
   Kind,
   LinkType,
   MemoryId,
-  MemoryScopeKey,
   Tag,
   edgeTargetKey,
   isTemporalRecord,
@@ -310,6 +310,7 @@ export class MemoryIngestOrchestrator implements IMemoryIngestOrchestrator {
     const edgesResult: Result<ReadonlyArray<ICandidateEdge>> = await this._relate(
       item,
       writablePlans,
+      MemoryIngestOrchestrator._collapseRedirects(plans),
       scoped,
       byKey
     );
@@ -443,7 +444,9 @@ export class MemoryIngestOrchestrator implements IMemoryIngestOrchestrator {
 
   /**
    * 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).
@@ -456,7 +459,7 @@ export class MemoryIngestOrchestrator implements IMemoryIngestOrchestrator {
     snapshot: ReadonlyArray<IMemoryRecord<unknown>>,
     byKey: ReadonlyMap<string, IMemoryRecord<unknown>>
   ): Promise<Result<ResolutionVerdict>> {
-    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)`.
@@ -534,27 +537,52 @@ export class MemoryIngestOrchestrator implements IMemoryIngestOrchestrator {
   }
 
   /**
-   * 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(
     kind: Kind,
     body: string,
-    scope: MemoryScopeKey,
+    addr: IIdentityCodecResult,
     snapshot: ReadonlyArray<IMemoryRecord<unknown>>
   ): Result<MemoryId | undefined> {
+    const dedupScope: 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: ReadonlyArray<IMemoryRecord<unknown>> = 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: ReadonlyArray<IMemoryRecord<unknown>> = snapshot.filter((record) => {
+      if (record.envelope.kind !== kind || (isTemporalRecord(record) && !isVersionCurrent(record))) {
+        return false;
+      }
+      const recordAddr: IIdentityCodecResult | undefined = 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) =>
@@ -588,10 +616,11 @@ export class MemoryIngestOrchestrator implements IMemoryIngestOrchestrator {
     return this._hasher.computeHash({ kind, body });
   }
 
-  /** 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 async _relate(
     item: IIngestItem,
     writablePlans: ReadonlyArray<ICandidatePlan>,
+    redirects: ReadonlyMap<string, IEdgeTarget>,
     scoped: ReadonlyArray<IScopedRecord>,
     byKey: ReadonlyMap<string, IMemoryRecord<unknown>>
   ): Promise<Result<ReadonlyArray<ICandidateEdge>>> {
@@ -606,26 +635,92 @@ export class MemoryIngestOrchestrator implements IMemoryIngestOrchestrator {
     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: ReadonlyArray<ICandidateEdge> = 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: ReadonlySet<string> = new Set<string>(
       writablePlans.map((plan) => edgeTargetKey(plan.refTarget))
     );
-    const validation: Result<true> = this._validateEdges(item, proposed.value, refIds, byKey);
+    const validation: Result<true> = this._validateEdges(item, edges, refIds, byKey);
     if (validation.isFailure()) {
       return fail(validation.message);
     }
     if (this._cycleGuard === 'reject') {
       const guard: Result<true> = assertNoCycles(
         MemoryIngestOrchestrator._existingEdges(scoped),
-        proposed.value.map((e) => ({ source: e.source, target: e.edge.target, type: e.edge.type }))
+        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.
+   */
+  private static _collapseRedirects(plans: ReadonlyArray<ICandidatePlan>): ReadonlyMap<string, IEdgeTarget> {
+    const redirects: Map<string, IEdgeTarget> = new Map<string, IEdgeTarget>();
+    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.
+   */
+  private static _redirectEdges(
+    edges: ReadonlyArray<ICandidateEdge>,
+    redirects: ReadonlyMap<string, IEdgeTarget>
+  ): ReadonlyArray<ICandidateEdge> {
+    if (redirects.size === 0) {
+      return edges;
+    }
+    return edges.map((e) => {
+      const to: IEdgeTarget | undefined = redirects.get(edgeTargetKey(e.edge.target));
+      return to === undefined ? e : { ...e, edge: { ...e.edge, target: to } };
+    });
   }
 
   /**

package/src/packlets/retrieve/fragmentSemanticRetriever.ts

@@ -60,16 +60,19 @@ export interface IFragmentRetrieverCapabilities {
  * 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

package/src/packlets/store/fileTreeMemoryStore.ts

@@ -147,6 +147,35 @@ export interface IMemoryStore {
    */
   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
@@ -194,6 +223,59 @@ export 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>;
   /**
@@ -412,13 +494,15 @@ export class FileTreeMemoryStore implements IMemoryStore {
   }
 
   /**
-   * 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`).
    */
   public static create(params: IFileTreeMemoryStoreCreateParams): Result<FileTreeMemoryStore> {
     return KnowledgeLwwPolicy.create().onSuccess((defaultPolicy) =>
-      MemoryIndex.create().onSuccess((index) => {
+      FileTreeMemoryStore._resolveIndex(params.index).onSuccess((index) => {
         const store: FileTreeMemoryStore = new FileTreeMemoryStore({
           root: params.root,
           registry: params.registry,
@@ -442,6 +526,21 @@ export class FileTreeMemoryStore implements IMemoryStore {
     );
   }
 
+  /**
+   * 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(index: IMemoryIndex | undefined): Result<IMemoryIndex> {
+    // Nullish rather than strictly-undefined, matching how every sibling optional
+    // param in `create()` handles absence (`params.codecs ?? new Map()`, and so on).
+    // A JS caller — or a TS caller arriving through an `unknown` escape hatch —
+    // passing `null` otherwise gets `null` installed as the store's index and fails
+    // later inside `entries()` with a message that names neither the param nor the
+    // cause.
+    return index ? succeed(index) : MemoryIndex.create();
+  }
+
   /** {@inheritDoc IMemoryStore.get} */
   public async get(kind: Kind, entityId: EntityId): Promise<Result<IMemoryRecord<unknown> | undefined>> {
     const result: Result<IMemoryRecord<unknown> | undefined> = this._codecFor(kind).onSuccess((codec) =>
@@ -741,7 +840,10 @@ export class FileTreeMemoryStore implements IMemoryStore {
     hash: string
   ): Promise<Result<IPutOutcome>> {
     const policy: IWritePolicy = this._policyFor(record.envelope.kind);
-    const dedupScope: DedupScope = policy.dedupScope ?? DEFAULT_DEDUP_SCOPE;
+    // Read through the public accessor so the write path and every external
+    // caller (the ingest orchestrator's layer-1) resolve dedup granularity from
+    // ONE place — there is no second declaration site.
+    const dedupScope: DedupScope = this.dedupScopeFor(record.envelope.kind);
     // Content-hash dedup runs BEFORE policy. Its granularity is the kind's
     // `dedupScope`:
     //   - 'content': an identical { kind, body, links } triple ANYWHERE in the
@@ -1171,7 +1273,8 @@ export class FileTreeMemoryStore implements IMemoryStore {
     const priorCurrents: ReadonlyArray<IMemoryRecord<unknown>> = versions.filter(isVersionCurrent);
     const current: IMemoryRecord<unknown> | undefined = selectCurrentVersion(versions);
     const policy: IWritePolicy = this._policyFor(kind);
-    const dedupScope: DedupScope = policy.dedupScope ?? DEFAULT_DEDUP_SCOPE;
+    // Same single-owner read as the flat path (see `_writeResolved`).
+    const dedupScope: DedupScope = this.dedupScopeFor(kind);
     return this._contentHash(kind, body, envelope.links).thenOnSuccess((hash) => {
       // Entity-scoped dedup: a re-put is a no-op only when the CURRENT content AND
       // its mutable metadata are unchanged (does not spawn a redundant version).
@@ -1514,6 +1617,11 @@ export class FileTreeMemoryStore implements IMemoryStore {
     return this._writePolicies.get(kind) ?? this._defaultPolicy;
   }
 
+  /** {@inheritDoc IMemoryStore.dedupScopeFor} */
+  public dedupScopeFor(kind: Kind): DedupScope {
+    return this._policyFor(kind).dedupScope ?? DEFAULT_DEDUP_SCOPE;
+  }
+
   /**
    * Read and validate the record at `<scope>/<idStem>.md`, returning `undefined`
    * when the scope directory or file is absent. Verifies the on-disk id ↔

package/src/packlets/types/writePolicy.ts

@@ -90,6 +90,27 @@ export 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
@@ -133,13 +154,21 @@ const MERGE_PATCH_OPTIONS: Partial<IJsonEditorOptions> = {
  * 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 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.
    */
   public readonly mutableFields: ReadonlyArray<string> = [
     'body',
@@ -271,6 +300,15 @@ export 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>;
 }

package/src/packlets/vector/fragmentConverters.ts

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Converter, Converters, Result, fail, succeed } from '@fgv/ts-utils';
+import { IEmbeddedFragment, IFragmentLocator } from './vectorIndex';
+
+/**
+ * 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 const fragmentLocatorConverter: Converter<IFragmentLocator> = Converters.object<IFragmentLocator>({
+  start: Converters.number,
+  end: Converters.number
+});
+
+/** Validates an already-constructed `Float32Array` embedding vector in place. */
+const embeddingVectorConverter: Converter<Float32Array> = Converters.generic<Float32Array>(
+  (from: unknown): Result<Float32Array> =>
+    from instanceof Float32Array ? succeed(from) : fail('embedded fragment: vector must be a Float32Array')
+);
+
+/** The field-shape half of {@link embeddedFragmentConverter}; the invariant is layered on top. */
+const embeddedFragmentFieldsConverter: Converter<IEmbeddedFragment> = Converters.object<IEmbeddedFragment>(
+  {
+    locator: fragmentLocatorConverter.optional(),
+    fragmentId: Converters.string.optional(),
+    vector: embeddingVectorConverter
+  },
+  { optionalFields: ['locator', 'fragmentId'] }
+);
+
+/**
+ * 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 const embeddedFragmentConverter: Converter<IEmbeddedFragment> =
+  embeddedFragmentFieldsConverter.withConstraint((fragment: IEmbeddedFragment) =>
+    fragment.locator === undefined && fragment.fragmentId === undefined
+      ? fail('embedded fragment: at least one of `locator` or `fragmentId` is required')
+      : succeed(fragment)
+  );

package/src/packlets/vector/inMemoryFragmentCosineIndex.ts

@@ -8,16 +8,31 @@ import { IEdgeTarget, edgeTargetKey } from '../types';
 import {
   FragmentEmbedder,
   IEmbeddedFragment,
-  IFragmentLocator,
   IFragmentVectorIndex,
   IMemoryRecordSource,
   IScopedMemoryRecord,
   IVectorQueryHit
 } from './vectorIndex';
 
-/** One stored fragment: its in-record locator plus the vector for that span. */
+/**
+ * The identity fields a fragment was added with, already in query-hit shape: a field
+ * the fragment did not carry is *absent*, never present-but-`undefined`, so a hit
+ * for a fragment added without a `fragmentId` is structurally identical to one
+ * produced before `fragmentId` existed.
+ */
+type FragmentIdentity = Pick<IVectorQueryHit, 'locator' | 'fragmentId'>;
+
+/** Project an incoming fragment's identity fields, dropping the ones it did not carry. */
+function fragmentIdentity(fragment: IEmbeddedFragment): FragmentIdentity {
+  return {
+    ...(fragment.locator !== undefined ? { locator: fragment.locator } : {}),
+    ...(fragment.fragmentId !== undefined ? { fragmentId: fragment.fragmentId } : {})
+  };
+}
+
+/** One stored fragment: the identity it was added with plus its vector. */
 interface IStoredFragment {
-  readonly locator: IFragmentLocator;
+  readonly identity: FragmentIdentity;
   readonly vector: Float32Array;
 }
 
@@ -36,9 +51,11 @@ interface IScoredFragment {
 /**
  * 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
@@ -108,6 +125,16 @@ export class InMemoryFragmentCosineIndex implements IFragmentVectorIndex {
       if (fragment.vector.length === 0) {
         return Promise.resolve(fail(`fragment index: cannot add '${key}': empty fragment vector`));
       }
+      // A fragment carrying neither identity cannot be resolved back to anything by a
+      // consumer holding the hit — the same invariant `embeddedFragmentConverter`
+      // enforces at the untyped boundary, re-checked here at the index seam.
+      if (fragment.locator === undefined && fragment.fragmentId === undefined) {
+        return Promise.resolve(
+          fail(
+            `fragment index: cannot add '${key}': fragment requires at least one of 'locator' or 'fragmentId'`
+          )
+        );
+      }
       if (dimension === undefined) {
         dimension = fragment.vector.length;
       } else if (fragment.vector.length !== dimension) {
@@ -118,7 +145,7 @@ export class InMemoryFragmentCosineIndex implements IFragmentVectorIndex {
         );
       }
       // Defensive copy: the caller may reuse or mutate the buffer after `addFragments`.
-      stored.push({ locator: fragment.locator, vector: Float32Array.from(fragment.vector) });
+      stored.push({ identity: fragmentIdentity(fragment), vector: Float32Array.from(fragment.vector) });
     }
     // Whole-record replace: an empty `fragments` array drops the record entirely
     // rather than leaving an empty shell behind. Commit the (possibly newly-derived)
@@ -163,7 +190,7 @@ export class InMemoryFragmentCosineIndex implements IFragmentVectorIndex {
           hit: {
             target: record.target,
             score: InMemoryFragmentCosineIndex._cosine(vector, queryMagnitude, fragment.vector),
-            locator: fragment.locator
+            ...fragment.identity
           }
         });
       }

package/src/packlets/vector/index.ts

@@ -4,5 +4,6 @@
  */
 
 export * from './vectorIndex';
+export * from './fragmentConverters';
 export * from './inMemoryCosineIndex';
 export * from './inMemoryFragmentCosineIndex';