@fgv/ts-agent-memory 5.1.0-49 → 5.1.0-50

package/lib/packlets/store/storeCoverage.js

@@ -0,0 +1,105 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeCoverage = computeCoverage;
+const ts_utils_1 = require("@fgv/ts-utils");
+const types_1 = require("../types");
+/** Get or create `kind`'s bucket. */
+function bucketFor(buckets, kind) {
+    let bucket = buckets.get(kind);
+    if (bucket === undefined) {
+        bucket = { expected: 0, covered: 0 };
+        buckets.set(kind, bucket);
+    }
+    return bucket;
+}
+/**
+ * One walk over the projected entries, producing every derived-state count.
+ *
+ * @remarks
+ * **Reads no record bodies and calls no embedder**, and the walk itself touches
+ * no filesystem. That is the contract `IMemoryStore.coverage` makes, and this
+ * function is where it is kept: every number below comes from an envelope field
+ * or an index-side count. The index-side counts are the one place that leaves
+ * envelope territory — on a durable backend they run a query, which is why they
+ * are captured (see the comment at the `captureResult` below) and why the walk's
+ * "no filesystem" claim is scoped to the walk rather than the whole call. A
+ * future addition that needs a body does not belong here.
+ *
+ * Extracted from `fileTreeMemoryStore.ts` because inlining it took that file past
+ * the 2000-line `max-lines` cap — the same reason `vectorRecordSource.ts` exists.
+ */
+function computeCoverage(params) {
+    var _a;
+    const records = new Map();
+    const rank = new Map();
+    const vectors = new Map();
+    for (const entry of params.entries) {
+        const kind = entry.envelope.kind;
+        records.set(kind, ((_a = records.get(kind)) !== null && _a !== void 0 ? _a : 0) + 1);
+        // `rank` is expected only where a projector is registered. A kind with no
+        // projector stays absent from the map rather than appearing at 0% — the store
+        // is not failing to rank it, it was never asked to.
+        if (params.hasRankProjector(kind)) {
+            const bucket = bucketFor(rank, kind);
+            bucket.expected += 1;
+            if (entry.envelope.rank !== undefined) {
+                bucket.covered += 1;
+            }
+        }
+        // Every kind appears here, INCLUDING excluded ones: `records: 40, expected: 0`
+        // is the exclusion story stated rather than inferred, and is strictly more
+        // useful than omitting the kind entirely.
+        const bucket = bucketFor(vectors, kind);
+        if (params.embedsKind(kind)) {
+            bucket.expected += 1;
+            // Counted INSIDE the exclusion branch so `covered <= expected` holds, which
+            // is what `IArtifactCoverage.covered` promises when it says "of those". An
+            // excluded kind carrying a residual `embeddingRef` (written before
+            // `embedKinds` narrowed and never re-put) would otherwise report
+            // `expected: 0, covered: 3` and make `expected - covered` negative for a
+            // caller sizing the gap. That residue is not lost: its vector still counts
+            // toward `indexSize`, which is exactly the belief-vs-fact disagreement that
+            // field exists to surface.
+            if ((0, types_1.embeddingRefOf)(entry.envelope) !== undefined) {
+                bucket.covered += 1;
+            }
+        }
+    }
+    // The index-side counts are the ONE place this walk leaves envelope territory,
+    // and on a durable backend they run SQL: `SqliteVecVectorIndex.size` executes a
+    // prepared COUNT and throws on a closed connection. Capturing them keeps the
+    // `Result` contract honest — coverage FAILS rather than rejecting — and is why
+    // the "touches no filesystem" claim is scoped to the walk rather than the whole
+    // call: reading a persistent index's count is I/O, and it is the caller's own
+    // index doing it.
+    return (0, ts_utils_1.captureResult)(() => ({
+        recordVectors: params.vectorIndex === undefined ? undefined : { size: params.vectorIndex.size },
+        fragmentVectors: params.fragmentIndex === undefined
+            ? undefined
+            : {
+                recordCount: params.fragmentIndex.recordCount,
+                fragmentCount: params.fragmentIndex.fragmentCount
+            }
+    }))
+        .withErrorFormat((e) => `memory coverage: reading an index count failed: ${e}`)
+        .onSuccess((counts) => (0, ts_utils_1.succeed)(Object.assign(Object.assign(Object.assign({ records }, (params.anyRankProjector ? { rank: rank } : {})), (counts.recordVectors !== undefined
+        ? {
+            recordVectors: {
+                perKind: vectors,
+                indexSize: counts.recordVectors.size
+            }
+        }
+        : {})), (counts.fragmentVectors !== undefined
+        ? {
+            fragmentVectors: {
+                indexRecordCount: counts.fragmentVectors.recordCount,
+                indexFragmentCount: counts.fragmentVectors.fragmentCount
+            }
+        }
+        : {}))));
+}
+//# sourceMappingURL=storeCoverage.js.map

