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

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

@@ -1,3 +1,7 @@
+export * from './coverage';
+export * from './reconcile';
+export * from './listSelection';
+export * from './memoryStore';
 export * from './fileTreeMemoryStore';
 export * from './scopeEncoding';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/store/index.ts"],"names":[],"mappings":"AAKA,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/store/index.ts"],"names":[],"mappings":"AAKA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC"}

package/lib/packlets/store/index.js

@@ -18,6 +18,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./coverage"), exports);
+__exportStar(require("./reconcile"), exports);
+__exportStar(require("./listSelection"), exports);
+__exportStar(require("./memoryStore"), exports);
 __exportStar(require("./fileTreeMemoryStore"), exports);
 __exportStar(require("./scopeEncoding"), exports);
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/store/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,wDAAsC;AACtC,kDAAgC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './fileTreeMemoryStore';\nexport * from './scopeEncoding';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/store/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,6CAA2B;AAC3B,8CAA4B;AAC5B,kDAAgC;AAChC,gDAA8B;AAC9B,wDAAsC;AACtC,kDAAgC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './coverage';\nexport * from './reconcile';\nexport * from './listSelection';\nexport * from './memoryStore';\nexport * from './fileTreeMemoryStore';\nexport * from './scopeEncoding';\n"]}

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

@@ -0,0 +1,101 @@
+import { Kind, MemoryScopeKey, Tag } from '../types';
+/**
+ * Filter for {@link IMemoryStore.list}. All present fields are ANDed together.
+ *
+ * @remarks
+ * **At least one of `scope` / `kind` / `tag` must be present.** `asOf` is a
+ * temporal *projection*, not a narrowing — it collapses versions rather than
+ * excluding entities — so it does not satisfy the requirement on its own. A
+ * selection that narrows nothing fails with a message naming
+ * {@link scanEveryRecord}.
+ * @public
+ */
+export interface IMemoryStoreListFilter {
+    /**
+     * Never present on a narrowing filter.
+     *
+     * @remarks
+     * Exclusivity marker, paired with the `never`s on {@link IWholeVaultScan}.
+     * Without it `{ scanEveryRecord: true, kind }` type-checks — TypeScript's
+     * excess-property check on a union admits any property declared by *any*
+     * member — and `list` then takes the scan branch and silently discards the
+     * narrowing. Since the whole point of requiring a selection is that a
+     * whole-vault read must be deliberate, a call that reads the whole vault while
+     * *looking* narrowed is the one outcome this surface must not permit.
+     */
+    readonly scanEveryRecord?: never;
+    /** Restrict to records in this scope. */
+    readonly scope?: MemoryScopeKey;
+    /** Restrict to records of this kind. */
+    readonly kind?: Kind;
+    /** Restrict to records carrying this tag (exact match). */
+    readonly tag?: Tag;
+    /**
+     * For temporal (versioned) kinds: collapse each entity to the single version
+     * valid at this epoch ms. Non-temporal records are timeless and pass through
+     * unchanged. Absent = no temporal projection (every version is returned).
+     */
+    readonly asOf?: number;
+}
+/**
+ * The named, deliberately uncomfortable opt-out from
+ * {@link IMemoryStore.list}'s narrowing requirement — build one with
+ * {@link scanEveryRecord}.
+ * @public
+ */
+export interface IWholeVaultScan {
+    /** Discriminator. Always `true`; produced only by {@link scanEveryRecord}. */
+    readonly scanEveryRecord: true;
+    /**
+     * Never present on a whole-vault scan — see
+     * {@link IMemoryStoreListFilter.scanEveryRecord} for why these markers exist.
+     * A scan that also carried a narrowing axis would have that axis dropped.
+     */
+    readonly scope?: never;
+    /** Never present on a whole-vault scan. See {@link IWholeVaultScan.scope}. */
+    readonly kind?: never;
+    /** Never present on a whole-vault scan. See {@link IWholeVaultScan.scope}. */
+    readonly tag?: never;
+    /**
+     * Optional temporal projection, exactly as on {@link IMemoryStoreListFilter}.
+     * NOT excluded, because `asOf` projects rather than narrows and composes with
+     * a whole-vault read exactly as it does with a filtered one.
+     */
+    readonly asOf?: number;
+}
+/**
+ * What {@link IMemoryStore.list} accepts: a narrowing filter, or the explicit
+ * whole-vault scan.
+ * @public
+ */
+export type MemoryListSelection = IMemoryStoreListFilter | IWholeVaultScan;
+/**
+ * Ask {@link IMemoryStore.list} for **every record in the vault**, bodies
+ * included.
+ *
+ * @remarks
+ * `list` requires a selection and rejects one that narrows nothing, so this is
+ * the only way to get the whole vault — and that is the point. Since the index
+ * holds envelopes only, `list` materializes every survivor from storage, so an
+ * unnarrowed call reads one file per record. Making it impossible to write by
+ * accident is worth more than making it fast.
+ *
+ * It is named for what it costs rather than for what it returns, and it is
+ * greppable: `scanEveryRecord` enumerates every whole-vault read in a codebase in
+ * one search. This mirrors `@fgv/ts-extras`' `safer-fetch`, where `addressGuard`
+ * is required with no default and `allowAnyAddress()` is the named opt-out.
+ *
+ * **If you only need to select, you do not need this.** Use
+ * {@link IMemoryStore.listEntries}, which returns every entry's scope and
+ * envelope, reads no files, and needs no selection.
+ * @public
+ */
+export declare function scanEveryRecord(options?: {
+    readonly asOf?: number;
+}): IWholeVaultScan;
+/**
+ * Whether a selection is the explicit whole-vault opt-out.
+ * @public
+ */
+export declare function isWholeVaultScan(selection: MemoryListSelection): selection is IWholeVaultScan;
+//# sourceMappingURL=listSelection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"listSelection.d.ts","sourceRoot":"","sources":["../../../src/packlets/store/listSelection.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAErD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,CAAC;IACjC,yCAAyC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,sBAAsB,GAAG,eAAe,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,eAAe,CAKrF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,mBAAmB,GAAG,SAAS,IAAI,eAAe,CAE7F"}

package/lib/packlets/store/listSelection.js

