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

package/dist/packlets/observe/observer.js.map

@@ -1 +1 @@
-{"version":3,"file":"observer.js","sourceRoot":"","sources":["../../../src/packlets/observe/observer.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result } from '@fgv/ts-utils';\nimport { IProvenance, Kind, MemoryId, MemoryScopeKey } from '../types';\n\n/**\n * The store/retriever operation an observation record describes.\n *\n * @remarks\n * `'read'` / `'write'` / `'delete'` are fired post-op by\n * {@link FileTreeMemoryStore} (on `get` / `put` / `delete` respectively) when\n * observers are wired. `'retrieve'` is reserved for retriever-fired\n * observations; no B2 retriever fires one (a single seq authority per\n * observation store is the supported topology), so it never appears in B2 but\n * is part of the vocabulary so a future retriever-firing hook is additive.\n * @public\n */\nexport type MemoryObservationPhase = 'read' | 'write' | 'delete' | 'retrieve';\n\n/**\n * The outcome of the observed operation.\n * @public\n */\nexport type MemoryObservationOutcome = 'success' | 'failure';\n\n/**\n * A single audit record produced by an observed store (or retriever) operation.\n *\n * @remarks\n * `seq` and `timestamp` are assigned by the firing authority (the store) before\n * fan-out, so the same record carries the same `seq` across every observer it\n * lands in. `seq` is strictly increasing per authority, satisfying the\n * `RetainingRingBuffer` cursor contract that {@link MemoryObservationStore}\n * relies on.\n * @public\n */\nexport interface IMemoryObservationRecord {\n  /**\n   * Monotonic 1-based sequence number assigned by the firing authority, stable\n   * across a store's ring eviction. The ordering / paging key.\n   */\n  readonly seq: number;\n  /** Milliseconds since epoch when the firing authority produced the record. */\n  readonly timestamp: number;\n  /** Which operation this record describes. */\n  readonly phase: MemoryObservationPhase;\n  /** The scope the operation touched, when resolvable. */\n  readonly scope?: MemoryScopeKey;\n  /** The record id the operation touched, when resolvable. */\n  readonly id?: MemoryId;\n  /** The kind the operation targeted, when known. */\n  readonly kind?: Kind;\n  /** Whether the operation succeeded. */\n  readonly outcome: MemoryObservationOutcome;\n  /** Present on failure: the failure `Result`'s message. */\n  readonly error?: string;\n  /** Structured provenance of the write, when the operation carried one. */\n  readonly provenance?: IProvenance;\n  /**\n   * For `'retrieve'` observations: an opaque snapshot of the query that drove\n   * the retrieval. Carried verbatim; never interpreted by the store.\n   */\n  readonly querySnapshot?: Readonly<Record<string, unknown>>;\n}\n\n/**\n * Single-method async observer hook. The store fires `observe` once per public\n * `get` / `put` / `delete` call when observers are wired.\n *\n * @remarks\n * Observer errors never affect the store operation — the store swallows a\n * failed `Result` or a thrown / rejected `observe`, logging it to the injected\n * diagnostic logger at `warn`.\n * @public\n */\nexport interface IMemoryObserver {\n  /**\n   * When `true`, the store dispatches `observe` without awaiting it, so a slow\n   * remote observer (SIEM, network sink) does not extend the store operation's\n   * latency. Defaults to `false` (awaited), which is correct for the cheap\n   * in-memory default {@link MemoryObservationStore}. Errors are swallowed\n   * either way.\n   */\n  readonly fireAndForget?: boolean;\n  /**\n   * Receives a fully-formed observation record.\n   * @param record - The observation record.\n   * @returns A `Result` whose failure is swallowed (logged to the store's\n   * diagnostic logger). A rejected promise is likewise swallowed.\n   */\n  observe(record: IMemoryObservationRecord): Promise<Result<unknown>>;\n}\n\n/**\n * Query criteria for {@link MemoryObservationStore.query}. All supplied criteria\n * are AND-combined.\n * @public\n */\nexport interface IMemoryObservationQuery {\n  /** Only records with `seq > sinceSeq` (incremental paging cursor). */\n  readonly sinceSeq?: number;\n  /** Return at most this many records — the most-recent N, still oldest-first. */\n  readonly limit?: number;\n  /** Only records with `timestamp >= since`. */\n  readonly since?: number;\n  /** Only records with `timestamp <= until`. */\n  readonly until?: number;\n  /** Only records that touched this scope. */\n  readonly scope?: MemoryScopeKey;\n  /** Only records that targeted this kind. */\n  readonly kind?: Kind;\n  /** Only records of this phase. */\n  readonly phase?: MemoryObservationPhase;\n  /** Only records with this outcome. */\n  readonly outcome?: MemoryObservationOutcome;\n}\n"]}
+{"version":3,"file":"observer.js","sourceRoot":"","sources":["../../../src/packlets/observe/observer.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result } from '@fgv/ts-utils';\nimport { IProvenance, Kind, MemoryId, MemoryScopeKey } from '../types';\n\n/**\n * The store/retriever operation an observation record describes.\n *\n * @remarks\n * `'read'` / `'write'` / `'delete'` are fired post-op by\n * {@link FileTreeMemoryStore} (on `get` / `put` / `delete` respectively) when\n * observers are wired. `'retrieve'` is reserved for retriever-fired\n * observations; no B2 retriever fires one (a single seq authority per\n * observation store is the supported topology), so it never appears in B2 but\n * is part of the vocabulary so a future retriever-firing hook is additive.\n * @public\n */\nexport type MemoryObservationPhase = 'read' | 'write' | 'delete' | 'retrieve';\n\n/**\n * The outcome of the observed operation.\n * @public\n */\nexport type MemoryObservationOutcome = 'success' | 'failure';\n\n/**\n * What the record-granular vector index did about a written record.\n *\n * @remarks\n * This exists because **`embeddingRef` absence is three-ways ambiguous**: a\n * record with no reference may have been declined, excluded, or genuinely\n * failed to embed, and the `put`'s own `outcome` cannot tell you which — it is\n * `'success'` in all three, because embed-on-write is best-effort by design and\n * never fails a durable write. Deriving index coverage from the absent field\n * alone therefore cannot distinguish a policy decision from an outage.\n *\n * - `'embedded'` — embedded and added; the record carries an `embeddingRef`.\n * - `'declined'` — the {@link MemoryEmbedder} resolved `undefined`: deliberately\n *   not embedded. Not a fault.\n * - `'excluded'` — the record's kind is outside the store's `embedKinds`\n *   declaration, so the embedder was never called. Also not a fault, and the\n *   cheaper of the two.\n * - `'failed'` — the embedder returned a `Failure` (or threw), **or** the index\n *   `add` did. Both are faults, and what they leave behind depends on whether\n *   the record had been embedded before: a **first** write ends up with no\n *   `embeddingRef` and nothing in the index, while an **update** keeps the\n *   reference and vector it already had — so the index goes on answering on the\n *   record's **previous** content until a `rebuild` reconciles it. Stale, not\n *   absent. The store's diagnostic logger names which fault it was, because the\n *   remediation differs (an embedder outage versus an index outage) while the\n *   coverage answer — \"this record needs a re-embed\" — does not.\n *\n * Absent on a write observation means **no outcome is being reported**, which\n * covers three cases:\n *\n * 1. no vector index / embedder is wired, so there is no index for the record to\n *    be absent from;\n * 2. the `put` was a dedup no-op, which attempted nothing;\n * 3. the `put` **failed** (`outcome: 'failure'`). An embed step may well have run\n *    before the failure — a record can even have been added to the index and then\n *    lost its durable write, leaving an orphan vector that a later `rebuild`\n *    reconciles. That is deliberately not reported here: the field answers\n *    \"is this *stored* record in the index?\", and on a failed write there is no\n *    stored record for it to be a statement about.\n *\n * So `embed` is a property of successful writes. Never present on `'read'` /\n * `'delete'` / `'retrieve'`.\n *\n * Record-granular only. The fragment path is independent and reports nothing\n * here — a record may be fragment-embedded while its record-level outcome is\n * `'excluded'`.\n * @public\n */\nexport type MemoryEmbedOutcome = 'embedded' | 'declined' | 'excluded' | 'failed';\n\n/**\n * A single audit record produced by an observed store (or retriever) operation.\n *\n * @remarks\n * `seq` and `timestamp` are assigned by the firing authority (the store) before\n * fan-out, so the same record carries the same `seq` across every observer it\n * lands in. `seq` is strictly increasing per authority, satisfying the\n * `RetainingRingBuffer` cursor contract that {@link MemoryObservationStore}\n * relies on.\n * @public\n */\nexport interface IMemoryObservationRecord {\n  /**\n   * Monotonic 1-based sequence number assigned by the firing authority, stable\n   * across a store's ring eviction. The ordering / paging key.\n   */\n  readonly seq: number;\n  /** Milliseconds since epoch when the firing authority produced the record. */\n  readonly timestamp: number;\n  /** Which operation this record describes. */\n  readonly phase: MemoryObservationPhase;\n  /** The scope the operation touched, when resolvable. */\n  readonly scope?: MemoryScopeKey;\n  /** The record id the operation touched, when resolvable. */\n  readonly id?: MemoryId;\n  /** The kind the operation targeted, when known. */\n  readonly kind?: Kind;\n  /** Whether the operation succeeded. */\n  readonly outcome: MemoryObservationOutcome;\n  /** Present on failure: the failure `Result`'s message. */\n  readonly error?: string;\n  /** Structured provenance of the write, when the operation carried one. */\n  readonly provenance?: IProvenance;\n  /**\n   * For `'write'` observations: what the record-granular vector index did about\n   * this record. Absent when the question does not apply — see\n   * {@link MemoryEmbedOutcome}.\n   */\n  readonly embed?: MemoryEmbedOutcome;\n  /**\n   * For `'retrieve'` observations: an opaque snapshot of the query that drove\n   * the retrieval. Carried verbatim; never interpreted by the store.\n   */\n  readonly querySnapshot?: Readonly<Record<string, unknown>>;\n}\n\n/**\n * Single-method async observer hook. The store fires `observe` once per public\n * `get` / `put` / `delete` call when observers are wired.\n *\n * @remarks\n * Observer errors never affect the store operation — the store swallows a\n * failed `Result` or a thrown / rejected `observe`, logging it to the injected\n * diagnostic logger at `warn`.\n * @public\n */\nexport interface IMemoryObserver {\n  /**\n   * When `true`, the store dispatches `observe` without awaiting it, so a slow\n   * remote observer (SIEM, network sink) does not extend the store operation's\n   * latency. Defaults to `false` (awaited), which is correct for the cheap\n   * in-memory default {@link MemoryObservationStore}. Errors are swallowed\n   * either way.\n   */\n  readonly fireAndForget?: boolean;\n  /**\n   * Receives a fully-formed observation record.\n   * @param record - The observation record.\n   * @returns A `Result` whose failure is swallowed (logged to the store's\n   * diagnostic logger). A rejected promise is likewise swallowed.\n   */\n  observe(record: IMemoryObservationRecord): Promise<Result<unknown>>;\n}\n\n/**\n * Query criteria for {@link MemoryObservationStore.query}. All supplied criteria\n * are AND-combined.\n * @public\n */\nexport interface IMemoryObservationQuery {\n  /** Only records with `seq > sinceSeq` (incremental paging cursor). */\n  readonly sinceSeq?: number;\n  /** Return at most this many records — the most-recent N, still oldest-first. */\n  readonly limit?: number;\n  /** Only records with `timestamp >= since`. */\n  readonly since?: number;\n  /** Only records with `timestamp <= until`. */\n  readonly until?: number;\n  /** Only records that touched this scope. */\n  readonly scope?: MemoryScopeKey;\n  /** Only records that targeted this kind. */\n  readonly kind?: Kind;\n  /** Only records of this phase. */\n  readonly phase?: MemoryObservationPhase;\n  /** Only records with this outcome. */\n  readonly outcome?: MemoryObservationOutcome;\n  /**\n   * Only `'write'` records with this embed outcome. Records carrying no embed\n   * outcome never match, so `embed: 'failed'` answers \"which writes left the\n   * index short?\" without a full scan of every record's `embeddingRef`.\n   */\n  readonly embed?: MemoryEmbedOutcome;\n}\n"]}

