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

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

@@ -1,5 +1,5 @@
 import { Result } from '@fgv/ts-utils';
-import { IEdgeTarget, IMemoryRecord, Kind, MemoryScopeKey, Tag } from '../types';
+import { IEdgeTarget, IMemoryEnvelope, IMemoryRecord, Kind, MemoryScopeKey, Tag } from '../types';
 /**
  * The mutation a {@link IMemoryIndex.patch | patch} applies: a record was
  * written (`'put'`) or removed (`'delete'`).
@@ -21,6 +21,32 @@ export interface IIndexedMemoryRecord {
     /** The memory record itself. */
     readonly record: IMemoryRecord<unknown>;
 }
+/**
+ * What the index HOLDS and what every index read returns: a record's scope and
+ * its {@link IMemoryEnvelope}, and **no body**.
+ *
+ * @remarks
+ * The index is a derived *selection* structure, and selection has never needed a
+ * body — every filter the store and the retrievers apply reads envelope fields
+ * (`scope` / `kind` / `tags` / `contentHash` / `provenance` / `links` /
+ * `temporal` / `updated` / `seq` / `rank`). Returning whole records made every
+ * conforming index hold every body by construction, which was the store's
+ * resident-memory ceiling; returning envelopes removes it from the contract
+ * rather than from one implementation.
+ *
+ * A caller that needs the body **materializes it explicitly** — through
+ * {@link IMemoryStore.getById}, or an `IMemoryRecordResolver` where one is
+ * wired. That is deliberately visible: a lazy `body` getter would have kept
+ * every call site compiling while turning a memory read into a file read behind
+ * an unchanged type, which is a silent performance cliff rather than a migration.
+ * @public
+ */
+export interface IIndexedMemoryEntry {
+    /** The scope the record is stored under. */
+    readonly scope: MemoryScopeKey;
+    /** The record's envelope. No body — see the remarks. */
+    readonly envelope: IMemoryEnvelope;
+}
 /**
  * The derived, in-memory secondary indexes the store maintains over its
  * records. Never the source of truth — the FileTree is. The index is fully
@@ -28,40 +54,98 @@ export interface IIndexedMemoryRecord {
  * patched incrementally on every write ({@link IMemoryIndex.patch}).
  *
  * @remarks
- * B1 builds the maps; link-traversal BFS over {@link IMemoryIndex.backlinks}
- * is B2. The accessors return records (not bare ids) so the B2 retrievers can
- * consume them directly.
+ * Every read returns the projected {@link IIndexedMemoryEntry} — scope and
+ * envelope, no body. See that type for why.
+ *
+ * **The conformance rule: an index is a derived, COMPLETE, FAITHFUL projection
+ * of the vault.** An implementation may change *where* entries are stored and
+ * *how* they are looked up; it may not change *which* entries exist or *what any
+ * envelope says*. Concretely, {@link IMemoryIndex.entries} must return exactly
+ * one entry per record the store has written and not deleted, and each entry's
+ * envelope must be the one the store patched in.
+ *
+ * An index that filters, truncates, deduplicates, or synthesizes entries is not
+ * a conforming implementation, and the reason is not tidiness: **the store's
+ * write path derives from these reads** — content-hash dedup, write-policy
+ * admission cohorts, and temporal version histories all read the index. An index
+ * that hides an entry does not merely hide it from queries; it changes what the
+ * next write does. That is why the previous guidance said only a faithful
+ * delegating decorator was safe to inject. This invariant is what that guidance
+ * was reaching for, stated so that a genuinely different implementation (a
+ * SQLite-backed index, a lazily-paged one) is permitted while the reshaping that
+ * was the actual hazard stays out.
+ *
+ * **Ordering is NOT part of the contract.** {@link IMemoryIndex.entries} may
+ * return entries in any order and callers that need one sort explicitly. Note
+ * this is a *behavioural* freedom the compiler cannot police: the bundled
+ * {@link MemoryIndex} iterates a `Map` and so returns insertion order, which is
+ * stable and observable, so code that came to rely on it keeps compiling and
+ * changes results. The ordered accessors ({@link IMemoryIndex.byRecency},
+ * {@link IMemoryIndex.byRank}, and the recency-ordered `byKind` / `byTag`) are
+ * the supported way to ask for an order.
  * @public
  */
 export interface IMemoryIndex {
     /**
-     * Replace the entire index from a full set of records (a store walk).
-     * @returns The number of records indexed.
+     * Replace the entire index from a full set of entries (a store walk).
+     *
+     * @remarks
+     * Takes the **projected** {@link IIndexedMemoryEntry} form, not whole records,
+     * and the distinction is load-bearing rather than cosmetic: **`patch` writes,
+     * `rebuild` reads.** A rebuild is a whole-vault read that happens to terminate
+     * in the index, so requiring whole records here would force every caller — the
+     * store's own open path included — to materialize N bodies purely to feed a
+     * structure that projects the envelope back out and discards them. `patch`
+     * keeps whole records because it carries exactly one, which its caller already
+     * holds.
+     *
+     * @returns The number of entries indexed.
      */
-    rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number>;
+    rebuild(entries: ReadonlyArray<IIndexedMemoryEntry>): Result<number>;
     /**
      * Apply a single incremental change. `'put'` inserts or replaces the entry
      * at its `(scope, id)` key (removing any prior associations first); `'delete'`
      * removes it.
+     *
+     * @remarks
+     * Takes the whole record — see {@link IMemoryIndex.rebuild} for why this one
+     * does and that one does not. It costs nothing (the caller is mid-write and
+     * holds the record already) and it is the single point at which an index
+     * maintaining a body-derived view could observe content without a re-read.
+     * What is *held* is still only the projection.
+     *
      * @returns The entry that was applied.
      */
     patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord>;
-    /** Every indexed entry (scope + record). Primary read surface for the store. */
-    entries(): ReadonlyArray<IIndexedMemoryRecord>;
-    /** Records of the given kind, in recency order (most-recently-updated first). */
-    byKind(kind: Kind): ReadonlyArray<IMemoryRecord<unknown>>;
-    /** Records carrying the given tag, in recency order. */
-    byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>>;
-    /** All records in recency order (most-recently-updated first). */
-    byRecency(): ReadonlyArray<IMemoryRecord<unknown>>;
+    /** Every indexed entry (scope + envelope). Primary read surface for the store. */
+    entries(): ReadonlyArray<IIndexedMemoryEntry>;
     /**
-     * All records ordered by store-computed {@link IMemoryEnvelope.rank} descending,
-     * with recency (most-recently-updated, then `seq`) as a tiebreak. Records with
-     * an absent `rank` sort LAST (after every ranked record), then by recency among
+     * The entry at a scope-qualified address, or `undefined` if none.
+     *
+     * @remarks
+     * On the contract because its absence made every caller that wanted **one**
+     * entry rebuild a map of **all** of them: both `SemanticRetriever` (resolving
+     * at most `topK` hits) and `LinkTraversalRetriever` (resolving a BFS frontier)
+     * built a full-index `Map` per query for want of this. The index already keys
+     * on `(scope, id)` internally, so this exposes a lookup it was doing anyway.
+     */
+    get(target: IEdgeTarget): IIndexedMemoryEntry | undefined;
+    /** Entries of the given kind, in recency order (most-recently-updated first). */
+    byKind(kind: Kind): ReadonlyArray<IIndexedMemoryEntry>;
+    /** Entries carrying the given tag, in recency order. */
+    byTag(tag: Tag): ReadonlyArray<IIndexedMemoryEntry>;
+    /** All entries in recency order (most-recently-updated first). */
+    byRecency(): ReadonlyArray<IIndexedMemoryEntry>;
+    /**
+     * All entries ordered by store-computed {@link IMemoryEnvelope.rank} descending,
+     * with recency (most-recently-updated, then `seq`) as a tiebreak. Entries with
+     * an absent `rank` sort LAST (after every ranked entry), then by recency among
      * themselves. Serves a bounded top-M ({@link IMemoryEnvelope.rank}-ordered) page
-     * from the in-memory index with no full-vault (filesystem) scan.
+     * from the in-memory index with no full-vault (filesystem) scan — and since the
+     * page is envelope-only, a caller taking the top M materializes M bodies rather
+     * than the vault.
      */
-    byRank(): ReadonlyArray<IMemoryRecord<unknown>>;
+    byRank(): ReadonlyArray<IIndexedMemoryEntry>;
     /**
      * The scope-qualified sources of records whose `links` point AT `target`
      * (inbound edges), keyed on the target's `(scope, id)` address. The seed map
@@ -78,7 +162,10 @@ export interface IMemoryIndex {
  * @public
  */
 export declare class MemoryIndex implements IMemoryIndex {
-    /** Primary store: `(scope, id)` composite key → indexed entry. */
+    /**
+     * Primary store: `(scope, id)` composite key → indexed entry. Holds the
+     * PROJECTED form, so the index never retains a body.
+     */
     private readonly _byKey;
     /** kind → set of composite keys. */
     private readonly _byKind;
@@ -105,19 +192,21 @@ export declare class MemoryIndex implements IMemoryIndex {
      */
     private static _keyOf;
     /** {@inheritDoc IMemoryIndex.rebuild} */
-    rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number>;
+    rebuild(entries: ReadonlyArray<IIndexedMemoryEntry>): Result<number>;
     /** {@inheritDoc IMemoryIndex.patch} */
     patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord>;
     /** {@inheritDoc IMemoryIndex.entries} */
-    entries(): ReadonlyArray<IIndexedMemoryRecord>;
+    entries(): ReadonlyArray<IIndexedMemoryEntry>;
+    /** {@inheritDoc IMemoryIndex.get} */
+    get(target: IEdgeTarget): IIndexedMemoryEntry | undefined;
     /** {@inheritDoc IMemoryIndex.byKind} */
-    byKind(kind: Kind): ReadonlyArray<IMemoryRecord<unknown>>;
+    byKind(kind: Kind): ReadonlyArray<IIndexedMemoryEntry>;
     /** {@inheritDoc IMemoryIndex.byTag} */
-    byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>>;
+    byTag(tag: Tag): ReadonlyArray<IIndexedMemoryEntry>;
     /** {@inheritDoc IMemoryIndex.byRecency} */
-    byRecency(): ReadonlyArray<IMemoryRecord<unknown>>;
+    byRecency(): ReadonlyArray<IIndexedMemoryEntry>;
     /** {@inheritDoc IMemoryIndex.byRank} */
-    byRank(): ReadonlyArray<IMemoryRecord<unknown>>;
+    byRank(): ReadonlyArray<IIndexedMemoryEntry>;
     /** {@inheritDoc IMemoryIndex.backlinks} */
     backlinks(target: IEdgeTarget): ReadonlyArray<IEdgeTarget>;
     /**
@@ -135,6 +224,8 @@ export declare class MemoryIndex implements IMemoryIndex {
      * approach; the sort is over the in-memory index, never a filesystem walk.
      */
     private _rankOrdered;
+    /** Resolve composite keys to their entries, skipping any that are absent. */
+    private static _resolve;
     /**
      * Rank-descending comparator with an absent-`rank`-last rule and a recency
      * (`updated`, then `seq`) tiebreak. Duplicated from the retrieve packlet's

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

@@ -1 +1 @@
-{"version":3,"file":"memoryIndex.d.ts","sourceRoot":"","sources":["../../../src/packlets/index/memoryIndex.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"memoryIndex.d.ts","sourceRoot":"","sources":["../../../src/packlets/index/memoryIndex.ts"],"names":[],"mappings":"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"}

package/lib/packlets/index/memoryIndex.js

@@ -9,6 +9,10 @@ const ts_utils_1 = require("@fgv/ts-utils");
 const types_1 = require("../types");
 /** Shared empty key set for `byKind` / `byTag` misses (avoids per-call allocation). */
 const EMPTY_KEY_SET = new Set();
+/** Project the write-side whole-record form onto the held/read entry form. */
+function toEntry(entry) {
+    return { scope: entry.scope, envelope: entry.record.envelope };
+}
 /**
  * Default in-memory {@link IMemoryIndex}. Maintains the derived `byKind` /
  * `byTag` / `byRecency` / `backlinks` views incrementally; a `'put'` for an
@@ -54,7 +58,9 @@ class MemoryIndex {
         // changes kind/tags/links cannot strand a stale reference.
         this._remove(key);
         if (op === 'put') {
-            this._add(entry);
+            // Projected on the way in: the caller's record is used for its envelope and
+            // the body is not retained.
+            this._add(toEntry(entry));
         }
         return (0, ts_utils_1.succeed)(entry);
     }
@@ -62,6 +68,10 @@ class MemoryIndex {
     entries() {
         return Array.from(this._byKey.values());
     }
+    /** {@inheritDoc IMemoryIndex.get} */
+    get(target) {
+        return this._byKey.get((0, types_1.edgeTargetKey)(target));
+    }
     /** {@inheritDoc IMemoryIndex.byKind} */
     byKind(kind) {
         var _a;
@@ -91,14 +101,7 @@ class MemoryIndex {
      * records sort deterministically).
      */
     _recencyOrdered(keys) {
-        const records = [];
-        for (const key of keys) {
-            const entry = this._byKey.get(key);
-            if (entry !== undefined) {
-                records.push(entry.record);
-            }
-        }
-        return records.sort((a, b) => {
+        return MemoryIndex._resolve(this._byKey, keys).sort((a, b) => {
             const byUpdated = b.envelope.updated - a.envelope.updated;
             return byUpdated !== 0 ? byUpdated : b.envelope.seq - a.envelope.seq;
         });
@@ -112,14 +115,18 @@ class MemoryIndex {
      * approach; the sort is over the in-memory index, never a filesystem walk.
      */
     _rankOrdered(keys) {
-        const records = [];
+        return MemoryIndex._resolve(this._byKey, keys).sort(MemoryIndex._compareByRank);
+    }
+    /** Resolve composite keys to their entries, skipping any that are absent. */
+    static _resolve(byKey, keys) {
+        const entries = [];
         for (const key of keys) {
-            const entry = this._byKey.get(key);
+            const entry = byKey.get(key);
             if (entry !== undefined) {
-                records.push(entry.record);
+                entries.push(entry);
             }
         }
-        return records.sort(MemoryIndex._compareByRank);
+        return entries;
     }
     /**
      * Rank-descending comparator with an absent-`rank`-last rule and a recency
@@ -146,8 +153,8 @@ class MemoryIndex {
     }
     /** Insert an entry and register all its derived associations. */
     _add(entry) {
-        const key = MemoryIndex._keyOf(entry.scope, entry.record.envelope.id);
-        const envelope = entry.record.envelope;
+        const key = MemoryIndex._keyOf(entry.scope, entry.envelope.id);
+        const envelope = entry.envelope;
         this._byKey.set(key, entry);
         this._addToSetMap(this._byKind, envelope.kind, key);
         for (const tag of envelope.tags) {
@@ -163,7 +170,7 @@ class MemoryIndex {
         if (entry === undefined) {
             return;
         }
-        const envelope = entry.record.envelope;
+        const envelope = entry.envelope;
         this._byKey.delete(key);
         this._removeFromSetMap(this._byKind, envelope.kind, key);
         for (const tag of envelope.tags) {

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

@@ -1 +1 @@
-{"version":3,"file":"memoryIndex.js","sourceRoot":"","sources":["../../../src/packlets/index/memoryIndex.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, succeed } from '@fgv/ts-utils';\nimport { IEdgeTarget, IMemoryRecord, Kind, MemoryId, MemoryScopeKey, Tag, edgeTargetKey } from '../types';\n\n/**\n * The mutation a {@link IMemoryIndex.patch | patch} applies: a record was\n * written (`'put'`) or removed (`'delete'`).\n * @public\n */\nexport type MemoryIndexPatchOp = 'put' | 'delete';\n\n/** Shared empty key set for `byKind` / `byTag` misses (avoids per-call allocation). */\nconst EMPTY_KEY_SET: ReadonlySet<string> = new Set<string>();\n\n/**\n * A memory record paired with the {@link MemoryScopeKey | scope} it lives\n * under. The scope is not carried on the {@link IMemoryEnvelope} (it is derived\n * from the entity id by the codec), so the store threads it alongside the\n * record when patching or rebuilding the index. The `(scope, id)` pair is the\n * index's primary key, keeping records distinct across scopes that reuse a\n * filename stem (e.g. `turn-0` under different conversations in Phase C).\n * @public\n */\nexport interface IIndexedMemoryRecord {\n  /** The scope the record is stored under. */\n  readonly scope: MemoryScopeKey;\n  /** The memory record itself. */\n  readonly record: IMemoryRecord<unknown>;\n}\n\n/**\n * The derived, in-memory secondary indexes the store maintains over its\n * records. Never the source of truth — the FileTree is. The index is fully\n * rebuildable from a walk of the store ({@link IMemoryIndex.rebuild}) and is\n * patched incrementally on every write ({@link IMemoryIndex.patch}).\n *\n * @remarks\n * B1 builds the maps; link-traversal BFS over {@link IMemoryIndex.backlinks}\n * is B2. The accessors return records (not bare ids) so the B2 retrievers can\n * consume them directly.\n * @public\n */\nexport interface IMemoryIndex {\n  /**\n   * Replace the entire index from a full set of records (a store walk).\n   * @returns The number of records indexed.\n   */\n  rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number>;\n\n  /**\n   * Apply a single incremental change. `'put'` inserts or replaces the entry\n   * at its `(scope, id)` key (removing any prior associations first); `'delete'`\n   * removes it.\n   * @returns The entry that was applied.\n   */\n  patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord>;\n\n  /** Every indexed entry (scope + record). Primary read surface for the store. */\n  entries(): ReadonlyArray<IIndexedMemoryRecord>;\n\n  /** Records of the given kind, in recency order (most-recently-updated first). */\n  byKind(kind: Kind): ReadonlyArray<IMemoryRecord<unknown>>;\n\n  /** Records carrying the given tag, in recency order. */\n  byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>>;\n\n  /** All records in recency order (most-recently-updated first). */\n  byRecency(): ReadonlyArray<IMemoryRecord<unknown>>;\n\n  /**\n   * All records ordered by store-computed {@link IMemoryEnvelope.rank} descending,\n   * with recency (most-recently-updated, then `seq`) as a tiebreak. Records with\n   * an absent `rank` sort LAST (after every ranked record), then by recency among\n   * themselves. Serves a bounded top-M ({@link IMemoryEnvelope.rank}-ordered) page\n   * from the in-memory index with no full-vault (filesystem) scan.\n   */\n  byRank(): ReadonlyArray<IMemoryRecord<unknown>>;\n\n  /**\n   * The scope-qualified sources of records whose `links` point AT `target`\n   * (inbound edges), keyed on the target's `(scope, id)` address. The seed map\n   * for B2 link-traversal; results are {@link IEdgeTarget}s so a caller can feed\n   * them straight back in as further traversal seeds.\n   */\n  backlinks(target: IEdgeTarget): ReadonlyArray<IEdgeTarget>;\n}\n\n/**\n * Default in-memory {@link IMemoryIndex}. Maintains the derived `byKind` /\n * `byTag` / `byRecency` / `backlinks` views incrementally; a `'put'` for an\n * already-indexed key first removes the prior entry's associations so a changed\n * kind / tag / link set never leaves a stale reference behind.\n * @public\n */\nexport class MemoryIndex implements IMemoryIndex {\n  /** Primary store: `(scope, id)` composite key → indexed entry. */\n  private readonly _byKey: Map<string, IIndexedMemoryRecord>;\n  /** kind → set of composite keys. */\n  private readonly _byKind: Map<Kind, Set<string>>;\n  /** tag → set of composite keys. */\n  private readonly _byTag: Map<Tag, Set<string>>;\n  /**\n   * canonical target key (`edgeTargetKey`) → (source composite key → source\n   * {@link IEdgeTarget}). The OUTER map is keyed on the scope-qualified target's\n   * canonical `(scope, id)` string — NOT the target's bare id — so an edge to\n   * `turn-3` in one conversation is tracked separately from `turn-3` in another.\n   * The INNER map is keyed by the source's `(scope, id)` composite so two distinct\n   * source records that share an id across scopes are tracked independently and\n   * removing one never drops the other's edge.\n   */\n  private readonly _backlinks: Map<string, Map<string, IEdgeTarget>>;\n\n  private constructor() {\n    this._byKey = new Map<string, IIndexedMemoryRecord>();\n    this._byKind = new Map<Kind, Set<string>>();\n    this._byTag = new Map<Tag, Set<string>>();\n    this._backlinks = new Map<string, Map<string, IEdgeTarget>>();\n  }\n\n  /** Family-convention factory. */\n  public static create(): Result<MemoryIndex> {\n    return succeed(new MemoryIndex());\n  }\n\n  /**\n   * The composite primary key for an entry: scope + id, NUL-separated. NUL\n   * is excluded from both components (scope segments pass\n   * `assertPortableFilenameStem`; `MemoryId` is portable-filename-safe), so it\n   * is a collision-proof separator across every scope/id pair the codecs produce.\n   */\n  private static _keyOf(scope: MemoryScopeKey, id: MemoryId): string {\n    return edgeTargetKey({ scope, id });\n  }\n\n  /** {@inheritDoc IMemoryIndex.rebuild} */\n  public rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number> {\n    this._byKey.clear();\n    this._byKind.clear();\n    this._byTag.clear();\n    this._backlinks.clear();\n    for (const entry of entries) {\n      this._add(entry);\n    }\n    return succeed(this._byKey.size);\n  }\n\n  /** {@inheritDoc IMemoryIndex.patch} */\n  public patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord> {\n    const key: string = MemoryIndex._keyOf(entry.scope, entry.record.envelope.id);\n    // Always drop any prior associations for this key first, so a 'put' that\n    // changes kind/tags/links cannot strand a stale reference.\n    this._remove(key);\n    if (op === 'put') {\n      this._add(entry);\n    }\n    return succeed(entry);\n  }\n\n  /** {@inheritDoc IMemoryIndex.entries} */\n  public entries(): ReadonlyArray<IIndexedMemoryRecord> {\n    return Array.from(this._byKey.values());\n  }\n\n  /** {@inheritDoc IMemoryIndex.byKind} */\n  public byKind(kind: Kind): ReadonlyArray<IMemoryRecord<unknown>> {\n    return this._recencyOrdered(this._byKind.get(kind) ?? EMPTY_KEY_SET);\n  }\n\n  /** {@inheritDoc IMemoryIndex.byTag} */\n  public byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>> {\n    return this._recencyOrdered(this._byTag.get(tag) ?? EMPTY_KEY_SET);\n  }\n\n  /** {@inheritDoc IMemoryIndex.byRecency} */\n  public byRecency(): ReadonlyArray<IMemoryRecord<unknown>> {\n    return this._recencyOrdered(this._byKey.keys());\n  }\n\n  /** {@inheritDoc IMemoryIndex.byRank} */\n  public byRank(): ReadonlyArray<IMemoryRecord<unknown>> {\n    return this._rankOrdered(this._byKey.keys());\n  }\n\n  /** {@inheritDoc IMemoryIndex.backlinks} */\n  public backlinks(target: IEdgeTarget): ReadonlyArray<IEdgeTarget> {\n    const sources: Map<string, IEdgeTarget> | undefined = this._backlinks.get(edgeTargetKey(target));\n    return sources === undefined ? [] : Array.from(sources.values());\n  }\n\n  /**\n   * Resolve a set of composite keys to their records, ordered\n   * most-recently-updated first (with a `seq` tiebreak so equal-`updated`\n   * records sort deterministically).\n   */\n  private _recencyOrdered(keys: Iterable<string>): ReadonlyArray<IMemoryRecord<unknown>> {\n    const records: IMemoryRecord<unknown>[] = [];\n    for (const key of keys) {\n      const entry: IIndexedMemoryRecord | undefined = this._byKey.get(key);\n      if (entry !== undefined) {\n        records.push(entry.record);\n      }\n    }\n    return records.sort((a, b) => {\n      const byUpdated: number = b.envelope.updated - a.envelope.updated;\n      return byUpdated !== 0 ? byUpdated : b.envelope.seq - a.envelope.seq;\n    });\n  }\n\n  /**\n   * Resolve a set of composite keys to their records, ordered by\n   * {@link IMemoryEnvelope.rank} descending with recency (`updated`, then `seq`)\n   * as the tiebreak. Records with an absent `rank` sort LAST, then by recency\n   * among themselves. Computed on call (mirrors {@link MemoryIndex._recencyOrdered}) —\n   * no incremental rank-ordered view is maintained, matching the recency view's\n   * approach; the sort is over the in-memory index, never a filesystem walk.\n   */\n  private _rankOrdered(keys: Iterable<string>): ReadonlyArray<IMemoryRecord<unknown>> {\n    const records: IMemoryRecord<unknown>[] = [];\n    for (const key of keys) {\n      const entry: IIndexedMemoryRecord | undefined = this._byKey.get(key);\n      if (entry !== undefined) {\n        records.push(entry.record);\n      }\n    }\n    return records.sort(MemoryIndex._compareByRank);\n  }\n\n  /**\n   * Rank-descending comparator with an absent-`rank`-last rule and a recency\n   * (`updated`, then `seq`) tiebreak. Duplicated from the retrieve packlet's\n   * `rankCompare` deliberately: the index must not depend on `retrieve` (that\n   * package depends on the index), mirroring how `_recencyOrdered` inlines the\n   * recency ordering rather than importing `recencyCompare`.\n   */\n  private static _compareByRank(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number {\n    const ra: number | undefined = a.envelope.rank;\n    const rb: number | undefined = b.envelope.rank;\n    // Absent rank sorts last; two absent ranks fall through to the recency tiebreak.\n    if (ra === undefined && rb !== undefined) {\n      return 1;\n    }\n    if (rb === undefined && ra !== undefined) {\n      return -1;\n    }\n    if (ra !== undefined && rb !== undefined && ra !== rb) {\n      return rb - ra;\n    }\n    const byUpdated: number = b.envelope.updated - a.envelope.updated;\n    return byUpdated !== 0 ? byUpdated : b.envelope.seq - a.envelope.seq;\n  }\n\n  /** Insert an entry and register all its derived associations. */\n  private _add(entry: IIndexedMemoryRecord): void {\n    const key: string = MemoryIndex._keyOf(entry.scope, entry.record.envelope.id);\n    const envelope: IMemoryRecord<unknown>['envelope'] = entry.record.envelope;\n    this._byKey.set(key, entry);\n    this._addToSetMap(this._byKind, envelope.kind, key);\n    for (const tag of envelope.tags) {\n      this._addToSetMap(this._byTag, tag, key);\n    }\n    for (const edge of envelope.links) {\n      this._addBacklink(edge.target, key, { scope: entry.scope, id: envelope.id });\n    }\n  }\n\n  /** Remove the entry at `key` (if present) and all its derived associations. */\n  private _remove(key: string): void {\n    const entry: IIndexedMemoryRecord | undefined = this._byKey.get(key);\n    if (entry === undefined) {\n      return;\n    }\n    const envelope: IMemoryRecord<unknown>['envelope'] = entry.record.envelope;\n    this._byKey.delete(key);\n    this._removeFromSetMap(this._byKind, envelope.kind, key);\n    for (const tag of envelope.tags) {\n      this._removeFromSetMap(this._byTag, tag, key);\n    }\n    for (const edge of envelope.links) {\n      this._removeBacklink(edge.target, key);\n    }\n  }\n\n  /** Register `source` (keyed by its composite `sourceKey`) as linking at `target`. */\n  private _addBacklink(target: IEdgeTarget, sourceKey: string, source: IEdgeTarget): void {\n    const targetKey: string = edgeTargetKey(target);\n    const existing: Map<string, IEdgeTarget> | undefined = this._backlinks.get(targetKey);\n    if (existing === undefined) {\n      this._backlinks.set(targetKey, new Map<string, IEdgeTarget>([[sourceKey, source]]));\n    } else {\n      existing.set(sourceKey, source);\n    }\n  }\n\n  /** Drop the backlink from `sourceKey` to `target`, removing the target map when empty. */\n  private _removeBacklink(target: IEdgeTarget, sourceKey: string): void {\n    const targetKey: string = edgeTargetKey(target);\n    const existing: Map<string, IEdgeTarget> | undefined = this._backlinks.get(targetKey);\n    if (existing === undefined) {\n      return;\n    }\n    existing.delete(sourceKey);\n    if (existing.size === 0) {\n      this._backlinks.delete(targetKey);\n    }\n  }\n\n  /** Add `member` to the set at `mapKey`, creating the set on first use. */\n  private _addToSetMap<K, M>(map: Map<K, Set<M>>, mapKey: K, member: M): void {\n    const existing: Set<M> | undefined = map.get(mapKey);\n    if (existing === undefined) {\n      map.set(mapKey, new Set<M>([member]));\n    } else {\n      existing.add(member);\n    }\n  }\n\n  /** Remove `member` from the set at `mapKey`, dropping the set when empty. */\n  private _removeFromSetMap<K, M>(map: Map<K, Set<M>>, mapKey: K, member: M): void {\n    const existing: Set<M> | undefined = map.get(mapKey);\n    if (existing === undefined) {\n      return;\n    }\n    existing.delete(member);\n    if (existing.size === 0) {\n      map.delete(mapKey);\n    }\n  }\n}\n"]}
+{"version":3,"file":"memoryIndex.js","sourceRoot":"","sources":["../../../src/packlets/index/memoryIndex.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,4CAAgD;AAChD,oCASkB;AASlB,uFAAuF;AACvF,MAAM,aAAa,GAAwB,IAAI,GAAG,EAAU,CAAC;AA6C7D,8EAA8E;AAC9E,SAAS,OAAO,CAAC,KAA2B;IAC1C,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;AACjE,CAAC;AAsHD;;;;;;GAMG;AACH,MAAa,WAAW;IAqBtB;QACE,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,EAA+B,CAAC;QACrD,IAAI,CAAC,OAAO,GAAG,IAAI,GAAG,EAAqB,CAAC;QAC5C,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;QAC1C,IAAI,CAAC,UAAU,GAAG,IAAI,GAAG,EAAoC,CAAC;IAChE,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM;QAClB,OAAO,IAAA,kBAAO,EAAC,IAAI,WAAW,EAAE,CAAC,CAAC;IACpC,CAAC;IAED;;;;;OAKG;IACK,MAAM,CAAC,MAAM,CAAC,KAAqB,EAAE,EAAY;QACvD,OAAO,IAAA,qBAAa,EAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,yCAAyC;IAClC,OAAO,CAAC,OAA2C;QACxD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnB,CAAC;QACD,OAAO,IAAA,kBAAO,EAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,uCAAuC;IAChC,KAAK,CAAC,EAAsB,EAAE,KAA2B;QAC9D,MAAM,GAAG,GAAW,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC9E,yEAAyE;QACzE,2DAA2D;QAC3D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAClB,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC;YACjB,4EAA4E;YAC5E,4BAA4B;YAC5B,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5B,CAAC;QACD,OAAO,IAAA,kBAAO,EAAC,KAAK,CAAC,CAAC;IACxB,CAAC;IAED,yCAAyC;IAClC,OAAO;QACZ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,qCAAqC;IAC9B,GAAG,CAAC,MAAmB;QAC5B,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAA,qBAAa,EAAC,MAAM,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,wCAAwC;IACjC,MAAM,CAAC,IAAU;;QACtB,OAAO,IAAI,CAAC,eAAe,CAAC,MAAA,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,mCAAI,aAAa,CAAC,CAAC;IACvE,CAAC;IAED,uCAAuC;IAChC,KAAK,CAAC,GAAQ;;QACnB,OAAO,IAAI,CAAC,eAAe,CAAC,MAAA,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,mCAAI,aAAa,CAAC,CAAC;IACrE,CAAC;IAED,2CAA2C;IACpC,SAAS;QACd,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,wCAAwC;IACjC,MAAM;QACX,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,2CAA2C;IACpC,SAAS,CAAC,MAAmB;QAClC,MAAM,OAAO,GAAyC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAA,qBAAa,EAAC,MAAM,CAAC,CAAC,CAAC;QACjG,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACnE,CAAC;IAED;;;;OAIG;IACK,eAAe,CAAC,IAAsB;QAC5C,OAAO,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YAC3D,MAAM,SAAS,GAAW,CAAC,CAAC,QAAQ,CAAC,OAAO,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;YAClE,OAAO,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;QACvE,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACK,YAAY,CAAC,IAAsB;QACzC,OAAO,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC;IAClF,CAAC;IAED,6EAA6E;IACrE,MAAM,CAAC,QAAQ,CACrB,KAA+C,EAC/C,IAAsB;QAEtB,MAAM,OAAO,GAA0B,EAAE,CAAC;QAC1C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,KAAK,GAAoC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC9D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;;OAMG;IACK,MAAM,CAAC,cAAc,CAAC,CAAsB,EAAE,CAAsB;QAC1E,MAAM,EAAE,GAAuB,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC/C,MAAM,EAAE,GAAuB,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC/C,iFAAiF;QACjF,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;YACzC,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;YACzC,OAAO,CAAC,CAAC,CAAC;QACZ,CAAC;QACD,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACtD,OAAO,EAAE,GAAG,EAAE,CAAC;QACjB,CAAC;QACD,MAAM,SAAS,GAAW,CAAC,CAAC,QAAQ,CAAC,OAAO,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;QAClE,OAAO,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;IACvE,CAAC;IAED,iEAAiE;IACzD,IAAI,CAAC,KAA0B;QACrC,MAAM,GAAG,GAAW,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QACvE,MAAM,QAAQ,GAAoB,KAAK,CAAC,QAAQ,CAAC;QACjD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC5B,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACpD,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;YAChC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAC3C,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YAClC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;IAED,+EAA+E;IACvE,OAAO,CAAC,GAAW;QACzB,MAAM,KAAK,GAAoC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACpE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO;QACT,CAAC;QACD,MAAM,QAAQ,GAAoB,KAAK,CAAC,QAAQ,CAAC;QACjD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACzD,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;YAChC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAChD,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YAClC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,qFAAqF;IAC7E,YAAY,CAAC,MAAmB,EAAE,SAAiB,EAAE,MAAmB;QAC9E,MAAM,SAAS,GAAW,IAAA,qBAAa,EAAC,MAAM,CAAC,CAAC;QAChD,MAAM,QAAQ,GAAyC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACtF,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,GAAG,CAAsB,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QACtF,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,0FAA0F;IAClF,eAAe,CAAC,MAAmB,EAAE,SAAiB;QAC5D,MAAM,SAAS,GAAW,IAAA,qBAAa,EAAC,MAAM,CAAC,CAAC;QAChD,MAAM,QAAQ,GAAyC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACtF,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO;QACT,CAAC;QACD,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC3B,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,0EAA0E;IAClE,YAAY,CAAO,GAAmB,EAAE,MAAS,EAAE,MAAS;QAClE,MAAM,QAAQ,GAAuB,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,CAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACxC,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,6EAA6E;IACrE,iBAAiB,CAAO,GAAmB,EAAE,MAAS,EAAE,MAAS;QACvE,MAAM,QAAQ,GAAuB,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO;QACT,CAAC;QACD,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACxB,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACxB,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;CACF;AApPD,kCAoPC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, succeed } from '@fgv/ts-utils';\nimport {\n  IEdgeTarget,\n  IMemoryEnvelope,\n  IMemoryRecord,\n  Kind,\n  MemoryId,\n  MemoryScopeKey,\n  Tag,\n  edgeTargetKey\n} from '../types';\n\n/**\n * The mutation a {@link IMemoryIndex.patch | patch} applies: a record was\n * written (`'put'`) or removed (`'delete'`).\n * @public\n */\nexport type MemoryIndexPatchOp = 'put' | 'delete';\n\n/** Shared empty key set for `byKind` / `byTag` misses (avoids per-call allocation). */\nconst EMPTY_KEY_SET: ReadonlySet<string> = new Set<string>();\n\n/**\n * A memory record paired with the {@link MemoryScopeKey | scope} it lives\n * under. The scope is not carried on the {@link IMemoryEnvelope} (it is derived\n * from the entity id by the codec), so the store threads it alongside the\n * record when patching or rebuilding the index. The `(scope, id)` pair is the\n * index's primary key, keeping records distinct across scopes that reuse a\n * filename stem (e.g. `turn-0` under different conversations in Phase C).\n * @public\n */\nexport interface IIndexedMemoryRecord {\n  /** The scope the record is stored under. */\n  readonly scope: MemoryScopeKey;\n  /** The memory record itself. */\n  readonly record: IMemoryRecord<unknown>;\n}\n\n/**\n * What the index HOLDS and what every index read returns: a record's scope and\n * its {@link IMemoryEnvelope}, and **no body**.\n *\n * @remarks\n * The index is a derived *selection* structure, and selection has never needed a\n * body — every filter the store and the retrievers apply reads envelope fields\n * (`scope` / `kind` / `tags` / `contentHash` / `provenance` / `links` /\n * `temporal` / `updated` / `seq` / `rank`). Returning whole records made every\n * conforming index hold every body by construction, which was the store's\n * resident-memory ceiling; returning envelopes removes it from the contract\n * rather than from one implementation.\n *\n * A caller that needs the body **materializes it explicitly** — through\n * {@link IMemoryStore.getById}, or an `IMemoryRecordResolver` where one is\n * wired. That is deliberately visible: a lazy `body` getter would have kept\n * every call site compiling while turning a memory read into a file read behind\n * an unchanged type, which is a silent performance cliff rather than a migration.\n * @public\n */\nexport interface IIndexedMemoryEntry {\n  /** The scope the record is stored under. */\n  readonly scope: MemoryScopeKey;\n  /** The record's envelope. No body — see the remarks. */\n  readonly envelope: IMemoryEnvelope;\n}\n\n/** Project the write-side whole-record form onto the held/read entry form. */\nfunction toEntry(entry: IIndexedMemoryRecord): IIndexedMemoryEntry {\n  return { scope: entry.scope, envelope: entry.record.envelope };\n}\n\n/**\n * The derived, in-memory secondary indexes the store maintains over its\n * records. Never the source of truth — the FileTree is. The index is fully\n * rebuildable from a walk of the store ({@link IMemoryIndex.rebuild}) and is\n * patched incrementally on every write ({@link IMemoryIndex.patch}).\n *\n * @remarks\n * Every read returns the projected {@link IIndexedMemoryEntry} — scope and\n * envelope, no body. See that type for why.\n *\n * **The conformance rule: an index is a derived, COMPLETE, FAITHFUL projection\n * of the vault.** An implementation may change *where* entries are stored and\n * *how* they are looked up; it may not change *which* entries exist or *what any\n * envelope says*. Concretely, {@link IMemoryIndex.entries} must return exactly\n * one entry per record the store has written and not deleted, and each entry's\n * envelope must be the one the store patched in.\n *\n * An index that filters, truncates, deduplicates, or synthesizes entries is not\n * a conforming implementation, and the reason is not tidiness: **the store's\n * write path derives from these reads** — content-hash dedup, write-policy\n * admission cohorts, and temporal version histories all read the index. An index\n * that hides an entry does not merely hide it from queries; it changes what the\n * next write does. That is why the previous guidance said only a faithful\n * delegating decorator was safe to inject. This invariant is what that guidance\n * was reaching for, stated so that a genuinely different implementation (a\n * SQLite-backed index, a lazily-paged one) is permitted while the reshaping that\n * was the actual hazard stays out.\n *\n * **Ordering is NOT part of the contract.** {@link IMemoryIndex.entries} may\n * return entries in any order and callers that need one sort explicitly. Note\n * this is a *behavioural* freedom the compiler cannot police: the bundled\n * {@link MemoryIndex} iterates a `Map` and so returns insertion order, which is\n * stable and observable, so code that came to rely on it keeps compiling and\n * changes results. The ordered accessors ({@link IMemoryIndex.byRecency},\n * {@link IMemoryIndex.byRank}, and the recency-ordered `byKind` / `byTag`) are\n * the supported way to ask for an order.\n * @public\n */\nexport interface IMemoryIndex {\n  /**\n   * Replace the entire index from a full set of entries (a store walk).\n   *\n   * @remarks\n   * Takes the **projected** {@link IIndexedMemoryEntry} form, not whole records,\n   * and the distinction is load-bearing rather than cosmetic: **`patch` writes,\n   * `rebuild` reads.** A rebuild is a whole-vault read that happens to terminate\n   * in the index, so requiring whole records here would force every caller — the\n   * store's own open path included — to materialize N bodies purely to feed a\n   * structure that projects the envelope back out and discards them. `patch`\n   * keeps whole records because it carries exactly one, which its caller already\n   * holds.\n   *\n   * @returns The number of entries indexed.\n   */\n  rebuild(entries: ReadonlyArray<IIndexedMemoryEntry>): Result<number>;\n\n  /**\n   * Apply a single incremental change. `'put'` inserts or replaces the entry\n   * at its `(scope, id)` key (removing any prior associations first); `'delete'`\n   * removes it.\n   *\n   * @remarks\n   * Takes the whole record — see {@link IMemoryIndex.rebuild} for why this one\n   * does and that one does not. It costs nothing (the caller is mid-write and\n   * holds the record already) and it is the single point at which an index\n   * maintaining a body-derived view could observe content without a re-read.\n   * What is *held* is still only the projection.\n   *\n   * @returns The entry that was applied.\n   */\n  patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord>;\n\n  /** Every indexed entry (scope + envelope). Primary read surface for the store. */\n  entries(): ReadonlyArray<IIndexedMemoryEntry>;\n\n  /**\n   * The entry at a scope-qualified address, or `undefined` if none.\n   *\n   * @remarks\n   * On the contract because its absence made every caller that wanted **one**\n   * entry rebuild a map of **all** of them: both `SemanticRetriever` (resolving\n   * at most `topK` hits) and `LinkTraversalRetriever` (resolving a BFS frontier)\n   * built a full-index `Map` per query for want of this. The index already keys\n   * on `(scope, id)` internally, so this exposes a lookup it was doing anyway.\n   */\n  get(target: IEdgeTarget): IIndexedMemoryEntry | undefined;\n\n  /** Entries of the given kind, in recency order (most-recently-updated first). */\n  byKind(kind: Kind): ReadonlyArray<IIndexedMemoryEntry>;\n\n  /** Entries carrying the given tag, in recency order. */\n  byTag(tag: Tag): ReadonlyArray<IIndexedMemoryEntry>;\n\n  /** All entries in recency order (most-recently-updated first). */\n  byRecency(): ReadonlyArray<IIndexedMemoryEntry>;\n\n  /**\n   * All entries ordered by store-computed {@link IMemoryEnvelope.rank} descending,\n   * with recency (most-recently-updated, then `seq`) as a tiebreak. Entries with\n   * an absent `rank` sort LAST (after every ranked entry), then by recency among\n   * themselves. Serves a bounded top-M ({@link IMemoryEnvelope.rank}-ordered) page\n   * from the in-memory index with no full-vault (filesystem) scan — and since the\n   * page is envelope-only, a caller taking the top M materializes M bodies rather\n   * than the vault.\n   */\n  byRank(): ReadonlyArray<IIndexedMemoryEntry>;\n\n  /**\n   * The scope-qualified sources of records whose `links` point AT `target`\n   * (inbound edges), keyed on the target's `(scope, id)` address. The seed map\n   * for B2 link-traversal; results are {@link IEdgeTarget}s so a caller can feed\n   * them straight back in as further traversal seeds.\n   */\n  backlinks(target: IEdgeTarget): ReadonlyArray<IEdgeTarget>;\n}\n\n/**\n * Default in-memory {@link IMemoryIndex}. Maintains the derived `byKind` /\n * `byTag` / `byRecency` / `backlinks` views incrementally; a `'put'` for an\n * already-indexed key first removes the prior entry's associations so a changed\n * kind / tag / link set never leaves a stale reference behind.\n * @public\n */\nexport class MemoryIndex implements IMemoryIndex {\n  /**\n   * Primary store: `(scope, id)` composite key → indexed entry. Holds the\n   * PROJECTED form, so the index never retains a body.\n   */\n  private readonly _byKey: Map<string, IIndexedMemoryEntry>;\n  /** kind → set of composite keys. */\n  private readonly _byKind: Map<Kind, Set<string>>;\n  /** tag → set of composite keys. */\n  private readonly _byTag: Map<Tag, Set<string>>;\n  /**\n   * canonical target key (`edgeTargetKey`) → (source composite key → source\n   * {@link IEdgeTarget}). The OUTER map is keyed on the scope-qualified target's\n   * canonical `(scope, id)` string — NOT the target's bare id — so an edge to\n   * `turn-3` in one conversation is tracked separately from `turn-3` in another.\n   * The INNER map is keyed by the source's `(scope, id)` composite so two distinct\n   * source records that share an id across scopes are tracked independently and\n   * removing one never drops the other's edge.\n   */\n  private readonly _backlinks: Map<string, Map<string, IEdgeTarget>>;\n\n  private constructor() {\n    this._byKey = new Map<string, IIndexedMemoryEntry>();\n    this._byKind = new Map<Kind, Set<string>>();\n    this._byTag = new Map<Tag, Set<string>>();\n    this._backlinks = new Map<string, Map<string, IEdgeTarget>>();\n  }\n\n  /** Family-convention factory. */\n  public static create(): Result<MemoryIndex> {\n    return succeed(new MemoryIndex());\n  }\n\n  /**\n   * The composite primary key for an entry: scope + id, NUL-separated. NUL\n   * is excluded from both components (scope segments pass\n   * `assertPortableFilenameStem`; `MemoryId` is portable-filename-safe), so it\n   * is a collision-proof separator across every scope/id pair the codecs produce.\n   */\n  private static _keyOf(scope: MemoryScopeKey, id: MemoryId): string {\n    return edgeTargetKey({ scope, id });\n  }\n\n  /** {@inheritDoc IMemoryIndex.rebuild} */\n  public rebuild(entries: ReadonlyArray<IIndexedMemoryEntry>): Result<number> {\n    this._byKey.clear();\n    this._byKind.clear();\n    this._byTag.clear();\n    this._backlinks.clear();\n    for (const entry of entries) {\n      this._add(entry);\n    }\n    return succeed(this._byKey.size);\n  }\n\n  /** {@inheritDoc IMemoryIndex.patch} */\n  public patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord> {\n    const key: string = MemoryIndex._keyOf(entry.scope, entry.record.envelope.id);\n    // Always drop any prior associations for this key first, so a 'put' that\n    // changes kind/tags/links cannot strand a stale reference.\n    this._remove(key);\n    if (op === 'put') {\n      // Projected on the way in: the caller's record is used for its envelope and\n      // the body is not retained.\n      this._add(toEntry(entry));\n    }\n    return succeed(entry);\n  }\n\n  /** {@inheritDoc IMemoryIndex.entries} */\n  public entries(): ReadonlyArray<IIndexedMemoryEntry> {\n    return Array.from(this._byKey.values());\n  }\n\n  /** {@inheritDoc IMemoryIndex.get} */\n  public get(target: IEdgeTarget): IIndexedMemoryEntry | undefined {\n    return this._byKey.get(edgeTargetKey(target));\n  }\n\n  /** {@inheritDoc IMemoryIndex.byKind} */\n  public byKind(kind: Kind): ReadonlyArray<IIndexedMemoryEntry> {\n    return this._recencyOrdered(this._byKind.get(kind) ?? EMPTY_KEY_SET);\n  }\n\n  /** {@inheritDoc IMemoryIndex.byTag} */\n  public byTag(tag: Tag): ReadonlyArray<IIndexedMemoryEntry> {\n    return this._recencyOrdered(this._byTag.get(tag) ?? EMPTY_KEY_SET);\n  }\n\n  /** {@inheritDoc IMemoryIndex.byRecency} */\n  public byRecency(): ReadonlyArray<IIndexedMemoryEntry> {\n    return this._recencyOrdered(this._byKey.keys());\n  }\n\n  /** {@inheritDoc IMemoryIndex.byRank} */\n  public byRank(): ReadonlyArray<IIndexedMemoryEntry> {\n    return this._rankOrdered(this._byKey.keys());\n  }\n\n  /** {@inheritDoc IMemoryIndex.backlinks} */\n  public backlinks(target: IEdgeTarget): ReadonlyArray<IEdgeTarget> {\n    const sources: Map<string, IEdgeTarget> | undefined = this._backlinks.get(edgeTargetKey(target));\n    return sources === undefined ? [] : Array.from(sources.values());\n  }\n\n  /**\n   * Resolve a set of composite keys to their records, ordered\n   * most-recently-updated first (with a `seq` tiebreak so equal-`updated`\n   * records sort deterministically).\n   */\n  private _recencyOrdered(keys: Iterable<string>): ReadonlyArray<IIndexedMemoryEntry> {\n    return MemoryIndex._resolve(this._byKey, keys).sort((a, b) => {\n      const byUpdated: number = b.envelope.updated - a.envelope.updated;\n      return byUpdated !== 0 ? byUpdated : b.envelope.seq - a.envelope.seq;\n    });\n  }\n\n  /**\n   * Resolve a set of composite keys to their records, ordered by\n   * {@link IMemoryEnvelope.rank} descending with recency (`updated`, then `seq`)\n   * as the tiebreak. Records with an absent `rank` sort LAST, then by recency\n   * among themselves. Computed on call (mirrors {@link MemoryIndex._recencyOrdered}) —\n   * no incremental rank-ordered view is maintained, matching the recency view's\n   * approach; the sort is over the in-memory index, never a filesystem walk.\n   */\n  private _rankOrdered(keys: Iterable<string>): ReadonlyArray<IIndexedMemoryEntry> {\n    return MemoryIndex._resolve(this._byKey, keys).sort(MemoryIndex._compareByRank);\n  }\n\n  /** Resolve composite keys to their entries, skipping any that are absent. */\n  private static _resolve(\n    byKey: ReadonlyMap<string, IIndexedMemoryEntry>,\n    keys: Iterable<string>\n  ): IIndexedMemoryEntry[] {\n    const entries: IIndexedMemoryEntry[] = [];\n    for (const key of keys) {\n      const entry: IIndexedMemoryEntry | undefined = byKey.get(key);\n      if (entry !== undefined) {\n        entries.push(entry);\n      }\n    }\n    return entries;\n  }\n\n  /**\n   * Rank-descending comparator with an absent-`rank`-last rule and a recency\n   * (`updated`, then `seq`) tiebreak. Duplicated from the retrieve packlet's\n   * `rankCompare` deliberately: the index must not depend on `retrieve` (that\n   * package depends on the index), mirroring how `_recencyOrdered` inlines the\n   * recency ordering rather than importing `recencyCompare`.\n   */\n  private static _compareByRank(a: IIndexedMemoryEntry, b: IIndexedMemoryEntry): number {\n    const ra: number | undefined = a.envelope.rank;\n    const rb: number | undefined = b.envelope.rank;\n    // Absent rank sorts last; two absent ranks fall through to the recency tiebreak.\n    if (ra === undefined && rb !== undefined) {\n      return 1;\n    }\n    if (rb === undefined && ra !== undefined) {\n      return -1;\n    }\n    if (ra !== undefined && rb !== undefined && ra !== rb) {\n      return rb - ra;\n    }\n    const byUpdated: number = b.envelope.updated - a.envelope.updated;\n    return byUpdated !== 0 ? byUpdated : b.envelope.seq - a.envelope.seq;\n  }\n\n  /** Insert an entry and register all its derived associations. */\n  private _add(entry: IIndexedMemoryEntry): void {\n    const key: string = MemoryIndex._keyOf(entry.scope, entry.envelope.id);\n    const envelope: IMemoryEnvelope = entry.envelope;\n    this._byKey.set(key, entry);\n    this._addToSetMap(this._byKind, envelope.kind, key);\n    for (const tag of envelope.tags) {\n      this._addToSetMap(this._byTag, tag, key);\n    }\n    for (const edge of envelope.links) {\n      this._addBacklink(edge.target, key, { scope: entry.scope, id: envelope.id });\n    }\n  }\n\n  /** Remove the entry at `key` (if present) and all its derived associations. */\n  private _remove(key: string): void {\n    const entry: IIndexedMemoryEntry | undefined = this._byKey.get(key);\n    if (entry === undefined) {\n      return;\n    }\n    const envelope: IMemoryEnvelope = entry.envelope;\n    this._byKey.delete(key);\n    this._removeFromSetMap(this._byKind, envelope.kind, key);\n    for (const tag of envelope.tags) {\n      this._removeFromSetMap(this._byTag, tag, key);\n    }\n    for (const edge of envelope.links) {\n      this._removeBacklink(edge.target, key);\n    }\n  }\n\n  /** Register `source` (keyed by its composite `sourceKey`) as linking at `target`. */\n  private _addBacklink(target: IEdgeTarget, sourceKey: string, source: IEdgeTarget): void {\n    const targetKey: string = edgeTargetKey(target);\n    const existing: Map<string, IEdgeTarget> | undefined = this._backlinks.get(targetKey);\n    if (existing === undefined) {\n      this._backlinks.set(targetKey, new Map<string, IEdgeTarget>([[sourceKey, source]]));\n    } else {\n      existing.set(sourceKey, source);\n    }\n  }\n\n  /** Drop the backlink from `sourceKey` to `target`, removing the target map when empty. */\n  private _removeBacklink(target: IEdgeTarget, sourceKey: string): void {\n    const targetKey: string = edgeTargetKey(target);\n    const existing: Map<string, IEdgeTarget> | undefined = this._backlinks.get(targetKey);\n    if (existing === undefined) {\n      return;\n    }\n    existing.delete(sourceKey);\n    if (existing.size === 0) {\n      this._backlinks.delete(targetKey);\n    }\n  }\n\n  /** Add `member` to the set at `mapKey`, creating the set on first use. */\n  private _addToSetMap<K, M>(map: Map<K, Set<M>>, mapKey: K, member: M): void {\n    const existing: Set<M> | undefined = map.get(mapKey);\n    if (existing === undefined) {\n      map.set(mapKey, new Set<M>([member]));\n    } else {\n      existing.add(member);\n    }\n  }\n\n  /** Remove `member` from the set at `mapKey`, dropping the set when empty. */\n  private _removeFromSetMap<K, M>(map: Map<K, Set<M>>, mapKey: K, member: M): void {\n    const existing: Set<M> | undefined = map.get(mapKey);\n    if (existing === undefined) {\n      return;\n    }\n    existing.delete(member);\n    if (existing.size === 0) {\n      map.delete(mapKey);\n    }\n  }\n}\n"]}

package/lib/packlets/ingest/orchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../../src/packlets/ingest/orchestrator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../../src/packlets/ingest/orchestrator.ts"],"names":[],"mappings":"AAKA,OAAO,EAAQ,OAAO,EAAE,MAAM,EAA6B,MAAM,eAAe,CAAC;AACjF,OAAO,EAML,cAAc,EAKd,IAAI,EACJ,QAAQ,EAMT,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,YAAY,EAAmB,MAAM,UAAU,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EACL,eAAe,EACf,cAAc,EACd,iBAAiB,EAEjB,kBAAkB,EACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAIL,WAAW,EACX,iBAAiB,EAKlB,MAAM,SAAS,CAAC;AAEjB;;;GAGG;AACH,eAAO,MAAM,6BAA6B,EAAE,MAAsB,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,QAAoC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAAa,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAU,CAAC;AAElD;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAElE;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;CACnG;AAED;;;GAGG;AACH,MAAM,WAAW,qCAAqC;IACpD,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,qFAAqF;IACrF,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IACpD,kEAAkE;IAClE,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC;IACvC,uCAAuC;IACvC,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,+CAA+C;IAC/C,QAAQ,CAAC,iBAAiB,EAAE,kBAAkB,CAAC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,eAAe,CAAC;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,YAAY,CAAC;IACpC,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC;;OAEG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;IACrC,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC;CACnC;AAwCD;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,yBAAyB;IACxE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAC5C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgC;IAC5D,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAE/C,OAAO;IAmBP,iCAAiC;WACnB,MAAM,CAAC,MAAM,EAAE,qCAAqC,GAAG,MAAM,CAAC,wBAAwB,CAAC;IAIrG,yDAAyD;IAC5C,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAM9E,0DAA0D;IAC7C,WAAW,CACtB,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,GAChC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAYpD,gFAAgF;YAClE,SAAS;IAIvB,+EAA+E;YACjE,QAAQ;IAOtB;;;OAGG;YACW,kBAAkB;IAyEhC,uFAAuF;YACzE,cAAc;IA4B5B;;;;;;;;OAQG;IACH,OAAO,CAAC,gBAAgB;IAyExB;;;;;;;;OAQG;YACW,eAAe;IAuB7B,4DAA4D;YAC9C,qBAAqB;IAYnC,iFAAiF;YACnE,6BAA6B;IA0D3C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,eAAe;IAsCvB;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAShC,0EAA0E;IAC1E,OAAO,CAAC,SAAS;IAIjB,+GAA+G;YACjG,OAAO;IA+CrB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAUjC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAa7B;;;;OAIG;IACH,OAAO,CAAC,cAAc;IA4BtB,uFAAuF;YACzE,cAAc;IAwC5B,+FAA+F;IAC/F,OAAO,CAAC,YAAY;IA+CpB,6EAA6E;IAC7E,OAAO,CAAC,MAAM,CAAC,UAAU;IAYzB,0FAA0F;IAC1F,OAAO,CAAC,WAAW;IAgBnB,oFAAoF;IACpF,OAAO,CAAC,eAAe;IAQvB,yGAAyG;YAC3F,QAAQ;IAUtB;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAU7B;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAYrB,8FAA8F;IAC9F,OAAO,CAAC,MAAM,CAAC,aAAa;IAI5B,oFAAoF;IACpF,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAkBjC,uFAAuF;IACvF,OAAO,CAAC,MAAM,CAAC,aAAa;CAU7B"}

package/lib/packlets/ingest/orchestrator.js

@@ -7,6 +7,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MemoryIngestOrchestrator = exports.DEFAULT_SIMILARITY_TOP_K = exports.DEFAULT_SIMILARITY_THRESHOLD = exports.CONTRADICTS_LINK_TYPE = exports.HOST_INGEST_PROVENANCE_SOURCE = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
 const types_1 = require("../types");
+const store_1 = require("../store");
 const cycleGuard_1 = require("./cycleGuard");
 /**
  * The provenance source stamped on every record the ingest pipeline writes.
@@ -92,7 +93,18 @@ class MemoryIngestOrchestrator {
     async _processCandidates(item, candidates) {
         // Snapshot the store once; stage-4 resolution and the cycle guard reason over
         // the pre-ingest state.
-        const snapshotResult = await this._store.list();
+        //
+        // DECLARED, not optimized. This reads every body in the vault on EVERY
+        // ingested item, and `scanEveryRecord()` is how the store now makes a caller
+        // say so out loud. Most of what the snapshot is used for downstream — edge
+        // target existence, the cycle guard's link walk, scoped-address keying — is
+        // envelope-only work that `listEntries()` would serve without reading a
+        // single file; only stage-4 layer-1's exact `{ kind, body }` match needs
+        // bodies, and it needs them for candidates rather than for the whole vault.
+        // Converting this is its own stream (`agent-memory-ingest-snapshot`), because
+        // it is on the write path with its own risk surface. Until then the cost is
+        // at least visible and greppable rather than implied.
+        const snapshotResult = await this._store.list((0, store_1.scanEveryRecord)());
         if (snapshotResult.isFailure()) {
             return (0, ts_utils_1.fail)(`ingest '${item.id}': failed to snapshot store: ${snapshotResult.message}`);
         }