@@ -0,0 +1,40 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanEveryRecord = scanEveryRecord;
+exports.isWholeVaultScan = isWholeVaultScan;
+/**
+ * Ask {@link IMemoryStore.list} for **every record in the vault**, bodies
+ * included.
+ *
+ * @remarks
+ * `list` requires a selection and rejects one that narrows nothing, so this is
+ * the only way to get the whole vault — and that is the point. Since the index
+ * holds envelopes only, `list` materializes every survivor from storage, so an
+ * unnarrowed call reads one file per record. Making it impossible to write by
+ * accident is worth more than making it fast.
+ *
+ * It is named for what it costs rather than for what it returns, and it is
+ * greppable: `scanEveryRecord` enumerates every whole-vault read in a codebase in
+ * one search. This mirrors `@fgv/ts-extras`' `safer-fetch`, where `addressGuard`
+ * is required with no default and `allowAnyAddress()` is the named opt-out.
+ *
+ * **If you only need to select, you do not need this.** Use
+ * {@link IMemoryStore.listEntries}, which returns every entry's scope and
+ * envelope, reads no files, and needs no selection.
+ * @public
+ */
+function scanEveryRecord(options) {
+    return Object.assign({ scanEveryRecord: true }, ((options === null || options === void 0 ? void 0 : options.asOf) !== undefined ? { asOf: options.asOf } : {}));
+}
+/**
+ * Whether a selection is the explicit whole-vault opt-out.
+ * @public
+ */
+function isWholeVaultScan(selection) {
+    return selection.scanEveryRecord === true;
+}
+//# sourceMappingURL=listSelection.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"listSelection.js","sourceRoot":"","sources":["../../../src/packlets/store/listSelection.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAkGH,0CAKC;AAMD,4CAEC;AAlCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,eAAe,CAAC,OAAoC;IAClE,uBACE,eAAe,EAAE,IAAI,IAClB,CAAC,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,IAAI,MAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAC9D;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,SAA8B;IAC7D,OAAQ,SAA6B,CAAC,eAAe,KAAK,IAAI,CAAC;AACjE,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Kind, MemoryScopeKey, Tag } from '../types';\n\n/**\n * Filter for {@link IMemoryStore.list}. All present fields are ANDed together.\n *\n * @remarks\n * **At least one of `scope` / `kind` / `tag` must be present.** `asOf` is a\n * temporal *projection*, not a narrowing — it collapses versions rather than\n * excluding entities — so it does not satisfy the requirement on its own. A\n * selection that narrows nothing fails with a message naming\n * {@link scanEveryRecord}.\n * @public\n */\nexport interface IMemoryStoreListFilter {\n  /**\n   * Never present on a narrowing filter.\n   *\n   * @remarks\n   * Exclusivity marker, paired with the `never`s on {@link IWholeVaultScan}.\n   * Without it `{ scanEveryRecord: true, kind }` type-checks — TypeScript's\n   * excess-property check on a union admits any property declared by *any*\n   * member — and `list` then takes the scan branch and silently discards the\n   * narrowing. Since the whole point of requiring a selection is that a\n   * whole-vault read must be deliberate, a call that reads the whole vault while\n   * *looking* narrowed is the one outcome this surface must not permit.\n   */\n  readonly scanEveryRecord?: never;\n  /** Restrict to records in this scope. */\n  readonly scope?: MemoryScopeKey;\n  /** Restrict to records of this kind. */\n  readonly kind?: Kind;\n  /** Restrict to records carrying this tag (exact match). */\n  readonly tag?: Tag;\n  /**\n   * For temporal (versioned) kinds: collapse each entity to the single version\n   * valid at this epoch ms. Non-temporal records are timeless and pass through\n   * unchanged. Absent = no temporal projection (every version is returned).\n   */\n  readonly asOf?: number;\n}\n\n/**\n * The named, deliberately uncomfortable opt-out from\n * {@link IMemoryStore.list}'s narrowing requirement — build one with\n * {@link scanEveryRecord}.\n * @public\n */\nexport interface IWholeVaultScan {\n  /** Discriminator. Always `true`; produced only by {@link scanEveryRecord}. */\n  readonly scanEveryRecord: true;\n  /**\n   * Never present on a whole-vault scan — see\n   * {@link IMemoryStoreListFilter.scanEveryRecord} for why these markers exist.\n   * A scan that also carried a narrowing axis would have that axis dropped.\n   */\n  readonly scope?: never;\n  /** Never present on a whole-vault scan. See {@link IWholeVaultScan.scope}. */\n  readonly kind?: never;\n  /** Never present on a whole-vault scan. See {@link IWholeVaultScan.scope}. */\n  readonly tag?: never;\n  /**\n   * Optional temporal projection, exactly as on {@link IMemoryStoreListFilter}.\n   * NOT excluded, because `asOf` projects rather than narrows and composes with\n   * a whole-vault read exactly as it does with a filtered one.\n   */\n  readonly asOf?: number;\n}\n\n/**\n * What {@link IMemoryStore.list} accepts: a narrowing filter, or the explicit\n * whole-vault scan.\n * @public\n */\nexport type MemoryListSelection = IMemoryStoreListFilter | IWholeVaultScan;\n\n/**\n * Ask {@link IMemoryStore.list} for **every record in the vault**, bodies\n * included.\n *\n * @remarks\n * `list` requires a selection and rejects one that narrows nothing, so this is\n * the only way to get the whole vault — and that is the point. Since the index\n * holds envelopes only, `list` materializes every survivor from storage, so an\n * unnarrowed call reads one file per record. Making it impossible to write by\n * accident is worth more than making it fast.\n *\n * It is named for what it costs rather than for what it returns, and it is\n * greppable: `scanEveryRecord` enumerates every whole-vault read in a codebase in\n * one search. This mirrors `@fgv/ts-extras`' `safer-fetch`, where `addressGuard`\n * is required with no default and `allowAnyAddress()` is the named opt-out.\n *\n * **If you only need to select, you do not need this.** Use\n * {@link IMemoryStore.listEntries}, which returns every entry's scope and\n * envelope, reads no files, and needs no selection.\n * @public\n */\nexport function scanEveryRecord(options?: { readonly asOf?: number }): IWholeVaultScan {\n  return {\n    scanEveryRecord: true,\n    ...(options?.asOf !== undefined ? { asOf: options.asOf } : {})\n  };\n}\n\n/**\n * Whether a selection is the explicit whole-vault opt-out.\n * @public\n */\nexport function isWholeVaultScan(selection: MemoryListSelection): selection is IWholeVaultScan {\n  return (selection as IWholeVaultScan).scanEveryRecord === true;\n}\n"]}

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