package/dist/packlets/store/fileTreeMemoryStore.js

@@ -6,6 +6,7 @@ import { Hash, Logging, fail, mapResults, mapSuccess, succeed } from '@fgv/ts-ut
 import { FileTree } from '@fgv/ts-json-base';
 import { DEFAULT_DEDUP_SCOPE, KnowledgeLwwPolicy, isTemporalIdentityCodec, isTemporalRecord, isVersionCurrent, selectCurrentVersion, selectVersionAsOf } from '../types';
 import { parseMemoryFile, serializeMemoryFile } from '../converters';
+import { VectorMaintenance } from './vectorMaintenance';
 import { MemoryIndex } from '../index';
 import { defaultMemoryScopeEncoding } from './scopeEncoding';
 /** The on-disk extension for a memory record file. */
@@ -26,11 +27,13 @@ const MEMORY_FILE_EXTENSION = '.md';
  */
 export class FileTreeMemoryStore {
     constructor(params) {
+        var _a;
         this._root = params.root;
         this._registry = params.registry;
         this._writePolicies = params.writePolicies;
         this._codecs = params.codecs;
         this._rankProjectors = params.rankProjectors;
+        this._embedKinds = (_a = params.embedKinds) !== null && _a !== void 0 ? _a : undefined;
         this._defaultCodec = params.defaultCodec;
         this._defaultPolicy = params.defaultPolicy;
         this._scopeEncoding = params.scopeEncoding;
@@ -39,10 +42,14 @@ export class FileTreeMemoryStore {
         this._hasher = new Hash.Crc32Normalizer();
         this._observers = params.observers;
         this._logger = params.logger;
-        this._vectorIndex = params.vectorIndex;
-        this._embed = params.embed;
-        this._fragmentIndex = params.fragmentIndex;
-        this._fragmentEmbedder = params.fragmentEmbedder;
+        this._vectors = new VectorMaintenance({
+            vectorIndex: params.vectorIndex,
+            embed: params.embed,
+            fragmentIndex: params.fragmentIndex,
+            fragmentEmbedder: params.fragmentEmbedder,
+            warn: (message) => this._warnSwallowed(message),
+            embedsKind: (kind) => this.embedsKind(kind)
+        });
         this._skippedRecords = [];
         this._seq = 0;
         this._observationSeq = 0;
@@ -75,6 +82,7 @@ export class FileTreeMemoryStore {
                 writePolicies: (_a = params.writePolicies) !== null && _a !== void 0 ? _a : new Map(),
                 codecs: (_b = params.codecs) !== null && _b !== void 0 ? _b : new Map(),
                 rankProjectors: (_c = params.rankProjectors) !== null && _c !== void 0 ? _c : new Map(),
+                embedKinds: params.embedKinds,
                 defaultCodec: params.defaultCodec,
                 defaultPolicy,
                 scopeEncoding: (_d = params.scopeEncoding) !== null && _d !== void 0 ? _d : defaultMemoryScopeEncoding,
@@ -168,7 +176,14 @@ export class FileTreeMemoryStore {
     }
     /** {@inheritDoc IMemoryStore.asRecordSource} */
     asRecordSource() {
-        return { list: () => this.listScoped() };
+        return {
+            // Filtered to the kinds that participate in the record vector index. This
+            // source exists to drive `IVectorIndex` rebuilds, so a kind excluded from the
+            // index has no business being re-embedded on open — which is where the cost
+            // is worst, since a rebuild embeds the whole vault serially. With no
+            // `embedKinds` declaration every kind passes and this is the identity filter.
+            list: async () => (await this.listScoped()).onSuccess((scoped) => succeed(scoped.filter((s) => this.embedsKind(s.record.envelope.kind))))
+        };
     }
     /**
      * Collapse temporal records to the single version valid at `asOf` per entity;
@@ -210,7 +225,8 @@ export class FileTreeMemoryStore {
             outcome: result.isSuccess() ? 'success' : 'failure',
             id: result.isSuccess() ? result.value.record.envelope.id : record.envelope.id,
             provenance: record.envelope.provenance,
-            error: result.isFailure() ? result.message : undefined
+            error: result.isFailure() ? result.message : undefined,
+            embed: result.isSuccess() ? result.value.embed : undefined
         });
         // Fire one `'delete'` observation per record evicted by cap-cull. The
         // evicted records are always in the same `(scope, kind)` cohort as the
@@ -266,7 +282,8 @@ export class FileTreeMemoryStore {
             kind,
             outcome: details.outcome,
             error: details.error,
-            provenance: details.provenance
+            provenance: details.provenance,
+            embed: details.embed
         };
         const awaited = [];
         for (const observer of this._observers) {
@@ -348,9 +365,11 @@ export class FileTreeMemoryStore {
      * vector index, the on-disk file, and the derived index never interleave.
      */
     async _writeResolved(record, body, scope, idStem, hash) {
-        var _a;
         const policy = this._policyFor(record.envelope.kind);
-        const dedupScope = (_a = policy.dedupScope) !== null && _a !== void 0 ? _a : 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 = 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
@@ -417,89 +436,27 @@ export class FileTreeMemoryStore {
         }
         return this._buildRecord(record, body, existing, policy, hash)
             .onSuccess((built) => succeed(this._stampRank(built)))
-            .thenOnSuccess((built) => this._embedOnWrite(built, scope))
-            .thenOnSuccess((built) => this._embedFragmentsOnWrite(built, scope))
-            .onSuccess((embeddedBuilt) => this._persist(embeddedBuilt, scope, idStem))
-            .thenOnSuccess(async (persisted) => {
+            .thenOnSuccess((built) => this._vectors.embedOnWrite(built, scope))
+            .thenOnSuccess(async (embedded) => (await this._vectors.embedFragmentsOnWrite(embedded.record, scope)).onSuccess((withFragments) => succeed(Object.assign(Object.assign({}, embedded), { record: withFragments }))))
+            .onSuccess((embedded) => this._persist(embedded.record, scope, idStem).onSuccess((persisted) => succeed({ persisted, stale: embedded.stale, embed: embedded.embed })))
+            .thenOnSuccess(async ({ persisted, stale, embed }) => {
             // Everything after the authoritative `_persist` commit is best-effort and
             // never turns a committed write into a `Failure`:
+            //   - a stale vector superseded by a decline is pruned here rather than at
+            //     the point of the decline, because a `_persist` that fails leaves the
+            //     PREVIOUS content on disk — content that vector is still an accurate
+            //     embedding of. Pruning early would delete a correct vector on behalf
+            //     of a write that never landed;
             //   - a cull-oldest eviction that fails is logged (the per-(scope,kind)
             //     cap may be transiently exceeded; the next write's admission restores
             //     it), and only the successfully-evicted ids flow onward;
             //   - vector pruning of the evicted cohort is likewise best-effort.
+            await this._vectors.pruneStaleVector(stale);
             const evicted = this._applyEvictions(decision, scope);
-            await this._removeEvictedVectors(evicted, scope);
-            return succeed({ record: persisted, evicted });
+            await this._vectors.removeEvictedVectors(evicted, scope);
+            return succeed({ record: persisted, evicted, embed });
         });
     }
-    /**
-     * Best-effort embed-on-write. When a vector index AND an embedder are wired,
-     * embeds the built record, `add`s the vector (replace semantics handle a same-id
-     * re-embed — no explicit remove), and stamps the returned `embeddingRef`. A
-     * failure (returned `fail` OR a thrown/rejected hook) is logged and the
-     * unembedded record is returned unchanged — the put still persists, and the
-     * derived index is reconciled by a later `rebuild`. A pass-through no-op when
-     * unwired (byte-identical record).
-     *
-     * Always succeeds (`Result` is the chain's shape, never a vector-induced
-     * failure).
-     */
-    async _embedOnWrite(built, scope) {
-        if (this._vectorIndex === undefined || this._embed === undefined) {
-            return succeed(built);
-        }
-        const vectorIndex = this._vectorIndex;
-        const embed = this._embed;
-        const target = { scope, id: built.envelope.id };
-        const embedded = await this._tryVectorOp(() => embed(built), `embedding '${built.envelope.id}'`);
-        if (embedded.isFailure()) {
-            return succeed(built);
-        }
-        const added = await this._tryVectorOp(() => vectorIndex.add(target, embedded.value), `vector add for '${built.envelope.id}'`);
-        if (added.isFailure()) {
-            return succeed(built);
-        }
-        return succeed({ envelope: Object.assign(Object.assign({}, built.envelope), { embeddingRef: added.value }), body: built.body });
-    }
-    /**
-     * Best-effort fragment-embed-on-write. When a fragment index AND a fragment
-     * embedder are wired, chunks + embeds the built record and replaces its
-     * fragments in the index (`addFragments` is whole-record-replace, so a re-authored
-     * document never leaves stale fragments behind — no explicit remove needed). A
-     * failure (returned `fail` OR a thrown/rejected hook) is logged and the record is
-     * returned unchanged — the put still persists, and the fragment index is a derived
-     * view a later `rebuild` reconciles. Unlike {@link FileTreeMemoryStore._embedOnWrite}
-     * it stamps nothing on the record (fragments have no per-record `embeddingRef`
-     * analog). A pass-through no-op when unwired (byte-identical record).
-     */
-    async _embedFragmentsOnWrite(built, scope) {
-        if (this._fragmentIndex === undefined || this._fragmentEmbedder === undefined) {
-            return succeed(built);
-        }
-        const fragmentIndex = this._fragmentIndex;
-        const fragmentEmbedder = this._fragmentEmbedder;
-        const target = { scope, id: built.envelope.id };
-        const embedded = await this._tryVectorOp(() => fragmentEmbedder(built), `fragment embedding '${built.envelope.id}'`);
-        if (embedded.isFailure()) {
-            return succeed(built);
-        }
-        await this._tryVectorOp(() => fragmentIndex.addFragments(target, embedded.value), `fragment add for '${built.envelope.id}'`);
-        return succeed(built);
-    }
-    /**
-     * Best-effort fragment removal. A no-op unless the full fragment lifecycle is
-     * wired (both an index AND an embedder), so an unwired store does no fragment
-     * work and behaves byte-identically. Failures are logged, never surfaced — a
-     * committed delete/eviction must not fail because a derived fragment index could
-     * not be pruned.
-     */
-    async _removeFragmentsBestEffort(target) {
-        if (this._fragmentIndex === undefined || this._fragmentEmbedder === undefined) {
-            return;
-        }
-        const fragmentIndex = this._fragmentIndex;
-        await this._tryVectorOp(() => fragmentIndex.remove(target), `fragment removal for '${target.id}'`);
-    }
     /**
      * Evict the records named by a `cull-oldest` decision, best-effort. Runs only
      * after the authoritative `_persist`, so a failed eviction is logged (never
@@ -523,49 +480,6 @@ export class FileTreeMemoryStore {
         }
         return evicted;
     }
-    /**
-     * Best-effort vector removal for each evicted record (never fails the put).
-     * Every evicted record is in the same `scope` as the incoming write (the
-     * cull-oldest cohort is the incoming record's `(scope, kind)` cohort), so that
-     * scope qualifies each removal target.
-     */
-    async _removeEvictedVectors(evicted, scope) {
-        for (const id of evicted) {
-            await this._removeVectorBestEffort({ scope, id });
-            await this._removeFragmentsBestEffort({ scope, id });
-        }
-    }
-    /**
-     * Run a consumer-supplied vector hook, normalizing a thrown/rejected hook into a
-     * `Failure` and logging any failure at `warn`. Best-effort: the caller proceeds
-     * regardless, since the index is rebuildable.
-     */
-    async _tryVectorOp(op, label) {
-        let result;
-        try {
-            result = await op();
-        }
-        catch (err) {
-            result = fail(`${label} threw: ${String(err)}`);
-        }
-        if (result.isFailure()) {
-            this._warnSwallowed(`memory: ${label} failed (best-effort; derived index left for rebuild): ${result.message}`);
-        }
-        return result;
-    }
-    /**
-     * Best-effort vector removal. A no-op unless the full vector lifecycle is wired
-     * (both an index AND an embedder), so an unwired store does no vector work and
-     * behaves byte-identically. Failures are logged, never surfaced — a committed
-     * delete/eviction must not fail because a derived index could not be pruned.
-     */
-    async _removeVectorBestEffort(target) {
-        if (this._vectorIndex === undefined || this._embed === undefined) {
-            return;
-        }
-        const vectorIndex = this._vectorIndex;
-        await this._tryVectorOp(() => vectorIndex.remove(target), `vector removal for '${target.id}'`);
-    }
     /**
      * Build the record to persist. On a first write the incoming envelope is the
      * base (final content equals the incoming content, so the dedup `hash` is
@@ -635,8 +549,7 @@ export class FileTreeMemoryStore {
             return this._deleteFile(scope, idStem)
                 .onSuccess(() => this._index.patch('delete', { scope, record: existing }))
                 .thenOnSuccess(async () => {
-                await this._removeVectorBestEffort({ scope, id: existing.envelope.id });
-                await this._removeFragmentsBestEffort({ scope, id: existing.envelope.id });
+                await this._vectors.removeAll({ scope, id: existing.envelope.id });
                 return succeed(existing.envelope.id);
             });
         });
@@ -674,7 +587,6 @@ export class FileTreeMemoryStore {
      * version's `valid_at` lower-bounds its interval.
      */
     async _putVersioned(record, body, codec, scope) {
-        var _a;
         const envelope = record.envelope;
         const entityId = envelope.entityId;
         const kind = envelope.kind;
@@ -686,7 +598,8 @@ export class FileTreeMemoryStore {
         const priorCurrents = versions.filter(isVersionCurrent);
         const current = selectCurrentVersion(versions);
         const policy = this._policyFor(kind);
-        const dedupScope = (_a = policy.dedupScope) !== null && _a !== void 0 ? _a : DEFAULT_DEDUP_SCOPE;
+        // Same single-owner read as the flat path (see `_writeResolved`).
+        const 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).
@@ -722,11 +635,15 @@ export class FileTreeMemoryStore {
                     .withErrorFormat((msg) => `memory put '${entityId}': ${msg}`)
                     .thenOnSuccess((versionStem) => this._buildVersionedRecord(record, body, current, policy, hash, versionStem, validAt, now, seq)
                     .onSuccess((built) => succeed(this._stampRank(built)))
-                    .thenOnSuccess((built) => this._embedOnWrite(built, scope))
-                    .thenOnSuccess((built) => this._embedFragmentsOnWrite(built, scope))
-                    .onSuccess((embeddedBuilt) => this._persist(embeddedBuilt, scope, versionStem))
-                    .onSuccess((persisted) => this._invalidateCurrents(scope, priorCurrents, validAt, now).onSuccess(() => succeed(persisted)))
-                    .onSuccess((persisted) => succeed({ record: persisted, evicted: [] })));
+                    .thenOnSuccess((built) => this._vectors.embedOnWrite(built, scope))
+                    .thenOnSuccess(async (embedded) => (await this._vectors.embedFragmentsOnWrite(embedded.record, scope)).onSuccess((withFragments) => succeed(Object.assign(Object.assign({}, embedded), { record: withFragments }))))
+                    .onSuccess((embedded) => this._persist(embedded.record, scope, versionStem).onSuccess((persisted) => succeed({ persisted, stale: embedded.stale, embed: embedded.embed })))
+                    .onSuccess(({ persisted, stale, embed }) => this._invalidateCurrents(scope, priorCurrents, validAt, now).onSuccess(() => succeed({ persisted, stale, embed })))
+                    // Post-commit and best-effort, exactly as on the flat path.
+                    .thenOnSuccess(async ({ persisted, stale, embed }) => {
+                    await this._vectors.pruneStaleVector(stale);
+                    return succeed({ record: persisted, evicted: [], embed });
+                }));
             });
         });
     }
@@ -934,6 +851,17 @@ export class FileTreeMemoryStore {
         var _a;
         return (_a = this._writePolicies.get(kind)) !== null && _a !== void 0 ? _a : this._defaultPolicy;
     }
+    /** {@inheritDoc IMemoryStore.dedupScopeFor} */
+    dedupScopeFor(kind) {
+        var _a;
+        return (_a = this._policyFor(kind).dedupScope) !== null && _a !== void 0 ? _a : DEFAULT_DEDUP_SCOPE;
+    }
+    /** {@inheritDoc IMemoryStore.embedsKind} */
+    embedsKind(kind) {
+        // No declaration means every kind participates — the behavior that predates
+        // this param, so an existing consumer is unaffected.
+        return this._embedKinds === undefined || this._embedKinds.has(kind);
+    }
     /**
      * Read and validate the record at `<scope>/<idStem>.md`, returning `undefined`
      * when the scope directory or file is absent. Verifies the on-disk id ↔