package/lib/packlets/store/storeCoverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storeCoverage.js","sourceRoot":"","sources":["../../../src/packlets/store/storeCoverage.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, captureResult, succeed } from '@fgv/ts-utils';\nimport { Kind, embeddingRefOf } from '../types';\nimport { IIndexedMemoryEntry } from '../index';\nimport { IFragmentVectorIndex, IVectorIndex } from '../vector';\nimport { IArtifactCoverage, IDerivedStateCoverage } from './coverage';\n\n/**\n * Everything {@link computeCoverage} needs, supplied by the store.\n *\n * @remarks\n * Taken as inputs rather than reading a store, so this module has no dependency\n * on `FileTreeMemoryStore` and the walk is testable on its own. Package-internal:\n * `IMemoryStore.coverage` is the published surface.\n */\nexport interface IComputeCoverageParams {\n  /** The projected index entries — envelopes only, already free of file reads. */\n  readonly entries: ReadonlyArray<IIndexedMemoryEntry>;\n  /** Whether `kind` has a registered rank projector. */\n  readonly hasRankProjector: (kind: Kind) => boolean;\n  /** Whether ANY kind has one — distinguishes an unwired lane from an empty one. */\n  readonly anyRankProjector: boolean;\n  /** Whether `kind` participates in the record-granular vector index. */\n  readonly embedsKind: (kind: Kind) => boolean;\n  /** The wired record-vector index, or `undefined` when the lane is unwired. */\n  readonly vectorIndex: IVectorIndex | undefined;\n  /** The wired fragment index, or `undefined` when the lane is unwired. */\n  readonly fragmentIndex: IFragmentVectorIndex | undefined;\n}\n\n/** A coverage bucket under construction; the published shape is readonly. */\ninterface IMutableArtifactCoverage {\n  expected: number;\n  covered: number;\n}\n\n/** Get or create `kind`'s bucket. */\nfunction bucketFor(buckets: Map<Kind, IMutableArtifactCoverage>, kind: Kind): IMutableArtifactCoverage {\n  let bucket: IMutableArtifactCoverage | undefined = buckets.get(kind);\n  if (bucket === undefined) {\n    bucket = { expected: 0, covered: 0 };\n    buckets.set(kind, bucket);\n  }\n  return bucket;\n}\n\n/**\n * One walk over the projected entries, producing every derived-state count.\n *\n * @remarks\n * **Reads no record bodies and calls no embedder**, and the walk itself touches\n * no filesystem. That is the contract `IMemoryStore.coverage` makes, and this\n * function is where it is kept: every number below comes from an envelope field\n * or an index-side count. The index-side counts are the one place that leaves\n * envelope territory — on a durable backend they run a query, which is why they\n * are captured (see the comment at the `captureResult` below) and why the walk's\n * \"no filesystem\" claim is scoped to the walk rather than the whole call. A\n * future addition that needs a body does not belong here.\n *\n * Extracted from `fileTreeMemoryStore.ts` because inlining it took that file past\n * the 2000-line `max-lines` cap — the same reason `vectorRecordSource.ts` exists.\n */\nexport function computeCoverage(params: IComputeCoverageParams): Result<IDerivedStateCoverage> {\n  const records: Map<Kind, number> = new Map<Kind, number>();\n  const rank: Map<Kind, IMutableArtifactCoverage> = new Map<Kind, IMutableArtifactCoverage>();\n  const vectors: Map<Kind, IMutableArtifactCoverage> = new Map<Kind, IMutableArtifactCoverage>();\n\n  for (const entry of params.entries) {\n    const kind: Kind = entry.envelope.kind;\n    records.set(kind, (records.get(kind) ?? 0) + 1);\n\n    // `rank` is expected only where a projector is registered. A kind with no\n    // projector stays absent from the map rather than appearing at 0% — the store\n    // is not failing to rank it, it was never asked to.\n    if (params.hasRankProjector(kind)) {\n      const bucket: IMutableArtifactCoverage = bucketFor(rank, kind);\n      bucket.expected += 1;\n      if (entry.envelope.rank !== undefined) {\n        bucket.covered += 1;\n      }\n    }\n\n    // Every kind appears here, INCLUDING excluded ones: `records: 40, expected: 0`\n    // is the exclusion story stated rather than inferred, and is strictly more\n    // useful than omitting the kind entirely.\n    const bucket: IMutableArtifactCoverage = bucketFor(vectors, kind);\n    if (params.embedsKind(kind)) {\n      bucket.expected += 1;\n      // Counted INSIDE the exclusion branch so `covered <= expected` holds, which\n      // is what `IArtifactCoverage.covered` promises when it says \"of those\". An\n      // excluded kind carrying a residual `embeddingRef` (written before\n      // `embedKinds` narrowed and never re-put) would otherwise report\n      // `expected: 0, covered: 3` and make `expected - covered` negative for a\n      // caller sizing the gap. That residue is not lost: its vector still counts\n      // toward `indexSize`, which is exactly the belief-vs-fact disagreement that\n      // field exists to surface.\n      if (embeddingRefOf(entry.envelope) !== undefined) {\n        bucket.covered += 1;\n      }\n    }\n  }\n\n  // The index-side counts are the ONE place this walk leaves envelope territory,\n  // and on a durable backend they run SQL: `SqliteVecVectorIndex.size` executes a\n  // prepared COUNT and throws on a closed connection. Capturing them keeps the\n  // `Result` contract honest — coverage FAILS rather than rejecting — and is why\n  // the \"touches no filesystem\" claim is scoped to the walk rather than the whole\n  // call: reading a persistent index's count is I/O, and it is the caller's own\n  // index doing it.\n  return captureResult(() => ({\n    recordVectors: params.vectorIndex === undefined ? undefined : { size: params.vectorIndex.size },\n    fragmentVectors:\n      params.fragmentIndex === undefined\n        ? undefined\n        : {\n            recordCount: params.fragmentIndex.recordCount,\n            fragmentCount: params.fragmentIndex.fragmentCount\n          }\n  }))\n    .withErrorFormat((e) => `memory coverage: reading an index count failed: ${e}`)\n    .onSuccess((counts) =>\n      succeed({\n        records,\n        // Absent, never zero: an unwired lane and an empty one are different facts,\n        // and folding them makes a health surface alarm on a feature nobody enabled.\n        ...(params.anyRankProjector ? { rank: rank as ReadonlyMap<Kind, IArtifactCoverage> } : {}),\n        ...(counts.recordVectors !== undefined\n          ? {\n              recordVectors: {\n                perKind: vectors as ReadonlyMap<Kind, IArtifactCoverage>,\n                indexSize: counts.recordVectors.size\n              }\n            }\n          : {}),\n        ...(counts.fragmentVectors !== undefined\n          ? {\n              fragmentVectors: {\n                indexRecordCount: counts.fragmentVectors.recordCount,\n                indexFragmentCount: counts.fragmentVectors.fragmentCount\n              }\n            }\n          : {})\n      })\n    );\n}\n"]}

package/lib/packlets/store/storeReconcile.d.ts

@@ -0,0 +1,41 @@
+import { Result } from '@fgv/ts-utils';
+import { IMemoryRecord, Kind, MemoryId, MemoryScopeKey } from '../types';
+import { IIndexedMemoryEntry } from '../index';
+import { DerivedArtifact, ReconcileReport } from './reconcile';
+import { VectorMaintenance } from './vectorMaintenance';
+/**
+ * Everything the vector reconcile branches need, supplied by the store.
+ * Package-internal; `IMemoryStore.reconcile` is the published surface.
+ */
+export interface IReconcileVectorsParams {
+    readonly kind: Kind;
+    readonly artifact: Exclude<DerivedArtifact, 'rank'>;
+    /** The kind's index entries — envelopes only, no bodies read yet. */
+    readonly targets: ReadonlyArray<IIndexedMemoryEntry>;
+    readonly maintenance: VectorMaintenance;
+    readonly embedsKind: (kind: Kind) => boolean;
+    /** Materialize one record; `undefined` when it has vanished. */
+    readonly resolve: (scope: MemoryScopeKey, id: MemoryId) => Result<IMemoryRecord<unknown> | undefined>;
+    /** Write an `embeddingRef` onto a record's envelope; `true` when it changed. */
+    readonly stampRef: (scope: MemoryScopeKey, id: MemoryId, ref: string) => Result<boolean>;
+}
+/**
+ * Repair one vector lane for one kind, touching only what is missing.
+ *
+ * @remarks
+ * **The `has` check is what makes this targeted rather than a rebuild.** A record
+ * the index already holds costs one membership query and no embedder call, which
+ * is the entire difference between repairing a brief outage and re-embedding a
+ * vault. It is also the only way to see the record-lane case where the index
+ * holds a vector but the envelope lost its `embeddingRef` — that record needs a
+ * restamp and no embedder call, and is indistinguishable from a never-embedded
+ * one if you only look at the envelope.
+ *
+ * Per-record failures are collected rather than fatal: a repair that stops at the
+ * first bad record leaves the rest of the gap open, which is the opposite of what
+ * a caller asked for. A failure to *materialize* is likewise collected — a record
+ * that vanished between the walk and the read is a casualty of this call, not a
+ * reason to abandon the others.
+ */
+export declare function reconcileVectors(params: IReconcileVectorsParams): Promise<Result<ReconcileReport>>;
+//# sourceMappingURL=storeReconcile.d.ts.map

package/lib/packlets/store/storeReconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storeReconcile.d.ts","sourceRoot":"","sources":["../../../src/packlets/store/storeReconcile.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAiB,MAAM,eAAe,CAAC;AACtD,OAAO,EAEL,aAAa,EACb,IAAI,EACJ,QAAQ,EACR,cAAc,EAGf,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAmB,iBAAiB,EAAqB,MAAM,qBAAqB,CAAC;AAE5F;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IACpD,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IACrD,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;IAC7C,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,QAAQ,KAAK,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;IACtG,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,OAAO,CAAC,CAAC;CAC1F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAwHxG"}

package/lib/packlets/store/storeReconcile.js

@@ -0,0 +1,125 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconcileVectors = reconcileVectors;
+const ts_utils_1 = require("@fgv/ts-utils");
+const types_1 = require("../types");
+const vectorMaintenance_1 = require("./vectorMaintenance");
+/**
+ * Repair one vector lane for one kind, touching only what is missing.
+ *
+ * @remarks
+ * **The `has` check is what makes this targeted rather than a rebuild.** A record
+ * the index already holds costs one membership query and no embedder call, which
+ * is the entire difference between repairing a brief outage and re-embedding a
+ * vault. It is also the only way to see the record-lane case where the index
+ * holds a vector but the envelope lost its `embeddingRef` — that record needs a
+ * restamp and no embedder call, and is indistinguishable from a never-embedded
+ * one if you only look at the envelope.
+ *
+ * Per-record failures are collected rather than fatal: a repair that stops at the
+ * first bad record leaves the rest of the gap open, which is the opposite of what
+ * a caller asked for. A failure to *materialize* is likewise collected — a record
+ * that vanished between the walk and the read is a casualty of this call, not a
+ * reason to abandon the others.
+ */
+async function reconcileVectors(params) {
+    const fragment = params.artifact === 'fragment-vector';
+    const index = fragment ? params.maintenance.fragmentIndex : params.maintenance.vectorIndex;
+    // BOTH halves, not just the index: an index wired without an embedder is a
+    // legal store (queries work, writes simply do not embed), and reconciling it
+    // would otherwise report a cheerful success with every record in `failed`.
+    // "Half the lane is wired" is a wiring mistake and says so.
+    const embedder = fragment ? params.maintenance.fragmentEmbedder : params.maintenance.embedder;
+    if (index === undefined || embedder === undefined) {
+        return (0, ts_utils_1.fail)(`memory reconcile '${params.kind}' ${params.artifact}: the ${fragment ? 'fragment' : 'record-vector'} lane is not fully wired (index: ${index === undefined ? 'absent' : 'present'}, embedder: ${embedder === undefined ? 'absent' : 'present'})`);
+    }
+    if (!fragment && !params.embedsKind(params.kind)) {
+        // Not a failure and not a silent no-op: the caller asked to repair a kind the
+        // store is deliberately not embedding, and the honest answer names that
+        // rather than reporting a healthy zero.
+        return (0, ts_utils_1.fail)(`memory reconcile '${params.kind}' record-vector: this kind is excluded from the record vector index`);
+    }
+    let repaired = 0;
+    let restamped = 0;
+    let declined = 0;
+    let alreadyIndexed = 0;
+    let fragments = 0;
+    const failed = [];
+    for (const entry of params.targets) {
+        const target = { scope: entry.scope, id: entry.envelope.id };
+        // Captured like every other consumer hook: `has` belongs to the injected
+        // index and may throw rather than fail. Unwrapped it would reject the whole
+        // `IMemoryStore.reconcile` call on one bad record, which is both a Result-
+        // contract break and the opposite of this loop's collect-and-continue intent.
+        const held = await (0, vectorMaintenance_1.captureVectorHook)(() => index.has(target), `membership check for '${entry.envelope.id}'`);
+        if (held.isFailure()) {
+            failed.push({ target, error: `membership check failed: ${held.message}` });
+            continue;
+        }
+        if (held.value) {
+            // The record lane can still be inconsistent while the index holds the
+            // vector: a reference lost after the vector was committed. Repairing it
+            // costs a write and no embedding.
+            if (!fragment && (0, types_1.embeddingRefOf)(entry.envelope) === undefined) {
+                // The one place a synthesized reference is unavoidable: `has` proved the
+                // vector exists but there is no contract member that returns the
+                // reference the index minted for it, and re-deriving one would cost the
+                // embedder call this branch exists to avoid. Sound for both shipped
+                // indexes, whose reference IS the scoped key; a third-party index that
+                // mints something else gets the scoped key stamped here. Recorded in
+                // `docs/FUTURE.md` rather than silently assumed.
+                const stamped = params.stampRef(entry.scope, entry.envelope.id, (0, types_1.edgeTargetKey)(target));
+                if (stamped.isFailure()) {
+                    failed.push({ target, error: `restamping the embedding reference failed: ${stamped.message}` });
+                    continue;
+                }
+                restamped++;
+                continue;
+            }
+            alreadyIndexed++;
+            continue;
+        }
+        const resolved = params.resolve(entry.scope, entry.envelope.id);
+        if (resolved.isFailure()) {
+            failed.push({ target, error: `reading the record failed: ${resolved.message}` });
+            continue;
+        }
+        if (resolved.value === undefined) {
+            failed.push({ target, error: 'the index claims this record but the vault has no such file' });
+            continue;
+        }
+        const outcome = await (fragment
+            ? params.maintenance.reembedFragments(resolved.value, target)
+            : params.maintenance.reembedRecord(resolved.value, target));
+        if (outcome.isFailure()) {
+            failed.push({ target, error: outcome.message });
+            continue;
+        }
+        if (outcome.value === undefined) {
+            declined++;
+            continue;
+        }
+        if (fragment) {
+            fragments += outcome.value.count;
+            repaired++;
+            continue;
+        }
+        // The reference the INDEX returned, never a synthesized key: the write path
+        // persists `add`'s value, so a third-party index whose reference is not the
+        // scoped key would otherwise get one stamp from `put` and a different one here.
+        const stamped = params.stampRef(entry.scope, entry.envelope.id, outcome.value.ref);
+        if (stamped.isFailure()) {
+            failed.push({ target, error: `stamping the embedding reference failed: ${stamped.message}` });
+            continue;
+        }
+        repaired++;
+    }
+    const base = { kind: params.kind, examined: params.targets.length, repaired, failed };
+    return (0, ts_utils_1.succeed)(fragment
+        ? Object.assign(Object.assign({}, base), { artifact: 'fragment-vector', alreadyIndexed, declined, fragments }) : Object.assign(Object.assign({}, base), { artifact: 'record-vector', alreadyIndexed, restamped, declined }));
+}
+//# sourceMappingURL=storeReconcile.js.map

package/lib/packlets/store/storeReconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storeReconcile.js","sourceRoot":"","sources":["../../../src/packlets/store/storeReconcile.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport {\n  IEdgeTarget,\n  IMemoryRecord,\n  Kind,\n  MemoryId,\n  MemoryScopeKey,\n  edgeTargetKey,\n  embeddingRefOf\n} from '../types';\nimport { IIndexedMemoryEntry } from '../index';\nimport { ISkippedVectorRecord } from '../vector';\nimport { DerivedArtifact, ReconcileReport } from './reconcile';\nimport { IReembedOutcome, VectorMaintenance, captureVectorHook } from './vectorMaintenance';\n\n/**\n * Everything the vector reconcile branches need, supplied by the store.\n * Package-internal; `IMemoryStore.reconcile` is the published surface.\n */\nexport interface IReconcileVectorsParams {\n  readonly kind: Kind;\n  readonly artifact: Exclude<DerivedArtifact, 'rank'>;\n  /** The kind's index entries — envelopes only, no bodies read yet. */\n  readonly targets: ReadonlyArray<IIndexedMemoryEntry>;\n  readonly maintenance: VectorMaintenance;\n  readonly embedsKind: (kind: Kind) => boolean;\n  /** Materialize one record; `undefined` when it has vanished. */\n  readonly resolve: (scope: MemoryScopeKey, id: MemoryId) => Result<IMemoryRecord<unknown> | undefined>;\n  /** Write an `embeddingRef` onto a record's envelope; `true` when it changed. */\n  readonly stampRef: (scope: MemoryScopeKey, id: MemoryId, ref: string) => Result<boolean>;\n}\n\n/**\n * Repair one vector lane for one kind, touching only what is missing.\n *\n * @remarks\n * **The `has` check is what makes this targeted rather than a rebuild.** A record\n * the index already holds costs one membership query and no embedder call, which\n * is the entire difference between repairing a brief outage and re-embedding a\n * vault. It is also the only way to see the record-lane case where the index\n * holds a vector but the envelope lost its `embeddingRef` — that record needs a\n * restamp and no embedder call, and is indistinguishable from a never-embedded\n * one if you only look at the envelope.\n *\n * Per-record failures are collected rather than fatal: a repair that stops at the\n * first bad record leaves the rest of the gap open, which is the opposite of what\n * a caller asked for. A failure to *materialize* is likewise collected — a record\n * that vanished between the walk and the read is a casualty of this call, not a\n * reason to abandon the others.\n */\nexport async function reconcileVectors(params: IReconcileVectorsParams): Promise<Result<ReconcileReport>> {\n  const fragment: boolean = params.artifact === 'fragment-vector';\n  const index = fragment ? params.maintenance.fragmentIndex : params.maintenance.vectorIndex;\n  // BOTH halves, not just the index: an index wired without an embedder is a\n  // legal store (queries work, writes simply do not embed), and reconciling it\n  // would otherwise report a cheerful success with every record in `failed`.\n  // \"Half the lane is wired\" is a wiring mistake and says so.\n  const embedder = fragment ? params.maintenance.fragmentEmbedder : params.maintenance.embedder;\n  if (index === undefined || embedder === undefined) {\n    return fail(\n      `memory reconcile '${params.kind}' ${params.artifact}: the ${\n        fragment ? 'fragment' : 'record-vector'\n      } lane is not fully wired (index: ${index === undefined ? 'absent' : 'present'}, embedder: ${\n        embedder === undefined ? 'absent' : 'present'\n      })`\n    );\n  }\n  if (!fragment && !params.embedsKind(params.kind)) {\n    // Not a failure and not a silent no-op: the caller asked to repair a kind the\n    // store is deliberately not embedding, and the honest answer names that\n    // rather than reporting a healthy zero.\n    return fail(\n      `memory reconcile '${params.kind}' record-vector: this kind is excluded from the record vector index`\n    );\n  }\n\n  let repaired: number = 0;\n  let restamped: number = 0;\n  let declined: number = 0;\n  let alreadyIndexed: number = 0;\n  let fragments: number = 0;\n  const failed: ISkippedVectorRecord[] = [];\n\n  for (const entry of params.targets) {\n    const target: IEdgeTarget = { scope: entry.scope, id: entry.envelope.id };\n    // Captured like every other consumer hook: `has` belongs to the injected\n    // index and may throw rather than fail. Unwrapped it would reject the whole\n    // `IMemoryStore.reconcile` call on one bad record, which is both a Result-\n    // contract break and the opposite of this loop's collect-and-continue intent.\n    const held: Result<boolean> = await captureVectorHook(\n      () => index.has(target),\n      `membership check for '${entry.envelope.id}'`\n    );\n    if (held.isFailure()) {\n      failed.push({ target, error: `membership check failed: ${held.message}` });\n      continue;\n    }\n    if (held.value) {\n      // The record lane can still be inconsistent while the index holds the\n      // vector: a reference lost after the vector was committed. Repairing it\n      // costs a write and no embedding.\n      if (!fragment && embeddingRefOf(entry.envelope) === undefined) {\n        // The one place a synthesized reference is unavoidable: `has` proved the\n        // vector exists but there is no contract member that returns the\n        // reference the index minted for it, and re-deriving one would cost the\n        // embedder call this branch exists to avoid. Sound for both shipped\n        // indexes, whose reference IS the scoped key; a third-party index that\n        // mints something else gets the scoped key stamped here. Recorded in\n        // `docs/FUTURE.md` rather than silently assumed.\n        const stamped: Result<boolean> = params.stampRef(\n          entry.scope,\n          entry.envelope.id,\n          edgeTargetKey(target)\n        );\n        if (stamped.isFailure()) {\n          failed.push({ target, error: `restamping the embedding reference failed: ${stamped.message}` });\n          continue;\n        }\n        restamped++;\n        continue;\n      }\n      alreadyIndexed++;\n      continue;\n    }\n\n    const resolved: Result<IMemoryRecord<unknown> | undefined> = params.resolve(\n      entry.scope,\n      entry.envelope.id\n    );\n    if (resolved.isFailure()) {\n      failed.push({ target, error: `reading the record failed: ${resolved.message}` });\n      continue;\n    }\n    if (resolved.value === undefined) {\n      failed.push({ target, error: 'the index claims this record but the vault has no such file' });\n      continue;\n    }\n    const outcome: Result<IReembedOutcome | undefined> = await (fragment\n      ? params.maintenance.reembedFragments(resolved.value, target)\n      : params.maintenance.reembedRecord(resolved.value, target));\n    if (outcome.isFailure()) {\n      failed.push({ target, error: outcome.message });\n      continue;\n    }\n    if (outcome.value === undefined) {\n      declined++;\n      continue;\n    }\n    if (fragment) {\n      fragments += outcome.value.count;\n      repaired++;\n      continue;\n    }\n    // The reference the INDEX returned, never a synthesized key: the write path\n    // persists `add`'s value, so a third-party index whose reference is not the\n    // scoped key would otherwise get one stamp from `put` and a different one here.\n    const stamped: Result<boolean> = params.stampRef(entry.scope, entry.envelope.id, outcome.value.ref);\n    if (stamped.isFailure()) {\n      failed.push({ target, error: `stamping the embedding reference failed: ${stamped.message}` });\n      continue;\n    }\n    repaired++;\n  }\n\n  const base = { kind: params.kind, examined: params.targets.length, repaired, failed };\n  return succeed(\n    fragment\n      ? { ...base, artifact: 'fragment-vector', alreadyIndexed, declined, fragments }\n      : { ...base, artifact: 'record-vector', alreadyIndexed, restamped, declined }\n  );\n}\n"]}

package/lib/packlets/store/vectorMaintenance.d.ts

@@ -2,6 +2,16 @@ import { Result } from '@fgv/ts-utils';
 import { MemoryEmbedOutcome } from '../observe';
 import { IEdgeTarget, IMemoryRecord, Kind, MemoryId, MemoryScopeKey } from '../types';
 import { FragmentEmbedder, IFragmentVectorIndex, IVectorIndex, MemoryEmbedder } from '../vector';
+/**
+ * What a repair-path re-embed established: how many vectors/fragments were
+ * written, and — record lane only — the reference the index returned, which is
+ * what the store stamps onto the envelope.
+ */
+export interface IReembedOutcome {
+    readonly count: number;
+    /** The index-supplied reference. Empty on the fragment lane, which has none. */
+    readonly ref: string;
+}
 /**
  * The internal outcome of record-level embed-on-write: the record to persist,
  * plus — only when the embedder declined a record that already carried an
@@ -25,6 +35,30 @@ export interface IEmbedOnWriteOutcome {
      */
     readonly embed?: MemoryEmbedOutcome;
 }
+/**
+ * Run a consumer-supplied hook, normalizing a synchronous throw or a rejected
+ * promise into a `Failure`.
+ *
+ * @remarks
+ * **Every vector-lane hook belongs to the consumer** — the embedder, the fragment
+ * embedder, and every member of both index seams — so any of them may throw
+ * rather than fail. Left unwrapped, that escapes as a rejected promise out of
+ * `IMemoryStore.reconcile`, which the repo's Result contract says cannot happen.
+ *
+ * **Module-level and exported rather than a private of {@link VectorMaintenance},
+ * because the repair loop in `storeReconcile.ts` needs it too.** It calls
+ * `index.has` per record, which is a consumer hook like any other; when the four
+ * embed/add hooks were wrapped, that fifth one was missed, and a second private
+ * copy would have made the next omission just as easy. One hook, one helper.
+ *
+ * Kept separate from {@link VectorMaintenance._tryVectorOp} (which delegates
+ * here and adds a warn) because that warning says "best-effort; derived index
+ * left for rebuild" — true of a write, false of a repair. The repair *is* the
+ * rebuild, and it returns its failures to the caller who asked for them rather
+ * than logging them past a success.
+ * @internal
+ */
+export declare function captureVectorHook<T>(op: () => Promise<Result<T>>, label: string): Promise<Result<T>>;
 /**
  * What {@link VectorMaintenance} needs from the store it serves. Every field is
  * the store's own, passed in rather than reached for, so this collaborator holds
@@ -76,6 +110,46 @@ export declare class VectorMaintenance {
      * committed by the time they call it.
      */
     removeAll(target: IEdgeTarget): Promise<void>;
+    /**
+     * The wired record-vector index, or `undefined`. Read-only, and exposed solely
+     * so the store's {@link IMemoryStore.coverage} can report an index-side count
+     * without a second copy of the wiring — absent here IS the "lane not wired"
+     * answer that coverage reports as `undefined` rather than as zero.
+     */
+    get vectorIndex(): IVectorIndex | undefined;
+    /** The wired fragment index, or `undefined`. See {@link VectorMaintenance.vectorIndex}. */
+    get fragmentIndex(): IFragmentVectorIndex | undefined;
+    /**
+     * The wired record embedder, or `undefined`. Exposed alongside the index
+     * because a lane is only usable when BOTH halves are present — an index with
+     * no embedder is a legal store whose writes simply do not embed, and a repair
+     * has to say so rather than failing every record.
+     */
+    get embedder(): MemoryEmbedder | undefined;
+    /** The wired fragment embedder, or `undefined`. See {@link VectorMaintenance.embedder}. */
+    get fragmentEmbedder(): FragmentEmbedder | undefined;
+    /**
+     * Re-embed one record into the record-vector index — the repair path.
+     *
+     * @remarks
+     * Distinct from {@link VectorMaintenance.embedOnWrite} in the one way that
+     * matters: **this is not best-effort.** Embed-on-write swallows a failure
+     * because a vault record is the source of truth and a write must not be
+     * rejected over a derived artifact; a repair was *asked for* by a caller who
+     * wants to know whether it worked, so a failure is returned.
+     *
+     * `undefined` means the embedder declined — intentionally not embedded, which
+     * is neither a repair nor a fault.
+     */
+    reembedRecord(record: IMemoryRecord<unknown>, target: IEdgeTarget): Promise<Result<IReembedOutcome | undefined>>;
+    /**
+     * Re-embed one record's fragments — the repair path, returning the fragment
+     * count written. See {@link VectorMaintenance.reembedRecord} for why this is
+     * not best-effort. An empty fragment array is this lane's decline and reports
+     * `undefined`, though the whole-record-replace still runs so stale fragments
+     * are cleared.
+     */
+    reembedFragments(record: IMemoryRecord<unknown>, target: IEdgeTarget): Promise<Result<IReembedOutcome | undefined>>;
     /**
      * 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

package/lib/packlets/store/vectorMaintenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vectorMaintenance.d.ts","sourceRoot":"","sources":["../../../src/packlets/store/vectorMaintenance.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAiB,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACtF,OAAO,EACL,gBAAgB,EAEhB,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACf,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;KAAE,CAAC;IAChF;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;CACrC;AA4CD;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,WAAW,CAAC,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,oBAAoB,CAAC;IAC9C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA2B;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAmC;IAClE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA+B;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4B;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0B;gBAEnC,MAAM,EAAE,wBAAwB;IASnD;;;;OAIG;IACU,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1D;;;;;;;;;;;;;;OAcG;IACU,YAAY,CACvB,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,EAC5B,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAuDxC;;;;;;;;;;;OAWG;IACU,gBAAgB,CAAC,KAAK,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAUlF;;;;;;;;;;OAUG;IACU,qBAAqB,CAChC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,EAC5B,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;IAqBzC;;;;;;OAMG;YACW,0BAA0B;IAQxC;;;;;OAKG;IACU,oBAAoB,CAAC,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzG;;;;OAIG;YACW,YAAY;IAa1B;;;;;OAKG;YACW,uBAAuB;CAOtC"}
+{"version":3,"file":"vectorMaintenance.d.ts","sourceRoot":"","sources":["../../../src/packlets/store/vectorMaintenance.ts"],"names":[],"mappings":"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"}

package/lib/packlets/store/vectorMaintenance.js

@@ -16,7 +16,9 @@ var __rest = (this && this.__rest) || function (s, e) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VectorMaintenance = void 0;
+exports.captureVectorHook = captureVectorHook;
 const ts_utils_1 = require("@fgv/ts-utils");
+const types_1 = require("../types");
 /**
  * Project a record the embedder **declined** into its written form: the same
  * record with no `embeddingRef`, plus the vector (if any) that reference
@@ -43,7 +45,7 @@ const ts_utils_1 = require("@fgv/ts-utils");
  * `_persist`.
  */
 function declineEmbedding(built, index, target, embed) {
-    if (built.envelope.embeddingRef === undefined) {
+    if ((0, types_1.embeddingRefOf)(built.envelope) === undefined) {
         return { record: built, embed };
     }
     // Rest-spread rather than `embeddingRef: undefined`: the envelope is YAML-
@@ -53,6 +55,37 @@ function declineEmbedding(built, index, target, embed) {
     const _a = built.envelope, { embeddingRef } = _a, envelope = __rest(_a, ["embeddingRef"]);
     return { record: { envelope, body: built.body }, stale: { index, target }, embed };
 }
+/**
+ * Run a consumer-supplied hook, normalizing a synchronous throw or a rejected
+ * promise into a `Failure`.
+ *
+ * @remarks
+ * **Every vector-lane hook belongs to the consumer** — the embedder, the fragment
+ * embedder, and every member of both index seams — so any of them may throw
+ * rather than fail. Left unwrapped, that escapes as a rejected promise out of
+ * `IMemoryStore.reconcile`, which the repo's Result contract says cannot happen.
+ *
+ * **Module-level and exported rather than a private of {@link VectorMaintenance},
+ * because the repair loop in `storeReconcile.ts` needs it too.** It calls
+ * `index.has` per record, which is a consumer hook like any other; when the four
+ * embed/add hooks were wrapped, that fifth one was missed, and a second private
+ * copy would have made the next omission just as easy. One hook, one helper.
+ *
+ * Kept separate from {@link VectorMaintenance._tryVectorOp} (which delegates
+ * here and adds a warn) because that warning says "best-effort; derived index
+ * left for rebuild" — true of a write, false of a repair. The repair *is* the
+ * rebuild, and it returns its failures to the caller who asked for them rather
+ * than logging them past a success.
+ * @internal
+ */
+async function captureVectorHook(op, label) {
+    try {
+        return await op();
+    }
+    catch (err) {
+        return (0, ts_utils_1.fail)(`${label} threw: ${String(err)}`);
+    }
+}
 /**
  * The store's record- and fragment-vector maintenance, extracted from
  * {@link FileTreeMemoryStore} as a collaborator.
@@ -88,6 +121,88 @@ class VectorMaintenance {
         await this._removeVectorBestEffort(target);
         await this._removeFragmentsBestEffort(target);
     }
+    /**
+     * The wired record-vector index, or `undefined`. Read-only, and exposed solely
+     * so the store's {@link IMemoryStore.coverage} can report an index-side count
+     * without a second copy of the wiring — absent here IS the "lane not wired"
+     * answer that coverage reports as `undefined` rather than as zero.
+     */
+    get vectorIndex() {
+        return this._vectorIndex;
+    }
+    /** The wired fragment index, or `undefined`. See {@link VectorMaintenance.vectorIndex}. */
+    get fragmentIndex() {
+        return this._fragmentIndex;
+    }
+    /**
+     * The wired record embedder, or `undefined`. Exposed alongside the index
+     * because a lane is only usable when BOTH halves are present — an index with
+     * no embedder is a legal store whose writes simply do not embed, and a repair
+     * has to say so rather than failing every record.
+     */
+    get embedder() {
+        return this._embed;
+    }
+    /** The wired fragment embedder, or `undefined`. See {@link VectorMaintenance.embedder}. */
+    get fragmentEmbedder() {
+        return this._fragmentEmbedder;
+    }
+    /**
+     * Re-embed one record into the record-vector index — the repair path.
+     *
+     * @remarks
+     * Distinct from {@link VectorMaintenance.embedOnWrite} in the one way that
+     * matters: **this is not best-effort.** Embed-on-write swallows a failure
+     * because a vault record is the source of truth and a write must not be
+     * rejected over a derived artifact; a repair was *asked for* by a caller who
+     * wants to know whether it worked, so a failure is returned.
+     *
+     * `undefined` means the embedder declined — intentionally not embedded, which
+     * is neither a repair nor a fault.
+     */
+    async reembedRecord(record, target) {
+        if (this._vectorIndex === undefined || this._embed === undefined) {
+            return (0, ts_utils_1.fail)('the record-vector lane is not wired');
+        }
+        const index = this._vectorIndex;
+        const embed = this._embed;
+        const embedded = await captureVectorHook(() => embed(record), `re-embedding '${record.envelope.id}'`);
+        if (embedded.isFailure()) {
+            return (0, ts_utils_1.fail)(embedded.message);
+        }
+        if (embedded.value === undefined) {
+            return (0, ts_utils_1.succeed)(undefined);
+        }
+        // Hoisted: the `undefined` check above does not narrow across the callback
+        // boundary below.
+        const vector = embedded.value;
+        // `add`'s return value IS the reference the store stamps — synthesizing one
+        // here would diverge from the write path for any index whose reference is
+        // not the scoped key.
+        return (await captureVectorHook(() => index.add(target, vector), `vector add for '${record.envelope.id}'`)).onSuccess((ref) => (0, ts_utils_1.succeed)({ count: 1, ref }));
+    }
+    /**
+     * Re-embed one record's fragments — the repair path, returning the fragment
+     * count written. See {@link VectorMaintenance.reembedRecord} for why this is
+     * not best-effort. An empty fragment array is this lane's decline and reports
+     * `undefined`, though the whole-record-replace still runs so stale fragments
+     * are cleared.
+     */
+    async reembedFragments(record, target) {
+        if (this._fragmentIndex === undefined || this._fragmentEmbedder === undefined) {
+            return (0, ts_utils_1.fail)('the fragment lane is not wired');
+        }
+        const index = this._fragmentIndex;
+        const fragmentEmbedder = this._fragmentEmbedder;
+        const embedded = await captureVectorHook(() => fragmentEmbedder(record), `re-embedding fragments of '${record.envelope.id}'`);
+        if (embedded.isFailure()) {
+            return (0, ts_utils_1.fail)(embedded.message);
+        }
+        const fragments = embedded.value;
+        return (await captureVectorHook(() => index.addFragments(target, fragments), `fragment add for '${record.envelope.id}'`)).onSuccess((n) => 
+        // The fragment lane has no envelope reference, so `ref` is empty and unused.
+        (0, ts_utils_1.succeed)(n === 0 ? undefined : { count: n, ref: '' }));
+    }
     /**
      * 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
@@ -225,13 +340,7 @@ class VectorMaintenance {
      * regardless, since the index is rebuildable.
      */
     async _tryVectorOp(op, label) {
-        let result;
-        try {
-            result = await op();
-        }
-        catch (err) {
-            result = (0, ts_utils_1.fail)(`${label} threw: ${String(err)}`);
-        }
+        const result = await captureVectorHook(op, label);
         if (result.isFailure()) {
             this._warn(`memory: ${label} failed (best-effort; derived index left for rebuild): ${result.message}`);
         }