@@ -0,0 +1,237 @@
+import { Result } from '@fgv/ts-utils';
+import { DedupScope, EntityId, IMemoryRecord, IMemoryRecordResolver, Kind, MemoryId, MemoryScopeKey } from '../types';
+import { IIndexedMemoryEntry } from '../index';
+import { IMemoryRecordSource, IScopedMemoryRecord } from '../vector';
+import { MemoryListSelection } from './listSelection';
+import { IDerivedStateCoverage } from './coverage';
+import { DerivedArtifact, ReconcileReport } from './reconcile';
+/**
+ * The writable, FileTree-backed, content-hash-deduped memory store.
+ *
+ * @remarks
+ * Extends {@link IMemoryRecordResolver} because the retrievers take a resolver
+ * and a store is the obvious one to hand them — `{ index, resolver: store }` is
+ * the documented wiring, and it has to type-check for the `IMemoryStore` handle
+ * a consumer actually holds, not only for the concrete `FileTreeMemoryStore`.
+ * @public
+ */
+export interface IMemoryStore extends IMemoryRecordResolver {
+    /**
+     * Keyed read by entity id. Resolves `entityId` to a storage address via the
+     * registered {@link IIdentityCodec} for `kind`. Returns `undefined` when no
+     * record exists. For a versioned (temporal) kind the current version is
+     * *selected* from the derived in-memory index — the version history is walked
+     * over envelopes, never bodies — and then that one version is read from
+     * storage. So the selection costs no file reads and the result costs exactly
+     * one, rather than one per version.
+     */
+    get(kind: Kind, entityId: EntityId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
+    /**
+     * Direct read by `(scope, MemoryId)`. Returns `undefined` when not found.
+     */
+    getById(scope: MemoryScopeKey, id: MemoryId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
+    /**
+     * List records: select over the derived index, then materialize the survivors.
+     *
+     * @remarks
+     * **The selection is required and must narrow.** Since the index holds
+     * envelopes only, every returned record is read from storage — so a call that
+     * narrows nothing reads the whole vault, and that has to be a decision rather
+     * than a default. Omitting the argument is a compile error; passing one with no
+     * `scope` / `kind` / `tag` fails with a message naming {@link scanEveryRecord},
+     * which is how a caller says it meant it.
+     *
+     * The requirement buys **explicitness, not a cost bound** — `{ kind }` on a
+     * vault dominated by that kind still materializes most of it. What it prevents
+     * is the whole-vault read nobody chose.
+     *
+     * If you only need to select, use {@link IMemoryStore.listEntries} instead: no
+     * selection, no file reads.
+     */
+    list(selection: MemoryListSelection): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    /**
+     * How much of the store's **derived state** exists, resolved by {@link Kind}.
+     *
+     * @remarks
+     * Answers *"is my derived state consistent with my records, and if not by how
+     * much?"* for every artifact the store derives — `rank`, record vectors, and
+     * fragment vectors — in one call.
+     *
+     * **Cheap and total, by contract rather than by implementation.** Every input is
+     * an envelope field or an index-side count: it reads **no record bodies** and
+     * calls **no embedder**, and the walk over the vault's own state touches the
+     * filesystem not at all. That is why it takes no selection, unlike
+     * {@link IMemoryStore.list} — the guard there exists because an unnarrowed list
+     * reads the vault, and putting one here would decorate a free operation and make
+     * that guard mean less.
+     *
+     * **The index-side counts are the one exception, and it is the caller's own
+     * index that spends it.** A persistent index answers `size` / `recordCount` /
+     * `fragmentCount` with a query — `SqliteVecVectorIndex` runs a prepared `COUNT`
+     * — so on a durable backend this call does I/O and can **fail**. It is bounded
+     * (one count per wired index, never per record) and it is why the return is a
+     * `Result` rather than a bare value.
+     *
+     * *If a future addition to the report would require reading a record body, it
+     * does not belong on this report.*
+     *
+     * The counterpart is {@link IMemoryStore.reconcile}: coverage says **how big**
+     * the gap is, cheaply; reconcile says **what it was** and closes what it can, at
+     * the cost of re-running the embedder. Neither substitutes for the other.
+     *
+     * **A lane is reported here whenever its *index* is wired**, which is weaker
+     * than what reconcile requires (index **and** embedder). That is intended: an
+     * index without an embedder still holds vectors and still answers queries, so
+     * its coverage is a real number worth reporting. The consequence to expect is a
+     * half-wired store that reports a gap `reconcile` will refuse to close, naming
+     * the missing embedder.
+     */
+    coverage(): Promise<Result<IDerivedStateCoverage>>;
+    /**
+     * Every entry in the vault — scope and envelope, **no bodies**. Reads no files
+     * and requires no selection, because there is nothing to be careful about: it
+     * returns what the index already holds.
+     *
+     * @remarks
+     * This is the whole-vault read most callers actually want. Selection, grouping,
+     * counting, "which kinds are in here", "what links at this" — all of it is
+     * envelope work. Reach for {@link IMemoryStore.list} with
+     * {@link scanEveryRecord} only when you genuinely need every body.
+     *
+     * Synchronous in spirit but `Promise`-returning for consistency with the rest
+     * of the store surface.
+     */
+    listEntries(): Promise<Result<ReadonlyArray<IIndexedMemoryEntry>>>;
+    /**
+     * List EVERY record in the vault, each paired with its scope-qualified
+     * `(scope, id)` address — the projection {@link IMemoryRecordSource} requires.
+     * Unlike {@link IMemoryStore.list | list}, it takes no filter (whole-vault) and
+     * returns {@link IScopedMemoryRecord}s so a re-index keys each entry on the same
+     * scoped target the incremental embed-on-write path uses. Two records that share
+     * a filename stem across scopes appear as distinct entries.
+     */
+    listScoped(): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>>;
+    /**
+     * Adapt this store to the {@link IMemoryRecordSource} seam so it can drive
+     * {@link IVectorIndex} rebuilds (e.g. `InMemoryCosineIndex.rebuild`). The
+     * returned source's `list()` delegates to {@link IMemoryStore.listScoped},
+     * **filtered to the kinds {@link IMemoryStore.embedsKind | embedsKind} reports** —
+     * this source exists to feed the record vector index, so a kind excluded from
+     * that index is excluded here too, and a reopen does not re-embed records the
+     * index will never return. With no
+     * {@link IFileTreeMemoryStoreCreateParams.embedKinds | embedKinds} declaration
+     * every kind participates and the filter is the identity. `listScoped` itself is
+     * **not** filtered and remains the whole-vault surface.
+     *
+     * The filter also **counts what it drops**, onto
+     * {@link IMemoryRecordListing.excluded} — this is the layer where the exclusion
+     * decision is made and so the only one that can. The count is always present
+     * (empty when nothing was excluded).
+     *
+     * The store cannot implement {@link IMemoryRecordSource} directly because its
+     * `list(filter?)` returns bare records (the ergonomic query surface) while the
+     * seam's `list()` returns scope-qualified records.
+     */
+    asRecordSource(): IMemoryRecordSource;
+    /**
+     * The EFFECTIVE {@link DedupScope} for `kind` — the granularity at which a
+     * write for this kind deduplicates against the existing vault.
+     *
+     * @remarks
+     * This is a **read accessor over the store's already-injected write policies**,
+     * and it is the single place any caller — the store's own write path included —
+     * asks what a kind's dedup granularity is. It resolves the full chain the store
+     * applies on write: the kind's registered {@link IWritePolicy}, falling back to
+     * the store's default policy, then that policy's
+     * {@link IWritePolicy.dedupScope | dedupScope}, falling back to
+     * {@link DEFAULT_DEDUP_SCOPE}. Note the store's default policy is a
+     * {@link KnowledgeLwwPolicy}, which declares `'content'` — so a kind with NO
+     * registered policy resolves to `'content'`, not to `DEFAULT_DEDUP_SCOPE`.
+     *
+     * It exists so a caller that must agree with the store about dedup granularity
+     * — notably the ingest orchestrator's stage-4 layer-1 exact match — can read the
+     * declaration through this seam instead of being handed a second copy of the
+     * policy map. A second declaration site is precisely the defect this accessor
+     * was added to remove.
+     *
+     * Deliberately synchronous, total, and NOT `Result`-returning: it reads
+     * constructor-injected configuration, touches no I/O, and cannot fail (every
+     * link in the fallback chain has a total default). It exposes only the scope,
+     * never the {@link IWritePolicy} itself, so it can never become a back door for
+     * invoking admission or merge logic out of band.
+     */
+    dedupScopeFor(kind: Kind): DedupScope;
+    /**
+     * Whether records of `kind` participate in the **record-granular** vector index.
+     *
+     * @remarks
+     * A read accessor over the store's injected {@link IFileTreeMemoryStoreCreateParams.embedKinds | embedKinds}
+     * declaration, in the same spirit as {@link IMemoryStore.dedupScopeFor} — one
+     * place to ask, so the store's write path and any caller reasoning about index
+     * coverage cannot disagree. `true` for every kind when no declaration was made.
+     *
+     * **This is distinct from a {@link MemoryEmbedder} decline, and the difference is
+     * cost.** An embedder that returns `undefined` has already been called: the
+     * round trip is paid, and on a locally-hosted model that round trip is the
+     * expense. A kind excluded here is never handed to the embedder at all. The
+     * decline makes the intent *expressible*; this makes it *free*.
+     *
+     * Deliberately synchronous, total, and NOT `Result`-returning: it reads
+     * constructor-injected configuration, touches no I/O, and cannot fail.
+     */
+    embedsKind(kind: Kind): boolean;
+    /**
+     * Write a record. Validates the body, computes a content hash, deduplicates
+     * (scope-wide, before policy), applies the kind's {@link IWritePolicy}, stamps
+     * transaction-time metadata (`created` / `updated` / `seq` / `contentHash`),
+     * writes the file, and patches the index. Returns the written record — or the
+     * existing record unchanged on a dedup no-op.
+     */
+    put(record: IMemoryRecord<unknown>): Promise<Result<IMemoryRecord<unknown>>>;
+    /**
+     * Repair one derived artifact for one {@link Kind} — **targeted and
+     * non-destructive**, unlike `IVectorIndex.rebuild`, which resets the index and
+     * re-embeds everything.
+     *
+     * @remarks
+     * The counterpart to {@link IMemoryStore.coverage}: coverage says **how big**
+     * the gap is and costs nothing; reconcile says **what it was** and closes what
+     * it can, at the cost of reading bodies and re-running the embedder. Neither
+     * substitutes for the other — in particular, only reconcile can distinguish a
+     * *declined* record from a *failed* one, because learning that requires calling
+     * the embedder again.
+     *
+     * **It only touches what is missing.** For the vector lanes it asks
+     * `has(target)` per record and skips the ones already held, so a repair after a
+     * brief outage costs a handful of embedder calls rather than a whole vault.
+     * That check is also the only way to see a record whose vector the index holds
+     * but whose envelope lost its `embeddingRef` — which needs a restamp and no
+     * embedder call at all, and which an `embeddingRef`-only repair cannot detect.
+     *
+     * **`artifact` is required and names one lane.** See {@link DerivedArtifact}
+     * for why an operation repairing "everything wired" would be the wrong shape.
+     *
+     * **A vector lane must be wired on BOTH halves — index *and* embedder — or this
+     * fails, and it is deliberately stricter than {@link IMemoryStore.coverage}.**
+     * The two ask different questions of the same wiring. Coverage asks *what does
+     * the index hold*, which an index alone can answer: an index wired without an
+     * embedder is a legal store (queries work; writes simply do not embed), so
+     * coverage reports that lane rather than pretending it is absent. Reconcile
+     * asks to *produce* vectors, which needs the embedder. So a half-wired store
+     * legitimately reports a coverage gap it cannot repair, and reconcile names the
+     * missing half rather than returning a cheerful success with every record in
+     * `failed`.
+     *
+     * Runs under the store's write lock, like any other mutation.
+     */
+    reconcile(kind: Kind, artifact: DerivedArtifact): Promise<Result<ReconcileReport>>;
+    /**
+     * Delete a record by `(kind, entityId)`. Non-temporal kinds physically delete
+     * the file and return the deleted record's {@link MemoryId}. Temporal
+     * (versioned) kinds SOFT-delete: the current version is invalidated
+     * (`invalid_at` set), history is retained, and the invalidated version's
+     * {@link MemoryId} is returned.
+     */
+    delete(kind: Kind, entityId: EntityId): Promise<Result<MemoryId>>;
+}
+//# sourceMappingURL=memoryStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memoryStore.d.ts","sourceRoot":"","sources":["../../../src/packlets/store/memoryStore.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EACL,UAAU,EACV,QAAQ,EACR,aAAa,EACb,qBAAqB,EACrB,IAAI,EACJ,QAAQ,EACR,cAAc,EACf,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAa,SAAQ,qBAAqB;IACzD;;;;;;;;OAQG;IACH,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;IAEzF;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;IAElG;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC,CAAC;IAEnD;;;;;;;;;;;;;OAaG;IACH,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAEnE;;;;;;;OAOG;IACH,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAElE;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,cAAc,IAAI,mBAAmB,CAAC;IAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,UAAU,CAAC;IAEtC;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;IAEhC;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC;IAEnF;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;CACnE"}

package/lib/packlets/store/memoryStore.js

@@ -0,0 +1,7 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=memoryStore.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memoryStore.js","sourceRoot":"","sources":["../../../src/packlets/store/memoryStore.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 {\n  DedupScope,\n  EntityId,\n  IMemoryRecord,\n  IMemoryRecordResolver,\n  Kind,\n  MemoryId,\n  MemoryScopeKey\n} from '../types';\nimport { IIndexedMemoryEntry } from '../index';\nimport { IMemoryRecordSource, IScopedMemoryRecord } from '../vector';\nimport { MemoryListSelection } from './listSelection';\nimport { IDerivedStateCoverage } from './coverage';\nimport { DerivedArtifact, ReconcileReport } from './reconcile';\n\n/**\n * The writable, FileTree-backed, content-hash-deduped memory store.\n *\n * @remarks\n * Extends {@link IMemoryRecordResolver} because the retrievers take a resolver\n * and a store is the obvious one to hand them — `{ index, resolver: store }` is\n * the documented wiring, and it has to type-check for the `IMemoryStore` handle\n * a consumer actually holds, not only for the concrete `FileTreeMemoryStore`.\n * @public\n */\nexport interface IMemoryStore extends IMemoryRecordResolver {\n  /**\n   * Keyed read by entity id. Resolves `entityId` to a storage address via the\n   * registered {@link IIdentityCodec} for `kind`. Returns `undefined` when no\n   * record exists. For a versioned (temporal) kind the current version is\n   * *selected* from the derived in-memory index — the version history is walked\n   * over envelopes, never bodies — and then that one version is read from\n   * storage. So the selection costs no file reads and the result costs exactly\n   * one, rather than one per version.\n   */\n  get(kind: Kind, entityId: EntityId): Promise<Result<IMemoryRecord<unknown> | undefined>>;\n\n  /**\n   * Direct read by `(scope, MemoryId)`. Returns `undefined` when not found.\n   */\n  getById(scope: MemoryScopeKey, id: MemoryId): Promise<Result<IMemoryRecord<unknown> | undefined>>;\n\n  /**\n   * List records: select over the derived index, then materialize the survivors.\n   *\n   * @remarks\n   * **The selection is required and must narrow.** Since the index holds\n   * envelopes only, every returned record is read from storage — so a call that\n   * narrows nothing reads the whole vault, and that has to be a decision rather\n   * than a default. Omitting the argument is a compile error; passing one with no\n   * `scope` / `kind` / `tag` fails with a message naming {@link scanEveryRecord},\n   * which is how a caller says it meant it.\n   *\n   * The requirement buys **explicitness, not a cost bound** — `{ kind }` on a\n   * vault dominated by that kind still materializes most of it. What it prevents\n   * is the whole-vault read nobody chose.\n   *\n   * If you only need to select, use {@link IMemoryStore.listEntries} instead: no\n   * selection, no file reads.\n   */\n  list(selection: MemoryListSelection): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;\n\n  /**\n   * How much of the store's **derived state** exists, resolved by {@link Kind}.\n   *\n   * @remarks\n   * Answers *\"is my derived state consistent with my records, and if not by how\n   * much?\"* for every artifact the store derives — `rank`, record vectors, and\n   * fragment vectors — in one call.\n   *\n   * **Cheap and total, by contract rather than by implementation.** Every input is\n   * an envelope field or an index-side count: it reads **no record bodies** and\n   * calls **no embedder**, and the walk over the vault's own state touches the\n   * filesystem not at all. That is why it takes no selection, unlike\n   * {@link IMemoryStore.list} — the guard there exists because an unnarrowed list\n   * reads the vault, and putting one here would decorate a free operation and make\n   * that guard mean less.\n   *\n   * **The index-side counts are the one exception, and it is the caller's own\n   * index that spends it.** A persistent index answers `size` / `recordCount` /\n   * `fragmentCount` with a query — `SqliteVecVectorIndex` runs a prepared `COUNT`\n   * — so on a durable backend this call does I/O and can **fail**. It is bounded\n   * (one count per wired index, never per record) and it is why the return is a\n   * `Result` rather than a bare value.\n   *\n   * *If a future addition to the report would require reading a record body, it\n   * does not belong on this report.*\n   *\n   * The counterpart is {@link IMemoryStore.reconcile}: coverage says **how big**\n   * the gap is, cheaply; reconcile says **what it was** and closes what it can, at\n   * the cost of re-running the embedder. Neither substitutes for the other.\n   *\n   * **A lane is reported here whenever its *index* is wired**, which is weaker\n   * than what reconcile requires (index **and** embedder). That is intended: an\n   * index without an embedder still holds vectors and still answers queries, so\n   * its coverage is a real number worth reporting. The consequence to expect is a\n   * half-wired store that reports a gap `reconcile` will refuse to close, naming\n   * the missing embedder.\n   */\n  coverage(): Promise<Result<IDerivedStateCoverage>>;\n\n  /**\n   * Every entry in the vault — scope and envelope, **no bodies**. Reads no files\n   * and requires no selection, because there is nothing to be careful about: it\n   * returns what the index already holds.\n   *\n   * @remarks\n   * This is the whole-vault read most callers actually want. Selection, grouping,\n   * counting, \"which kinds are in here\", \"what links at this\" — all of it is\n   * envelope work. Reach for {@link IMemoryStore.list} with\n   * {@link scanEveryRecord} only when you genuinely need every body.\n   *\n   * Synchronous in spirit but `Promise`-returning for consistency with the rest\n   * of the store surface.\n   */\n  listEntries(): Promise<Result<ReadonlyArray<IIndexedMemoryEntry>>>;\n\n  /**\n   * List EVERY record in the vault, each paired with its scope-qualified\n   * `(scope, id)` address — the projection {@link IMemoryRecordSource} requires.\n   * Unlike {@link IMemoryStore.list | list}, it takes no filter (whole-vault) and\n   * returns {@link IScopedMemoryRecord}s so a re-index keys each entry on the same\n   * scoped target the incremental embed-on-write path uses. Two records that share\n   * a filename stem across scopes appear as distinct entries.\n   */\n  listScoped(): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>>;\n\n  /**\n   * Adapt this store to the {@link IMemoryRecordSource} seam so it can drive\n   * {@link IVectorIndex} rebuilds (e.g. `InMemoryCosineIndex.rebuild`). The\n   * returned source's `list()` delegates to {@link IMemoryStore.listScoped},\n   * **filtered to the kinds {@link IMemoryStore.embedsKind | embedsKind} reports** —\n   * this source exists to feed the record vector index, so a kind excluded from\n   * that index is excluded here too, and a reopen does not re-embed records the\n   * index will never return. With no\n   * {@link IFileTreeMemoryStoreCreateParams.embedKinds | embedKinds} declaration\n   * every kind participates and the filter is the identity. `listScoped` itself is\n   * **not** filtered and remains the whole-vault surface.\n   *\n   * The filter also **counts what it drops**, onto\n   * {@link IMemoryRecordListing.excluded} — this is the layer where the exclusion\n   * decision is made and so the only one that can. The count is always present\n   * (empty when nothing was excluded).\n   *\n   * The store cannot implement {@link IMemoryRecordSource} directly because its\n   * `list(filter?)` returns bare records (the ergonomic query surface) while the\n   * seam's `list()` returns scope-qualified records.\n   */\n  asRecordSource(): IMemoryRecordSource;\n\n  /**\n   * The EFFECTIVE {@link DedupScope} for `kind` — the granularity at which a\n   * write for this kind deduplicates against the existing vault.\n   *\n   * @remarks\n   * This is a **read accessor over the store's already-injected write policies**,\n   * and it is the single place any caller — the store's own write path included —\n   * asks what a kind's dedup granularity is. It resolves the full chain the store\n   * applies on write: the kind's registered {@link IWritePolicy}, falling back to\n   * the store's default policy, then that policy's\n   * {@link IWritePolicy.dedupScope | dedupScope}, falling back to\n   * {@link DEFAULT_DEDUP_SCOPE}. Note the store's default policy is a\n   * {@link KnowledgeLwwPolicy}, which declares `'content'` — so a kind with NO\n   * registered policy resolves to `'content'`, not to `DEFAULT_DEDUP_SCOPE`.\n   *\n   * It exists so a caller that must agree with the store about dedup granularity\n   * — notably the ingest orchestrator's stage-4 layer-1 exact match — can read the\n   * declaration through this seam instead of being handed a second copy of the\n   * policy map. A second declaration site is precisely the defect this accessor\n   * was added to remove.\n   *\n   * Deliberately synchronous, total, and NOT `Result`-returning: it reads\n   * constructor-injected configuration, touches no I/O, and cannot fail (every\n   * link in the fallback chain has a total default). It exposes only the scope,\n   * never the {@link IWritePolicy} itself, so it can never become a back door for\n   * invoking admission or merge logic out of band.\n   */\n  dedupScopeFor(kind: Kind): DedupScope;\n\n  /**\n   * Whether records of `kind` participate in the **record-granular** vector index.\n   *\n   * @remarks\n   * A read accessor over the store's injected {@link IFileTreeMemoryStoreCreateParams.embedKinds | embedKinds}\n   * declaration, in the same spirit as {@link IMemoryStore.dedupScopeFor} — one\n   * place to ask, so the store's write path and any caller reasoning about index\n   * coverage cannot disagree. `true` for every kind when no declaration was made.\n   *\n   * **This is distinct from a {@link MemoryEmbedder} decline, and the difference is\n   * cost.** An embedder that returns `undefined` has already been called: the\n   * round trip is paid, and on a locally-hosted model that round trip is the\n   * expense. A kind excluded here is never handed to the embedder at all. The\n   * decline makes the intent *expressible*; this makes it *free*.\n   *\n   * Deliberately synchronous, total, and NOT `Result`-returning: it reads\n   * constructor-injected configuration, touches no I/O, and cannot fail.\n   */\n  embedsKind(kind: Kind): boolean;\n\n  /**\n   * Write a record. Validates the body, computes a content hash, deduplicates\n   * (scope-wide, before policy), applies the kind's {@link IWritePolicy}, stamps\n   * transaction-time metadata (`created` / `updated` / `seq` / `contentHash`),\n   * writes the file, and patches the index. Returns the written record — or the\n   * existing record unchanged on a dedup no-op.\n   */\n  put(record: IMemoryRecord<unknown>): Promise<Result<IMemoryRecord<unknown>>>;\n\n  /**\n   * Repair one derived artifact for one {@link Kind} — **targeted and\n   * non-destructive**, unlike `IVectorIndex.rebuild`, which resets the index and\n   * re-embeds everything.\n   *\n   * @remarks\n   * The counterpart to {@link IMemoryStore.coverage}: coverage says **how big**\n   * the gap is and costs nothing; reconcile says **what it was** and closes what\n   * it can, at the cost of reading bodies and re-running the embedder. Neither\n   * substitutes for the other — in particular, only reconcile can distinguish a\n   * *declined* record from a *failed* one, because learning that requires calling\n   * the embedder again.\n   *\n   * **It only touches what is missing.** For the vector lanes it asks\n   * `has(target)` per record and skips the ones already held, so a repair after a\n   * brief outage costs a handful of embedder calls rather than a whole vault.\n   * That check is also the only way to see a record whose vector the index holds\n   * but whose envelope lost its `embeddingRef` — which needs a restamp and no\n   * embedder call at all, and which an `embeddingRef`-only repair cannot detect.\n   *\n   * **`artifact` is required and names one lane.** See {@link DerivedArtifact}\n   * for why an operation repairing \"everything wired\" would be the wrong shape.\n   *\n   * **A vector lane must be wired on BOTH halves — index *and* embedder — or this\n   * fails, and it is deliberately stricter than {@link IMemoryStore.coverage}.**\n   * The two ask different questions of the same wiring. Coverage asks *what does\n   * the index hold*, which an index alone can answer: an index wired without an\n   * embedder is a legal store (queries work; writes simply do not embed), so\n   * coverage reports that lane rather than pretending it is absent. Reconcile\n   * asks to *produce* vectors, which needs the embedder. So a half-wired store\n   * legitimately reports a coverage gap it cannot repair, and reconcile names the\n   * missing half rather than returning a cheerful success with every record in\n   * `failed`.\n   *\n   * Runs under the store's write lock, like any other mutation.\n   */\n  reconcile(kind: Kind, artifact: DerivedArtifact): Promise<Result<ReconcileReport>>;\n\n  /**\n   * Delete a record by `(kind, entityId)`. Non-temporal kinds physically delete\n   * the file and return the deleted record's {@link MemoryId}. Temporal\n   * (versioned) kinds SOFT-delete: the current version is invalidated\n   * (`invalid_at` set), history is retained, and the invalidated version's\n   * {@link MemoryId} is returned.\n   */\n  delete(kind: Kind, entityId: EntityId): Promise<Result<MemoryId>>;\n}\n"]}

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

@@ -0,0 +1,82 @@
+import { Kind } from '../types';
+import { ISkippedVectorRecord } from '../vector';
+/**
+ * Which derived artifact a {@link IMemoryStore.reconcile} call repairs.
+ *
+ * @remarks
+ * **The operation names its artifact rather than repairing everything wired**,
+ * and the reasons are structural rather than stylistic: the record and fragment
+ * lanes are independently wirable (so an unnamed repair on a fragment-only store
+ * would have to no-op or guess), their units are incommensurable (one vector per
+ * record vs. N), and their costs differ by orders of magnitude — a measured case
+ * put 68 fragments behind a single 56 KB record. An operation whose cost varies
+ * that much along a dimension it does not name is the accidental-expense shape
+ * `IMemoryStore.list`'s required selection exists to prevent.
+ * @public
+ */
+export type DerivedArtifact = 'rank' | 'record-vector' | 'fragment-vector';
+/** What every reconcile reports, whatever the artifact. @public */
+export interface IReconcileReportBase {
+    /** The kind reconciled — named by the caller, so every count below is scalar. */
+    readonly kind: Kind;
+    /** Records of this kind considered. The denominator for everything else. */
+    readonly examined: number;
+    /** Records whose derived artifact was (re)produced by this call. */
+    readonly repaired: number;
+    /** Records that failed, with the error. A fault, never a decline. */
+    readonly failed: ReadonlyArray<ISkippedVectorRecord>;
+}
+/** A `rank` reconcile: re-run the projector and restamp what changed. @public */
+export interface IRankReconcileReport extends IReconcileReportBase {
+    readonly artifact: 'rank';
+}
+/**
+ * A record-vector reconcile.
+ * @public
+ */
+export interface IVectorReconcileReport extends IReconcileReportBase {
+    readonly artifact: 'record-vector';
+    /**
+     * Records the index already held and which needed **no embedder call** — the
+     * whole point of a targeted repair, and the number that shows what it saved
+     * against a `rebuild`.
+     */
+    readonly alreadyIndexed: number;
+    /**
+     * Records whose vector the index held but whose envelope had **lost its
+     * `embeddingRef`** — repaired by restamping the reference, with no embedder
+     * call.
+     *
+     * @remarks
+     * This case is invisible to an `embeddingRef`-only check, which is one of the
+     * two reasons `IVectorIndex.has` is on the contract: a reference-absent record
+     * looks identical to a never-embedded one until you ask the index.
+     */
+    readonly restamped: number;
+    /** Records the embedder intentionally declined. Not a failure, not a gap. */
+    readonly declined: number;
+}
+/**
+ * A fragment-vector reconcile.
+ *
+ * @remarks
+ * Note there is no `restamped`: the fragment lane has **no envelope marker**, so
+ * there is no reference that can go missing and nothing to restamp. The
+ * asymmetry with {@link IVectorReconcileReport} is real rather than an oversight.
+ * @public
+ */
+export interface IFragmentReconcileReport extends IReconcileReportBase {
+    readonly artifact: 'fragment-vector';
+    /** Records already represented, needing no embedder call. */
+    readonly alreadyIndexed: number;
+    /** Records whose embedder produced no fragments — this lane's decline. */
+    readonly declined: number;
+    /** Fragments written by this call — the fan-out `repaired` cannot express. */
+    readonly fragments: number;
+}
+/**
+ * What a {@link IMemoryStore.reconcile} established, discriminated by artifact.
+ * @public
+ */
+export type ReconcileReport = IRankReconcileReport | IVectorReconcileReport | IFragmentReconcileReport;
+//# sourceMappingURL=reconcile.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../../src/packlets/store/reconcile.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,eAAe,GAAG,iBAAiB,CAAC;AAE3E,mEAAmE;AACnE,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;CACtD;AAED,iFAAiF;AACjF,MAAM,WAAW,oBAAqB,SAAQ,oBAAoB;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,oBAAoB;IAClE,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,wBAAyB,SAAQ,oBAAoB;IACpE,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,oBAAoB,GAAG,sBAAsB,GAAG,wBAAwB,CAAC"}

package/lib/packlets/store/reconcile.js

@@ -0,0 +1,7 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=reconcile.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../../../src/packlets/store/reconcile.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Kind } from '../types';\nimport { ISkippedVectorRecord } from '../vector';\n\n/**\n * Which derived artifact a {@link IMemoryStore.reconcile} call repairs.\n *\n * @remarks\n * **The operation names its artifact rather than repairing everything wired**,\n * and the reasons are structural rather than stylistic: the record and fragment\n * lanes are independently wirable (so an unnamed repair on a fragment-only store\n * would have to no-op or guess), their units are incommensurable (one vector per\n * record vs. N), and their costs differ by orders of magnitude — a measured case\n * put 68 fragments behind a single 56 KB record. An operation whose cost varies\n * that much along a dimension it does not name is the accidental-expense shape\n * `IMemoryStore.list`'s required selection exists to prevent.\n * @public\n */\nexport type DerivedArtifact = 'rank' | 'record-vector' | 'fragment-vector';\n\n/** What every reconcile reports, whatever the artifact. @public */\nexport interface IReconcileReportBase {\n  /** The kind reconciled — named by the caller, so every count below is scalar. */\n  readonly kind: Kind;\n  /** Records of this kind considered. The denominator for everything else. */\n  readonly examined: number;\n  /** Records whose derived artifact was (re)produced by this call. */\n  readonly repaired: number;\n  /** Records that failed, with the error. A fault, never a decline. */\n  readonly failed: ReadonlyArray<ISkippedVectorRecord>;\n}\n\n/** A `rank` reconcile: re-run the projector and restamp what changed. @public */\nexport interface IRankReconcileReport extends IReconcileReportBase {\n  readonly artifact: 'rank';\n}\n\n/**\n * A record-vector reconcile.\n * @public\n */\nexport interface IVectorReconcileReport extends IReconcileReportBase {\n  readonly artifact: 'record-vector';\n  /**\n   * Records the index already held and which needed **no embedder call** — the\n   * whole point of a targeted repair, and the number that shows what it saved\n   * against a `rebuild`.\n   */\n  readonly alreadyIndexed: number;\n  /**\n   * Records whose vector the index held but whose envelope had **lost its\n   * `embeddingRef`** — repaired by restamping the reference, with no embedder\n   * call.\n   *\n   * @remarks\n   * This case is invisible to an `embeddingRef`-only check, which is one of the\n   * two reasons `IVectorIndex.has` is on the contract: a reference-absent record\n   * looks identical to a never-embedded one until you ask the index.\n   */\n  readonly restamped: number;\n  /** Records the embedder intentionally declined. Not a failure, not a gap. */\n  readonly declined: number;\n}\n\n/**\n * A fragment-vector reconcile.\n *\n * @remarks\n * Note there is no `restamped`: the fragment lane has **no envelope marker**, so\n * there is no reference that can go missing and nothing to restamp. The\n * asymmetry with {@link IVectorReconcileReport} is real rather than an oversight.\n * @public\n */\nexport interface IFragmentReconcileReport extends IReconcileReportBase {\n  readonly artifact: 'fragment-vector';\n  /** Records already represented, needing no embedder call. */\n  readonly alreadyIndexed: number;\n  /** Records whose embedder produced no fragments — this lane's decline. */\n  readonly declined: number;\n  /** Fragments written by this call — the fan-out `repaired` cannot express. */\n  readonly fragments: number;\n}\n\n/**\n * What a {@link IMemoryStore.reconcile} established, discriminated by artifact.\n * @public\n */\nexport type ReconcileReport = IRankReconcileReport | IVectorReconcileReport | IFragmentReconcileReport;\n"]}

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

@@ -0,0 +1,45 @@
+import { Result } from '@fgv/ts-utils';
+import { Kind } from '../types';
+import { IIndexedMemoryEntry } from '../index';
+import { IFragmentVectorIndex, IVectorIndex } from '../vector';
+import { IDerivedStateCoverage } from './coverage';
+/**
+ * Everything {@link computeCoverage} needs, supplied by the store.
+ *
+ * @remarks
+ * Taken as inputs rather than reading a store, so this module has no dependency
+ * on `FileTreeMemoryStore` and the walk is testable on its own. Package-internal:
+ * `IMemoryStore.coverage` is the published surface.
+ */
+export interface IComputeCoverageParams {
+    /** The projected index entries — envelopes only, already free of file reads. */
+    readonly entries: ReadonlyArray<IIndexedMemoryEntry>;
+    /** Whether `kind` has a registered rank projector. */
+    readonly hasRankProjector: (kind: Kind) => boolean;
+    /** Whether ANY kind has one — distinguishes an unwired lane from an empty one. */
+    readonly anyRankProjector: boolean;
+    /** Whether `kind` participates in the record-granular vector index. */
+    readonly embedsKind: (kind: Kind) => boolean;
+    /** The wired record-vector index, or `undefined` when the lane is unwired. */
+    readonly vectorIndex: IVectorIndex | undefined;
+    /** The wired fragment index, or `undefined` when the lane is unwired. */
+    readonly fragmentIndex: IFragmentVectorIndex | undefined;
+}
+/**
+ * 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.
+ */
+export declare function computeCoverage(params: IComputeCoverageParams): Result<IDerivedStateCoverage>;
+//# sourceMappingURL=storeCoverage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storeCoverage.d.ts","sourceRoot":"","sources":["../../../src/packlets/store/storeCoverage.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAA0B,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAkB,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAqB,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEtE;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IACrD,sDAAsD;IACtD,QAAQ,CAAC,gBAAgB,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;IACnD,kFAAkF;IAClF,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;IAC7C,8EAA8E;IAC9E,QAAQ,CAAC,WAAW,EAAE,YAAY,GAAG,SAAS,CAAC;IAC/C,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,oBAAoB,GAAG,SAAS,CAAC;CAC1D;AAkBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAkF7F"}