@fgv/ts-agent-memory 5.1.0-39 → 5.1.0-41

package/dist/packlets/retrieve/hybridRetriever.js.map

@@ -1 +1 @@
-{"version":3,"file":"hybridRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/hybridRetriever.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, mapResults, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord, MemoryId } from '../types';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  guardRetrieverCapabilities,\n  limitRecords,\n  recencyCompare\n} from './retriever';\n\n/**\n * Strategy for combining the result sets of the retrievers a\n * {@link HybridRetriever} composes. Injectable so a consumer can weight,\n * re-rank, or intersect instead of the default union.\n * @public\n */\nexport interface IMergeStrategy {\n  /**\n   * Merge the per-retriever result sets into a single ordered result.\n   * @param resultSets - One entry per composed retriever, in composition order.\n   */\n  merge(\n    resultSets: ReadonlyArray<ReadonlyArray<IMemoryRecord<unknown>>>\n  ): Result<ReadonlyArray<IMemoryRecord<unknown>>>;\n}\n\n/**\n * The reference {@link IMergeStrategy}: a score-union. Every record is scored by\n * the number of composed result sets it appears in (deduplicated by\n * {@link IMemoryEnvelope.id | id}); the merged result is ordered by descending\n * score, then by recency. Records surfaced by more retrievers rank higher.\n *\n * @remarks\n * Dedup is by `id` alone, which is unambiguous for the flat (one-file-per-entity)\n * kinds B2 ships. Phase-C versioned kinds that reuse a stem across scopes will\n * extend the dedup key — additive, no API change.\n * @public\n */\nexport class ScoreUnionMergeStrategy implements IMergeStrategy {\n  private constructor() {}\n\n  /** Family-convention factory. */\n  public static create(): Result<ScoreUnionMergeStrategy> {\n    return succeed(new ScoreUnionMergeStrategy());\n  }\n\n  /** {@inheritDoc IMergeStrategy.merge} */\n  public merge(\n    resultSets: ReadonlyArray<ReadonlyArray<IMemoryRecord<unknown>>>\n  ): Result<ReadonlyArray<IMemoryRecord<unknown>>> {\n    const scored: Map<MemoryId, { readonly record: IMemoryRecord<unknown>; score: number }> = new Map();\n    for (const set of resultSets) {\n      // Count each id at most once per result set, so the score is \"how many\n      // retrievers surfaced this record\" rather than \"how many copies total\".\n      const seenInSet: Set<MemoryId> = new Set<MemoryId>();\n      for (const record of set) {\n        const id: MemoryId = record.envelope.id;\n        if (seenInSet.has(id)) {\n          continue;\n        }\n        seenInSet.add(id);\n        const existing = scored.get(id);\n        if (existing === undefined) {\n          scored.set(id, { record, score: 1 });\n        } else {\n          existing.score += 1;\n        }\n      }\n    }\n    const merged: IMemoryRecord<unknown>[] = Array.from(scored.values())\n      .sort((a, b) => (b.score !== a.score ? b.score - a.score : recencyCompare(a.record, b.record)))\n      .map((entry) => entry.record);\n    return succeed(merged);\n  }\n}\n\n/**\n * Composes several retrievers, dispatches a query to each, and merges their\n * results via an injectable {@link IMergeStrategy}. Its capabilities are the\n * union of the composed retrievers' capabilities.\n *\n * @remarks\n * The hybrid enforces the loud-degradation contract against its OWN (union)\n * capabilities, then projects the query for each child: a child that does not\n * support the `semantic` (or `asOf`) axis is handed a query with that axis\n * stripped, so it returns its normal results instead of loud-failing on a field\n * a sibling handles. A child that genuinely fails (e.g. a wired semantic backend\n * erroring) propagates — the hybrid never silently drops a failure.\n * @public\n */\nexport class HybridRetriever implements IMemoryRetriever {\n  private readonly _retrievers: ReadonlyArray<IMemoryRetriever>;\n  private readonly _mergeStrategy: IMergeStrategy;\n  private readonly _capabilities: IMemoryRetrieverCapabilities;\n\n  private constructor(\n    retrievers: ReadonlyArray<IMemoryRetriever>,\n    mergeStrategy: IMergeStrategy,\n    capabilities: IMemoryRetrieverCapabilities\n  ) {\n    this._retrievers = retrievers;\n    this._mergeStrategy = mergeStrategy;\n    this._capabilities = capabilities;\n  }\n\n  /** {@inheritDoc IMemoryRetriever.capabilities} */\n  public get capabilities(): IMemoryRetrieverCapabilities {\n    return this._capabilities;\n  }\n\n  /**\n   * Family-convention factory.\n   * @param retrievers - The retrievers to compose (at least one).\n   * @param mergeStrategy - How to combine their results.\n   */\n  public static create(\n    retrievers: ReadonlyArray<IMemoryRetriever>,\n    mergeStrategy: IMergeStrategy\n  ): Result<HybridRetriever> {\n    if (retrievers.length === 0) {\n      return fail('HybridRetriever: at least one retriever is required');\n    }\n    // Snapshot the caller's array so a later mutation cannot make `retrieve()`\n    // and the cached `capabilities` disagree.\n    const stableRetrievers: ReadonlyArray<IMemoryRetriever> = [...retrievers];\n    const capabilities: IMemoryRetrieverCapabilities = {\n      supportsSemanticRecall: stableRetrievers.some((r) => r.capabilities.supportsSemanticRecall),\n      supportsTemporalQuery: stableRetrievers.some((r) => r.capabilities.supportsTemporalQuery),\n      supportsLinkTraversal: stableRetrievers.some((r) => r.capabilities.supportsLinkTraversal)\n    };\n    return succeed(new HybridRetriever(stableRetrievers, mergeStrategy, capabilities));\n  }\n\n  /** {@inheritDoc IMemoryRetriever.retrieve} */\n  public async retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {\n    return guardRetrieverCapabilities(query, this._capabilities).thenOnSuccess(async () => {\n      const perRetriever: Result<ReadonlyArray<IMemoryRecord<unknown>>>[] = await Promise.all(\n        this._retrievers.map((retriever) => retriever.retrieve(this._projectQuery(query, retriever)))\n      );\n      return mapResults(perRetriever)\n        .onSuccess((resultSets) => this._mergeStrategy.merge(resultSets))\n        .onSuccess((merged) => succeed(limitRecords(merged, query.limit)));\n    });\n  }\n\n  /**\n   * Project the query for one child retriever. Two adjustments:\n   *\n   * - Strip axes the child does not support (`semantic` / `topK` for a\n   *   non-semantic child, `asOf` for a non-temporal child, the link axes for a\n   *   non-link child) so it returns its normal results rather than loud-failing\n   *   on a field a sibling handles.\n   * - Strip `limit` unconditionally: limit is a post-merge concern. A child that\n   *   pre-truncated its result set would starve the merge strategy of candidates\n   *   it needs to score correctly (a record both children would surface must\n   *   reach the merge to score 2). The hybrid applies `limit` once, after merge.\n   */\n  private _projectQuery(query: IMemoryQuery, retriever: IMemoryRetriever): IMemoryQuery {\n    const projected: { -readonly [K in keyof IMemoryQuery]: IMemoryQuery[K] } = { ...query };\n    delete projected.limit;\n    if (!retriever.capabilities.supportsSemanticRecall) {\n      delete projected.semantic;\n      delete projected.topK;\n    }\n    if (!retriever.capabilities.supportsTemporalQuery) {\n      delete projected.asOf;\n    }\n    if (!retriever.capabilities.supportsLinkTraversal) {\n      delete projected.linkedFrom;\n      delete projected.linkedTo;\n      delete projected.hops;\n    }\n    return projected;\n  }\n}\n"]}
+{"version":3,"file":"hybridRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/hybridRetriever.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, mapResults, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord, MemoryId } from '../types';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  guardRetrieverCapabilities,\n  limitRecords,\n  rankCompare,\n  recencyCompare\n} from './retriever';\n\n/**\n * Strategy for combining the result sets of the retrievers a\n * {@link HybridRetriever} composes. Injectable so a consumer can weight,\n * re-rank, or intersect instead of the default union.\n * @public\n */\nexport interface IMergeStrategy {\n  /**\n   * Merge the per-retriever result sets into a single ordered result.\n   * @param resultSets - One entry per composed retriever, in composition order.\n   */\n  merge(\n    resultSets: ReadonlyArray<ReadonlyArray<IMemoryRecord<unknown>>>\n  ): Result<ReadonlyArray<IMemoryRecord<unknown>>>;\n}\n\n/**\n * The reference {@link IMergeStrategy}: a score-union. Every record is scored by\n * the number of composed result sets it appears in (deduplicated by\n * {@link IMemoryEnvelope.id | id}); the merged result is ordered by descending\n * score, then by recency. Records surfaced by more retrievers rank higher.\n *\n * @remarks\n * Dedup is by `id` alone, which is unambiguous for the flat (one-file-per-entity)\n * kinds B2 ships. Phase-C versioned kinds that reuse a stem across scopes will\n * extend the dedup key — additive, no API change.\n * @public\n */\nexport class ScoreUnionMergeStrategy implements IMergeStrategy {\n  private constructor() {}\n\n  /** Family-convention factory. */\n  public static create(): Result<ScoreUnionMergeStrategy> {\n    return succeed(new ScoreUnionMergeStrategy());\n  }\n\n  /** {@inheritDoc IMergeStrategy.merge} */\n  public merge(\n    resultSets: ReadonlyArray<ReadonlyArray<IMemoryRecord<unknown>>>\n  ): Result<ReadonlyArray<IMemoryRecord<unknown>>> {\n    const scored: Map<MemoryId, { readonly record: IMemoryRecord<unknown>; score: number }> = new Map();\n    for (const set of resultSets) {\n      // Count each id at most once per result set, so the score is \"how many\n      // retrievers surfaced this record\" rather than \"how many copies total\".\n      const seenInSet: Set<MemoryId> = new Set<MemoryId>();\n      for (const record of set) {\n        const id: MemoryId = record.envelope.id;\n        if (seenInSet.has(id)) {\n          continue;\n        }\n        seenInSet.add(id);\n        const existing = scored.get(id);\n        if (existing === undefined) {\n          scored.set(id, { record, score: 1 });\n        } else {\n          existing.score += 1;\n        }\n      }\n    }\n    const merged: IMemoryRecord<unknown>[] = Array.from(scored.values())\n      .sort((a, b) => (b.score !== a.score ? b.score - a.score : recencyCompare(a.record, b.record)))\n      .map((entry) => entry.record);\n    return succeed(merged);\n  }\n}\n\n/**\n * Composes several retrievers, dispatches a query to each, and merges their\n * results via an injectable {@link IMergeStrategy}. Its capabilities are the\n * union of the composed retrievers' capabilities.\n *\n * @remarks\n * The hybrid enforces the loud-degradation contract against its OWN (union)\n * capabilities, then projects the query for each child: a child that does not\n * support the `semantic` (or `asOf`) axis is handed a query with that axis\n * stripped, so it returns its normal results instead of loud-failing on a field\n * a sibling handles. A child that genuinely fails (e.g. a wired semantic backend\n * erroring) propagates — the hybrid never silently drops a failure.\n * @public\n */\nexport class HybridRetriever implements IMemoryRetriever {\n  private readonly _retrievers: ReadonlyArray<IMemoryRetriever>;\n  private readonly _mergeStrategy: IMergeStrategy;\n  private readonly _capabilities: IMemoryRetrieverCapabilities;\n\n  private constructor(\n    retrievers: ReadonlyArray<IMemoryRetriever>,\n    mergeStrategy: IMergeStrategy,\n    capabilities: IMemoryRetrieverCapabilities\n  ) {\n    this._retrievers = retrievers;\n    this._mergeStrategy = mergeStrategy;\n    this._capabilities = capabilities;\n  }\n\n  /** {@inheritDoc IMemoryRetriever.capabilities} */\n  public get capabilities(): IMemoryRetrieverCapabilities {\n    return this._capabilities;\n  }\n\n  /**\n   * Family-convention factory.\n   * @param retrievers - The retrievers to compose (at least one).\n   * @param mergeStrategy - How to combine their results.\n   */\n  public static create(\n    retrievers: ReadonlyArray<IMemoryRetriever>,\n    mergeStrategy: IMergeStrategy\n  ): Result<HybridRetriever> {\n    if (retrievers.length === 0) {\n      return fail('HybridRetriever: at least one retriever is required');\n    }\n    // Snapshot the caller's array so a later mutation cannot make `retrieve()`\n    // and the cached `capabilities` disagree.\n    const stableRetrievers: ReadonlyArray<IMemoryRetriever> = [...retrievers];\n    const capabilities: IMemoryRetrieverCapabilities = {\n      supportsSemanticRecall: stableRetrievers.some((r) => r.capabilities.supportsSemanticRecall),\n      supportsTemporalQuery: stableRetrievers.some((r) => r.capabilities.supportsTemporalQuery),\n      supportsLinkTraversal: stableRetrievers.some((r) => r.capabilities.supportsLinkTraversal)\n    };\n    return succeed(new HybridRetriever(stableRetrievers, mergeStrategy, capabilities));\n  }\n\n  /** {@inheritDoc IMemoryRetriever.retrieve} */\n  public async retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {\n    return guardRetrieverCapabilities(query, this._capabilities).thenOnSuccess(async () => {\n      const perRetriever: Result<ReadonlyArray<IMemoryRecord<unknown>>>[] = await Promise.all(\n        this._retrievers.map((retriever) => retriever.retrieve(this._projectQuery(query, retriever)))\n      );\n      return mapResults(perRetriever)\n        .onSuccess((resultSets) => this._mergeStrategy.merge(resultSets))\n        .onSuccess((merged) => {\n          // `orderBy: 'rank'` re-orders the merged set by rank (descending, absent\n          // last) before the page window, so a rank-ordered hybrid query yields a\n          // rank-ordered page. Absent / `'recency'` preserves the merge strategy's\n          // own ordering (byte-identical to the pre-`orderBy` behavior).\n          const ordered: ReadonlyArray<IMemoryRecord<unknown>> =\n            query.orderBy === 'rank' ? [...merged].sort(rankCompare) : merged;\n          return succeed(limitRecords(ordered, query.limit, query.offset));\n        });\n    });\n  }\n\n  /**\n   * Project the query for one child retriever. Two adjustments:\n   *\n   * - Strip axes the child does not support (`semantic` / `topK` for a\n   *   non-semantic child, `asOf` for a non-temporal child, the link axes for a\n   *   non-link child) so it returns its normal results rather than loud-failing\n   *   on a field a sibling handles.\n   * - Strip `limit` unconditionally: limit is a post-merge concern. A child that\n   *   pre-truncated its result set would starve the merge strategy of candidates\n   *   it needs to score correctly (a record both children would surface must\n   *   reach the merge to score 2). The hybrid applies `limit` once, after merge.\n   */\n  private _projectQuery(query: IMemoryQuery, retriever: IMemoryRetriever): IMemoryQuery {\n    const projected: { -readonly [K in keyof IMemoryQuery]: IMemoryQuery[K] } = { ...query };\n    delete projected.limit;\n    // Offset, like limit, is a post-merge concern: a child that pre-skipped its\n    // own ordered set would drop candidates the merge needs to score correctly.\n    // The hybrid applies the `{ offset, limit }` window once, after merge.\n    delete projected.offset;\n    if (!retriever.capabilities.supportsSemanticRecall) {\n      delete projected.semantic;\n      delete projected.topK;\n    }\n    if (!retriever.capabilities.supportsTemporalQuery) {\n      delete projected.asOf;\n    }\n    if (!retriever.capabilities.supportsLinkTraversal) {\n      delete projected.linkedFrom;\n      delete projected.linkedTo;\n      delete projected.hops;\n    }\n    return projected;\n  }\n}\n"]}

package/dist/packlets/retrieve/linkTraversalRetriever.js

@@ -3,7 +3,8 @@
  * SPDX-License-Identifier: MIT
  */
 import { fail, succeed } from '@fgv/ts-utils';
-import { guardRetrieverCapabilities, indexedRecordMatchesQuery, limitRecords, recencyCompare } from './retriever';
+import { edgeTargetKey } from '../types';
+import { guardRetrieverCapabilities, indexedRecordMatchesQuery, limitRecords, orderingCompare } from './retriever';
 /** The capabilities a link-traversal retriever exposes (link traversal only). */
 const LINK_TRAVERSAL_CAPABILITIES = {
     supportsSemanticRecall: false,
@@ -19,20 +20,23 @@ const DEFAULT_HOPS = 1;
  */
 export const LINK_TRAVERSAL_NO_SEED_MESSAGE = 'link traversal requires a seed id (linkedFrom or linkedTo)';
 /**
- * Breadth-first link-traversal retriever. From a seed {@link MemoryId} it walks
- * the link graph up to `query.hops` levels and returns the records reached
- * (excluding the seed), recency-ordered and limited.
+ * Breadth-first link-traversal retriever. From a scope-qualified
+ * {@link IEdgeTarget} seed it walks the link graph up to `query.hops` levels and
+ * returns the records reached (excluding the seed), recency-ordered and limited.
  *
  * @remarks
  * - **Direction.** `linkedFrom` walks OUTBOUND edges (each record's
  *   `envelope.links[].target`); `linkedTo` walks INBOUND edges (the index's
  *   `backlinks`). Exactly one is the seed; `linkedFrom` wins if both are set.
+ * - **Scope-qualified nodes.** Every graph node is an {@link IEdgeTarget}
+ *   `(scope, id)` pair, so following an edge to `turn-3` reaches ONLY the record
+ *   in the edge's own scope — never a same-stem record in another scope.
  * - **Bound + cycle safety.** Traversal is bounded by `hops` (default `1` — a
- *   single hop) and a visited-set guard. The graph is keyed by bare
- *   string {@link MemoryId}s, so a `Set<string>` visited-set is the exact,
- *   collision-free cycle key — no structural hashing (e.g. `Crc32Normalizer`) is
- *   needed. A self-loop or any multi-hop cycle terminates because a revisited id
- *   is never re-expanded.
+ *   single hop) and a visited-set guard. Nodes are canonicalized to their
+ *   `(scope, id)` string via {@link edgeTargetKey}, so a `Set<string>` visited-set
+ *   is the exact, collision-free cycle key — no structural hashing (e.g.
+ *   `Crc32Normalizer`) is needed. A self-loop or any multi-hop cycle terminates
+ *   because a revisited node is never re-expanded.
  * - **Post-filter.** The scope / kind / tag / predicate axes of the query are
  *   applied to the reached records (the link axes are the traversal itself).
  * @public
@@ -62,18 +66,20 @@ export class LinkTraversalRetriever {
             return fail(LINK_TRAVERSAL_NO_SEED_MESSAGE);
         }
         const hops = (_b = query.hops) !== null && _b !== void 0 ? _b : DEFAULT_HOPS;
-        const byId = this._indexById();
-        // The visited-set IS the cycle guard: ids are strings, so set membership is
-        // an exact identity check. The seed is pre-marked so it is never re-added.
-        const visited = new Set([seed]);
+        const byKey = this._indexByKey();
+        // The visited-set IS the cycle guard: nodes are canonicalized to their
+        // `(scope, id)` string, so set membership is an exact identity check. The
+        // seed is pre-marked so it is never re-added.
+        const visited = new Set([edgeTargetKey(seed)]);
         const reached = [];
         let frontier = [seed];
         for (let hop = 0; hop < hops && frontier.length > 0; hop++) {
             const next = [];
-            for (const id of frontier) {
-                for (const neighbor of outbound ? this._outbound(id, byId) : this._inbound(id)) {
-                    if (!visited.has(neighbor)) {
-                        visited.add(neighbor);
+            for (const node of frontier) {
+                for (const neighbor of outbound ? this._outbound(node, byKey) : this._inbound(node)) {
+                    const neighborKey = edgeTargetKey(neighbor);
+                    if (!visited.has(neighborKey)) {
+                        visited.add(neighborKey);
                         reached.push(neighbor);
                         next.push(neighbor);
                     }
@@ -82,62 +88,45 @@ export class LinkTraversalRetriever {
             frontier = next;
         }
         const entries = [];
-        for (const id of reached) {
-            const matches = byId.get(id);
-            if (matches !== undefined) {
-                entries.push(...matches);
+        for (const node of reached) {
+            const match = byKey.get(edgeTargetKey(node));
+            if (match !== undefined) {
+                entries.push(match);
             }
         }
         const ordered = entries
             .filter((entry) => indexedRecordMatchesQuery(entry, query))
             .map((entry) => entry.record)
-            .sort(recencyCompare);
-        return succeed(limitRecords(ordered, query.limit));
+            .sort(orderingCompare(query.orderBy));
+        return succeed(limitRecords(ordered, query.limit, query.offset));
     }
     /**
-     * Group the index's entries by bare {@link MemoryId}. An id can map to more
-     * than one entry when distinct scopes reuse a filename stem (e.g. `turn-0` in
-     * two conversations), so the value is an array.
-     *
-     * @remarks
-     * **Design note (links are globally-scoped identifiers in this phase).** An
-     * {@link IEdge.target} is a bare `MemoryId`, not a `(scope, id)` pair, so
-     * traversal resolves a target across ALL scopes that hold that id. When two
-     * scopes reuse a stem, following an edge to it reaches every match. This
-     * mirrors the `backlinks` index, which is also keyed by bare id. Scope-
-     * qualified link resolution is intentionally out of scope for Phase C and
-     * would be an additive change here (and to {@link IEdge} / the index).
+     * Group the index's entries by their scope-qualified {@link edgeTargetKey}
+     * `(scope, id)` composite. Each composite is the index's primary key, so it maps
+     * to exactly one entry — two records that reuse a filename stem across scopes
+     * (e.g. `turn-0` in two conversations) get distinct keys and never collide.
      */
-    _indexById() {
-        const byId = new Map();
+    _indexByKey() {
+        const byKey = new Map();
         for (const entry of this._index.entries()) {
-            const id = entry.record.envelope.id;
-            const existing = byId.get(id);
-            if (existing === undefined) {
-                byId.set(id, [entry]);
-            }
-            else {
-                existing.push(entry);
-            }
+            byKey.set(edgeTargetKey({ scope: entry.scope, id: entry.record.envelope.id }), entry);
         }
-        return byId;
+        return byKey;
     }
-    /** Outbound neighbors: the targets of every edge on the records with this id. */
-    _outbound(id, byId) {
+    /** Outbound neighbors: the scope-qualified targets of every edge on the record at `node`. */
+    _outbound(node, byKey) {
         const targets = [];
-        const matches = byId.get(id);
-        if (matches !== undefined) {
-            for (const entry of matches) {
-                for (const edge of entry.record.envelope.links) {
-                    targets.push(edge.target);
-                }
+        const match = byKey.get(edgeTargetKey(node));
+        if (match !== undefined) {
+            for (const edge of match.record.envelope.links) {
+                targets.push(edge.target);
             }
         }
         return targets;
     }
-    /** Inbound neighbors: the ids whose edges point AT this id (the backlinks). */
-    _inbound(id) {
-        return this._index.backlinks(id);
+    /** Inbound neighbors: the scope-qualified sources whose edges point AT `node` (the backlinks). */
+    _inbound(node) {
+        return this._index.backlinks(node);
     }
 }
 //# sourceMappingURL=linkTraversalRetriever.js.map

package/dist/packlets/retrieve/linkTraversalRetriever.js.map

@@ -1 +1 @@
-{"version":3,"file":"linkTraversalRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/linkTraversalRetriever.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord, MemoryId } from '../types';\nimport { IIndexedMemoryRecord, IMemoryIndex } from '../index';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  guardRetrieverCapabilities,\n  indexedRecordMatchesQuery,\n  limitRecords,\n  recencyCompare\n} from './retriever';\n\n/** The capabilities a link-traversal retriever exposes (link traversal only). */\nconst LINK_TRAVERSAL_CAPABILITIES: IMemoryRetrieverCapabilities = {\n  supportsSemanticRecall: false,\n  supportsTemporalQuery: false,\n  supportsLinkTraversal: true\n};\n\n/** Default BFS hop count when `query.hops` is not supplied. */\nconst DEFAULT_HOPS: number = 1;\n\n/**\n * The loud-degradation message returned when a link-traversal query supplies no\n * seed (`linkedFrom` / `linkedTo`).\n * @public\n */\nexport const LINK_TRAVERSAL_NO_SEED_MESSAGE: string =\n  'link traversal requires a seed id (linkedFrom or linkedTo)';\n\n/**\n * Breadth-first link-traversal retriever. From a seed {@link MemoryId} it walks\n * the link graph up to `query.hops` levels and returns the records reached\n * (excluding the seed), recency-ordered and limited.\n *\n * @remarks\n * - **Direction.** `linkedFrom` walks OUTBOUND edges (each record's\n *   `envelope.links[].target`); `linkedTo` walks INBOUND edges (the index's\n *   `backlinks`). Exactly one is the seed; `linkedFrom` wins if both are set.\n * - **Bound + cycle safety.** Traversal is bounded by `hops` (default `1` — a\n *   single hop) and a visited-set guard. The graph is keyed by bare\n *   string {@link MemoryId}s, so a `Set<string>` visited-set is the exact,\n *   collision-free cycle key — no structural hashing (e.g. `Crc32Normalizer`) is\n *   needed. A self-loop or any multi-hop cycle terminates because a revisited id\n *   is never re-expanded.\n * - **Post-filter.** The scope / kind / tag / predicate axes of the query are\n *   applied to the reached records (the link axes are the traversal itself).\n * @public\n */\nexport class LinkTraversalRetriever implements IMemoryRetriever {\n  private readonly _index: IMemoryIndex;\n\n  private constructor(index: IMemoryIndex) {\n    this._index = index;\n  }\n\n  /** Family-convention factory. */\n  public static create(index: IMemoryIndex): Result<LinkTraversalRetriever> {\n    return succeed(new LinkTraversalRetriever(index));\n  }\n\n  /** {@inheritDoc IMemoryRetriever.capabilities} */\n  public get capabilities(): IMemoryRetrieverCapabilities {\n    return LINK_TRAVERSAL_CAPABILITIES;\n  }\n\n  /** {@inheritDoc IMemoryRetriever.retrieve} */\n  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {\n    return Promise.resolve(\n      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => this._traverse(query))\n    );\n  }\n\n  /** Run the bounded, cycle-safe BFS and post-filter the reached records. */\n  private _traverse(query: IMemoryQuery): Result<ReadonlyArray<IMemoryRecord<unknown>>> {\n    const outbound: boolean = query.linkedFrom !== undefined;\n    const seed: MemoryId | undefined = query.linkedFrom ?? query.linkedTo;\n    if (seed === undefined) {\n      return fail(LINK_TRAVERSAL_NO_SEED_MESSAGE);\n    }\n    const hops: number = query.hops ?? DEFAULT_HOPS;\n    const byId: ReadonlyMap<MemoryId, IIndexedMemoryRecord[]> = this._indexById();\n\n    // The visited-set IS the cycle guard: ids are strings, so set membership is\n    // an exact identity check. The seed is pre-marked so it is never re-added.\n    const visited: Set<string> = new Set<string>([seed]);\n    const reached: MemoryId[] = [];\n    let frontier: MemoryId[] = [seed];\n    for (let hop = 0; hop < hops && frontier.length > 0; hop++) {\n      const next: MemoryId[] = [];\n      for (const id of frontier) {\n        for (const neighbor of outbound ? this._outbound(id, byId) : this._inbound(id)) {\n          if (!visited.has(neighbor)) {\n            visited.add(neighbor);\n            reached.push(neighbor);\n            next.push(neighbor);\n          }\n        }\n      }\n      frontier = next;\n    }\n\n    const entries: IIndexedMemoryRecord[] = [];\n    for (const id of reached) {\n      const matches: IIndexedMemoryRecord[] | undefined = byId.get(id);\n      if (matches !== undefined) {\n        entries.push(...matches);\n      }\n    }\n    const ordered: IMemoryRecord<unknown>[] = entries\n      .filter((entry) => indexedRecordMatchesQuery(entry, query))\n      .map((entry) => entry.record)\n      .sort(recencyCompare);\n    return succeed(limitRecords(ordered, query.limit));\n  }\n\n  /**\n   * Group the index's entries by bare {@link MemoryId}. An id can map to more\n   * than one entry when distinct scopes reuse a filename stem (e.g. `turn-0` in\n   * two conversations), so the value is an array.\n   *\n   * @remarks\n   * **Design note (links are globally-scoped identifiers in this phase).** An\n   * {@link IEdge.target} is a bare `MemoryId`, not a `(scope, id)` pair, so\n   * traversal resolves a target across ALL scopes that hold that id. When two\n   * scopes reuse a stem, following an edge to it reaches every match. This\n   * mirrors the `backlinks` index, which is also keyed by bare id. Scope-\n   * qualified link resolution is intentionally out of scope for Phase C and\n   * would be an additive change here (and to {@link IEdge} / the index).\n   */\n  private _indexById(): ReadonlyMap<MemoryId, IIndexedMemoryRecord[]> {\n    const byId: Map<MemoryId, IIndexedMemoryRecord[]> = new Map<MemoryId, IIndexedMemoryRecord[]>();\n    for (const entry of this._index.entries()) {\n      const id: MemoryId = entry.record.envelope.id;\n      const existing: IIndexedMemoryRecord[] | undefined = byId.get(id);\n      if (existing === undefined) {\n        byId.set(id, [entry]);\n      } else {\n        existing.push(entry);\n      }\n    }\n    return byId;\n  }\n\n  /** Outbound neighbors: the targets of every edge on the records with this id. */\n  private _outbound(id: MemoryId, byId: ReadonlyMap<MemoryId, IIndexedMemoryRecord[]>): MemoryId[] {\n    const targets: MemoryId[] = [];\n    const matches: IIndexedMemoryRecord[] | undefined = byId.get(id);\n    if (matches !== undefined) {\n      for (const entry of matches) {\n        for (const edge of entry.record.envelope.links) {\n          targets.push(edge.target);\n        }\n      }\n    }\n    return targets;\n  }\n\n  /** Inbound neighbors: the ids whose edges point AT this id (the backlinks). */\n  private _inbound(id: MemoryId): ReadonlyArray<MemoryId> {\n    return this._index.backlinks(id);\n  }\n}\n"]}
+{"version":3,"file":"linkTraversalRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/linkTraversalRetriever.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport { IEdgeTarget, IMemoryRecord, edgeTargetKey } from '../types';\nimport { IIndexedMemoryRecord, IMemoryIndex } from '../index';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  guardRetrieverCapabilities,\n  indexedRecordMatchesQuery,\n  limitRecords,\n  orderingCompare\n} from './retriever';\n\n/** The capabilities a link-traversal retriever exposes (link traversal only). */\nconst LINK_TRAVERSAL_CAPABILITIES: IMemoryRetrieverCapabilities = {\n  supportsSemanticRecall: false,\n  supportsTemporalQuery: false,\n  supportsLinkTraversal: true\n};\n\n/** Default BFS hop count when `query.hops` is not supplied. */\nconst DEFAULT_HOPS: number = 1;\n\n/**\n * The loud-degradation message returned when a link-traversal query supplies no\n * seed (`linkedFrom` / `linkedTo`).\n * @public\n */\nexport const LINK_TRAVERSAL_NO_SEED_MESSAGE: string =\n  'link traversal requires a seed id (linkedFrom or linkedTo)';\n\n/**\n * Breadth-first link-traversal retriever. From a scope-qualified\n * {@link IEdgeTarget} seed it walks the link graph up to `query.hops` levels and\n * returns the records reached (excluding the seed), recency-ordered and limited.\n *\n * @remarks\n * - **Direction.** `linkedFrom` walks OUTBOUND edges (each record's\n *   `envelope.links[].target`); `linkedTo` walks INBOUND edges (the index's\n *   `backlinks`). Exactly one is the seed; `linkedFrom` wins if both are set.\n * - **Scope-qualified nodes.** Every graph node is an {@link IEdgeTarget}\n *   `(scope, id)` pair, so following an edge to `turn-3` reaches ONLY the record\n *   in the edge's own scope — never a same-stem record in another scope.\n * - **Bound + cycle safety.** Traversal is bounded by `hops` (default `1` — a\n *   single hop) and a visited-set guard. Nodes are canonicalized to their\n *   `(scope, id)` string via {@link edgeTargetKey}, so a `Set<string>` visited-set\n *   is the exact, collision-free cycle key — no structural hashing (e.g.\n *   `Crc32Normalizer`) is needed. A self-loop or any multi-hop cycle terminates\n *   because a revisited node is never re-expanded.\n * - **Post-filter.** The scope / kind / tag / predicate axes of the query are\n *   applied to the reached records (the link axes are the traversal itself).\n * @public\n */\nexport class LinkTraversalRetriever implements IMemoryRetriever {\n  private readonly _index: IMemoryIndex;\n\n  private constructor(index: IMemoryIndex) {\n    this._index = index;\n  }\n\n  /** Family-convention factory. */\n  public static create(index: IMemoryIndex): Result<LinkTraversalRetriever> {\n    return succeed(new LinkTraversalRetriever(index));\n  }\n\n  /** {@inheritDoc IMemoryRetriever.capabilities} */\n  public get capabilities(): IMemoryRetrieverCapabilities {\n    return LINK_TRAVERSAL_CAPABILITIES;\n  }\n\n  /** {@inheritDoc IMemoryRetriever.retrieve} */\n  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {\n    return Promise.resolve(\n      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => this._traverse(query))\n    );\n  }\n\n  /** Run the bounded, cycle-safe BFS and post-filter the reached records. */\n  private _traverse(query: IMemoryQuery): Result<ReadonlyArray<IMemoryRecord<unknown>>> {\n    const outbound: boolean = query.linkedFrom !== undefined;\n    const seed: IEdgeTarget | undefined = query.linkedFrom ?? query.linkedTo;\n    if (seed === undefined) {\n      return fail(LINK_TRAVERSAL_NO_SEED_MESSAGE);\n    }\n    const hops: number = query.hops ?? DEFAULT_HOPS;\n    const byKey: ReadonlyMap<string, IIndexedMemoryRecord> = this._indexByKey();\n\n    // The visited-set IS the cycle guard: nodes are canonicalized to their\n    // `(scope, id)` string, so set membership is an exact identity check. The\n    // seed is pre-marked so it is never re-added.\n    const visited: Set<string> = new Set<string>([edgeTargetKey(seed)]);\n    const reached: IEdgeTarget[] = [];\n    let frontier: IEdgeTarget[] = [seed];\n    for (let hop = 0; hop < hops && frontier.length > 0; hop++) {\n      const next: IEdgeTarget[] = [];\n      for (const node of frontier) {\n        for (const neighbor of outbound ? this._outbound(node, byKey) : this._inbound(node)) {\n          const neighborKey: string = edgeTargetKey(neighbor);\n          if (!visited.has(neighborKey)) {\n            visited.add(neighborKey);\n            reached.push(neighbor);\n            next.push(neighbor);\n          }\n        }\n      }\n      frontier = next;\n    }\n\n    const entries: IIndexedMemoryRecord[] = [];\n    for (const node of reached) {\n      const match: IIndexedMemoryRecord | undefined = byKey.get(edgeTargetKey(node));\n      if (match !== undefined) {\n        entries.push(match);\n      }\n    }\n    const ordered: IMemoryRecord<unknown>[] = entries\n      .filter((entry) => indexedRecordMatchesQuery(entry, query))\n      .map((entry) => entry.record)\n      .sort(orderingCompare(query.orderBy));\n    return succeed(limitRecords(ordered, query.limit, query.offset));\n  }\n\n  /**\n   * Group the index's entries by their scope-qualified {@link edgeTargetKey}\n   * `(scope, id)` composite. Each composite is the index's primary key, so it maps\n   * to exactly one entry — two records that reuse a filename stem across scopes\n   * (e.g. `turn-0` in two conversations) get distinct keys and never collide.\n   */\n  private _indexByKey(): ReadonlyMap<string, IIndexedMemoryRecord> {\n    const byKey: Map<string, IIndexedMemoryRecord> = new Map<string, IIndexedMemoryRecord>();\n    for (const entry of this._index.entries()) {\n      byKey.set(edgeTargetKey({ scope: entry.scope, id: entry.record.envelope.id }), entry);\n    }\n    return byKey;\n  }\n\n  /** Outbound neighbors: the scope-qualified targets of every edge on the record at `node`. */\n  private _outbound(node: IEdgeTarget, byKey: ReadonlyMap<string, IIndexedMemoryRecord>): IEdgeTarget[] {\n    const targets: IEdgeTarget[] = [];\n    const match: IIndexedMemoryRecord | undefined = byKey.get(edgeTargetKey(node));\n    if (match !== undefined) {\n      for (const edge of match.record.envelope.links) {\n        targets.push(edge.target);\n      }\n    }\n    return targets;\n  }\n\n  /** Inbound neighbors: the scope-qualified sources whose edges point AT `node` (the backlinks). */\n  private _inbound(node: IEdgeTarget): ReadonlyArray<IEdgeTarget> {\n    return this._index.backlinks(node);\n  }\n}\n"]}

package/dist/packlets/retrieve/recencyRetriever.js

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: MIT
  */
 import { succeed } from '@fgv/ts-utils';
-import { NON_SEMANTIC_CAPABILITIES, guardRetrieverCapabilities, limitRecords, recencyCompare, selectByQuery } from './retriever';
+import { NON_SEMANTIC_CAPABILITIES, guardRetrieverCapabilities, limitRecords, orderingCompare, selectByQuery } from './retriever';
 /**
  * Returns records matching the query's scope / kind / tag / predicate filters,
  * ordered most-recently-updated first. The universal v1 retriever — an empty
@@ -25,8 +25,8 @@ export class RecencyRetriever {
     /** {@inheritDoc IMemoryRetriever.retrieve} */
     retrieve(query) {
         return Promise.resolve(guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => {
-            const ordered = selectByQuery(this._index.entries(), query).sort(recencyCompare);
-            return succeed(limitRecords(ordered, query.limit));
+            const ordered = selectByQuery(this._index.entries(), query).sort(orderingCompare(query.orderBy));
+            return succeed(limitRecords(ordered, query.limit, query.offset));
         }));
     }
 }

package/dist/packlets/retrieve/recencyRetriever.js.map

@@ -1 +1 @@
-{"version":3,"file":"recencyRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/recencyRetriever.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,OAAO,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAIL,yBAAyB,EACzB,0BAA0B,EAC1B,YAAY,EACZ,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IAG3B,YAAoB,KAAmB;QACrC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,kDAAkD;IAClD,IAAW,YAAY;QACrB,OAAO,yBAAyB,CAAC;IACnC,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM,CAAC,KAAmB;QACtC,OAAO,OAAO,CAAC,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,8CAA8C;IACvC,QAAQ,CAAC,KAAmB;QACjC,OAAO,OAAO,CAAC,OAAO,CACpB,0BAA0B,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE;YAClE,MAAM,OAAO,GAA6B,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC,IAAI,CACxF,cAAc,CACf,CAAC;YACF,OAAO,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QACrD,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord } from '../types';\nimport { IMemoryIndex } from '../index';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  NON_SEMANTIC_CAPABILITIES,\n  guardRetrieverCapabilities,\n  limitRecords,\n  recencyCompare,\n  selectByQuery\n} from './retriever';\n\n/**\n * Returns records matching the query's scope / kind / tag / predicate filters,\n * ordered most-recently-updated first. The universal v1 retriever — an empty\n * query returns the whole vault in recency order.\n * @public\n */\nexport class RecencyRetriever implements IMemoryRetriever {\n  private readonly _index: IMemoryIndex;\n\n  private constructor(index: IMemoryIndex) {\n    this._index = index;\n  }\n\n  /** {@inheritDoc IMemoryRetriever.capabilities} */\n  public get capabilities(): IMemoryRetrieverCapabilities {\n    return NON_SEMANTIC_CAPABILITIES;\n  }\n\n  /** Family-convention factory. */\n  public static create(index: IMemoryIndex): Result<RecencyRetriever> {\n    return succeed(new RecencyRetriever(index));\n  }\n\n  /** {@inheritDoc IMemoryRetriever.retrieve} */\n  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {\n    return Promise.resolve(\n      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => {\n        const ordered: IMemoryRecord<unknown>[] = selectByQuery(this._index.entries(), query).sort(\n          recencyCompare\n        );\n        return succeed(limitRecords(ordered, query.limit));\n      })\n    );\n  }\n}\n"]}
+{"version":3,"file":"recencyRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/recencyRetriever.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,OAAO,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAIL,yBAAyB,EACzB,0BAA0B,EAC1B,YAAY,EACZ,eAAe,EACf,aAAa,EACd,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IAG3B,YAAoB,KAAmB;QACrC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,kDAAkD;IAClD,IAAW,YAAY;QACrB,OAAO,yBAAyB,CAAC;IACnC,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM,CAAC,KAAmB;QACtC,OAAO,OAAO,CAAC,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,8CAA8C;IACvC,QAAQ,CAAC,KAAmB;QACjC,OAAO,OAAO,CAAC,OAAO,CACpB,0BAA0B,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE;YAClE,MAAM,OAAO,GAA6B,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC,IAAI,CACxF,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,CAC/B,CAAC;YACF,OAAO,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QACnE,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord } from '../types';\nimport { IMemoryIndex } from '../index';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  NON_SEMANTIC_CAPABILITIES,\n  guardRetrieverCapabilities,\n  limitRecords,\n  orderingCompare,\n  selectByQuery\n} from './retriever';\n\n/**\n * Returns records matching the query's scope / kind / tag / predicate filters,\n * ordered most-recently-updated first. The universal v1 retriever — an empty\n * query returns the whole vault in recency order.\n * @public\n */\nexport class RecencyRetriever implements IMemoryRetriever {\n  private readonly _index: IMemoryIndex;\n\n  private constructor(index: IMemoryIndex) {\n    this._index = index;\n  }\n\n  /** {@inheritDoc IMemoryRetriever.capabilities} */\n  public get capabilities(): IMemoryRetrieverCapabilities {\n    return NON_SEMANTIC_CAPABILITIES;\n  }\n\n  /** Family-convention factory. */\n  public static create(index: IMemoryIndex): Result<RecencyRetriever> {\n    return succeed(new RecencyRetriever(index));\n  }\n\n  /** {@inheritDoc IMemoryRetriever.retrieve} */\n  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {\n    return Promise.resolve(\n      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => {\n        const ordered: IMemoryRecord<unknown>[] = selectByQuery(this._index.entries(), query).sort(\n          orderingCompare(query.orderBy)\n        );\n        return succeed(limitRecords(ordered, query.limit, query.offset));\n      })\n    );\n  }\n}\n"]}

package/dist/packlets/retrieve/retriever.js

@@ -62,6 +62,36 @@ export function recencyCompare(a, b) {
     const byUpdated = b.envelope.updated - a.envelope.updated;
     return byUpdated !== 0 ? byUpdated : b.envelope.seq - a.envelope.seq;
 }
+/**
+ * Rank comparator: store-computed {@link IMemoryEnvelope.rank} descending, with
+ * {@link recencyCompare} as the tiebreak. Records with an absent `rank` sort LAST
+ * (after every ranked record), then by recency among themselves. Mirrors the
+ * index's rank-view ordering.
+ * @public
+ */
+export function rankCompare(a, b) {
+    const ra = a.envelope.rank;
+    const rb = b.envelope.rank;
+    if (ra === undefined && rb !== undefined) {
+        return 1;
+    }
+    if (rb === undefined && ra !== undefined) {
+        return -1;
+    }
+    if (ra !== undefined && rb !== undefined && ra !== rb) {
+        return rb - ra;
+    }
+    return recencyCompare(a, b);
+}
+/**
+ * Select the record comparator for a query's {@link IMemoryQuery.orderBy | orderBy}
+ * axis: {@link rankCompare} for `'rank'`, {@link recencyCompare} otherwise (the
+ * default, byte-identical to the pre-`orderBy` behavior).
+ * @public
+ */
+export function orderingCompare(orderBy) {
+    return orderBy === 'rank' ? rankCompare : recencyCompare;
+}
 /**
  * Whether an indexed entry satisfies a query's scope / kind / tag / predicate
  * pre-filter (the axes shared by every v1 retriever). The `semantic` / `asOf` /
@@ -75,6 +105,9 @@ export function indexedRecordMatchesQuery(entry, query) {
     if (query.kind !== undefined && entry.record.envelope.kind !== query.kind) {
         return false;
     }
+    if (query.kinds !== undefined && !query.kinds.includes(entry.record.envelope.kind)) {
+        return false;
+    }
     if (query.tag !== undefined && !entry.record.envelope.tags.includes(query.tag)) {
         return false;
     }
@@ -92,19 +125,29 @@ export function selectByQuery(entries, query) {
     return entries.filter((entry) => indexedRecordMatchesQuery(entry, query)).map((entry) => entry.record);
 }
 /**
- * Truncate to `query.limit` records (a no-op when `limit` is absent). Applied
- * last, after ordering, so it always takes the top-N of the ordered result. A
- * non-positive `limit` is public query input and means "no records" — it returns
- * an empty array rather than letting a negative value slip into `slice`.
+ * Apply the `{ offset, limit }` page window to an ordered record set. Applied
+ * last, after ordering, so it always takes a stable window of the ordered
+ * result. `offset` is applied first (records to skip), then `limit` (top-N of
+ * the remainder).
+ *
+ * @remarks
+ * Both bounds are public query input and are guarded against non-positive
+ * values slipping into `slice`:
+ * - `offset` absent or non-positive → no skip (today's behavior). An offset past
+ *   the end yields an empty page rather than a throw.
+ * - `limit` absent → no truncation; a non-positive `limit` means "no records"
+ *   and returns an empty array.
  * @public
  */
-export function limitRecords(records, limit) {
+export function limitRecords(records, limit, offset) {
+    const skip = offset !== undefined && offset > 0 ? offset : 0;
+    const windowed = skip > 0 ? records.slice(skip) : records;
     if (limit === undefined) {
-        return records;
+        return windowed;
     }
     if (limit <= 0) {
         return [];
     }
-    return records.length > limit ? records.slice(0, limit) : records;
+    return windowed.length > limit ? windowed.slice(0, limit) : windowed;
 }
 //# sourceMappingURL=retriever.js.map

package/dist/packlets/retrieve/retriever.js.map

@@ -1 +1 @@
-{"version":3,"file":"retriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/retriever.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,IAAI,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AA6EtD;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAW,0DAA0D,CAAC;AAE3G;;;;;GAKG;AACH,MAAM,CAAC,MAAM,8BAA8B,GACzC,2DAA2D,CAAC;AAE9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAiC;IACrE,sBAAsB,EAAE,KAAK;IAC7B,qBAAqB,EAAE,KAAK;IAC5B,qBAAqB,EAAE,KAAK;CAC7B,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAW;IAChD,OAAO,0DACL,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,CAAC,EAC7C,EAAE,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAmB,EACnB,YAA0C;IAE1C,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,YAAY,CAAC,sBAAsB,EAAE,CAAC;QACzE,OAAO,IAAI,CAAC,wBAAwB,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,YAAY,CAAC,qBAAqB,EAAE,CAAC;QACpE,OAAO,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,qBAAqB,GACzB,KAAK,CAAC,UAAU,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC;IAC7F,IAAI,qBAAqB,IAAI,CAAC,YAAY,CAAC,qBAAqB,EAAE,CAAC;QACjE,OAAO,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,CAAyB,EAAE,CAAyB;IACjF,MAAM,SAAS,GAAW,CAAC,CAAC,QAAQ,CAAC,OAAO,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;IAClE,OAAO,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;AACvE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAA2B,EAAE,KAAmB;IACxF,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,EAAE,CAAC;QAC7D,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;QAC1E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9D,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,OAA4C,EAC5C,KAAmB;IAEnB,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,yBAAyB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACzG,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,OAA8C,EAC9C,KAAc;IAEd,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACf,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AACpE,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord, Kind, MemoryId, MemoryScopeKey, Tag } from '../types';\nimport { IIndexedMemoryRecord } from '../index';\n\n/**\n * The capabilities a retriever exposes. A consumer probes these before\n * dispatching a query so it never silently gets an empty result for a\n * capability the retriever does not implement.\n * @public\n */\nexport interface IMemoryRetrieverCapabilities {\n  /** Semantic / vector recall is operational (an {@link IVectorIndex} is wired). */\n  readonly supportsSemanticRecall: boolean;\n  /** Temporal \"as-of\" queries are operational (a temporal index is wired). */\n  readonly supportsTemporalQuery: boolean;\n  /** Link traversal is supported (an in-memory backlink index is present). */\n  readonly supportsLinkTraversal: boolean;\n}\n\n/**\n * A retrieval query. Every field is optional; an empty query is the \"recency\n * over everything\" request. `semantic` and `asOf` are present from day one (the\n * no-resignature guarantee): a backend that adds semantic or temporal recall\n * sets the matching capability flag, with no interface change.\n * @public\n */\nexport interface IMemoryQuery {\n  /** Restrict to records in this scope. */\n  readonly scope?: MemoryScopeKey;\n  /** Restrict to records carrying this tag (exact match). */\n  readonly tag?: Tag;\n  /** Restrict to records of this kind. */\n  readonly kind?: Kind;\n  /** Restrict to records linked FROM this id (outbound). */\n  readonly linkedFrom?: MemoryId;\n  /** Restrict to records linked TO this id (inbound / backlinks). */\n  readonly linkedTo?: MemoryId;\n  /** BFS hop count for link traversal. Default: 1. */\n  readonly hops?: number;\n  /**\n   * Text query for semantic / vector recall. If set and the retriever's\n   * `supportsSemanticRecall` is `false`, the retriever returns a loud\n   * `Result.fail` ({@link SEMANTIC_UNWIRED_MESSAGE}) — never a silent empty.\n   */\n  readonly semantic?: string;\n  /** Top-K for semantic recall. Default: 10. */\n  readonly topK?: number;\n  /**\n   * As-of epoch ms for temporal \"valid at\" queries. If set and the retriever's\n   * `supportsTemporalQuery` is `false`, the retriever returns a loud\n   * `Result.fail` — never a silent empty.\n   */\n  readonly asOf?: number;\n  /** Maximum records to return. Applied after all other filters. */\n  readonly limit?: number;\n  /** Arbitrary predicate applied after the scope / kind / tag pre-filter. */\n  readonly filter?: (record: IMemoryRecord<unknown>) => boolean;\n}\n\n/**\n * The retrieval contract. A retriever exposes its {@link\n * IMemoryRetrieverCapabilities | capabilities} and answers\n * {@link IMemoryRetriever.retrieve | queries}, degrading loudly (never silently\n * empty) when a requested capability is not wired.\n * @public\n */\nexport interface IMemoryRetriever {\n  /** The capabilities this retriever exposes. Probe before dispatch. */\n  readonly capabilities: IMemoryRetrieverCapabilities;\n  /**\n   * Retrieve records matching `query`. Returns a `Result.fail` with a\n   * diagnostic message when the query requests a capability this retriever does\n   * not support (never an empty success).\n   */\n  retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;\n}\n\n/**\n * The loud-degradation message a retriever returns when `query.semantic` is set\n * but no {@link IVectorIndex} is wired.\n * @public\n */\nexport const SEMANTIC_UNWIRED_MESSAGE: string = 'semantic recall requires a vector index; none configured';\n\n/**\n * The loud-degradation message a retriever returns when a link-traversal axis\n * (`linkedFrom` / `linkedTo` / `hops`) is requested but no backlink index is\n * wired.\n * @public\n */\nexport const LINK_TRAVERSAL_UNWIRED_MESSAGE: string =\n  'link traversal requires a backlink index; none configured';\n\n/**\n * The capabilities every non-semantic, non-temporal, non-link v1 retriever\n * exposes (all three flags `false`).\n * @public\n */\nexport const NON_SEMANTIC_CAPABILITIES: IMemoryRetrieverCapabilities = {\n  supportsSemanticRecall: false,\n  supportsTemporalQuery: false,\n  supportsLinkTraversal: false\n};\n\n/**\n * Build the loud-degradation message a retriever returns when `query.asOf` is\n * set but no temporal index is wired.\n * @public\n */\nexport function temporalUnwiredMessage(kind?: Kind): string {\n  return `temporal query requires temporal index; none configured${\n    kind !== undefined ? ` for kind ${kind}` : ''\n  }`;\n}\n\n/**\n * Enforce the loud-degradation contract for the `semantic` and `asOf` axes\n * against a retriever's `capabilities`: a requested capability the retriever\n * does not support fails loudly rather than returning a silent empty result.\n * @public\n */\nexport function guardRetrieverCapabilities(\n  query: IMemoryQuery,\n  capabilities: IMemoryRetrieverCapabilities\n): Result<true> {\n  if (query.semantic !== undefined && !capabilities.supportsSemanticRecall) {\n    return fail(SEMANTIC_UNWIRED_MESSAGE);\n  }\n  if (query.asOf !== undefined && !capabilities.supportsTemporalQuery) {\n    return fail(temporalUnwiredMessage(query.kind));\n  }\n  const requestsLinkTraversal: boolean =\n    query.linkedFrom !== undefined || query.linkedTo !== undefined || query.hops !== undefined;\n  if (requestsLinkTraversal && !capabilities.supportsLinkTraversal) {\n    return fail(LINK_TRAVERSAL_UNWIRED_MESSAGE);\n  }\n  return succeed(true);\n}\n\n/**\n * Recency comparator: most-recently-updated first, with a `seq` tiebreak so\n * equal-`updated` records sort deterministically. Mirrors the B1 index ordering.\n * @public\n */\nexport function recencyCompare(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number {\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 * Whether an indexed entry satisfies a query's scope / kind / tag / predicate\n * pre-filter (the axes shared by every v1 retriever). The `semantic` / `asOf` /\n * link axes are NOT applied here — those are each retriever's own concern.\n * @public\n */\nexport function indexedRecordMatchesQuery(entry: IIndexedMemoryRecord, query: IMemoryQuery): boolean {\n  if (query.scope !== undefined && entry.scope !== query.scope) {\n    return false;\n  }\n  if (query.kind !== undefined && entry.record.envelope.kind !== query.kind) {\n    return false;\n  }\n  if (query.tag !== undefined && !entry.record.envelope.tags.includes(query.tag)) {\n    return false;\n  }\n  if (query.filter !== undefined && !query.filter(entry.record)) {\n    return false;\n  }\n  return true;\n}\n\n/**\n * Apply the shared scope / kind / tag / predicate pre-filter to a set of indexed\n * entries, returning the surviving records (unordered, unlimited).\n * @public\n */\nexport function selectByQuery(\n  entries: ReadonlyArray<IIndexedMemoryRecord>,\n  query: IMemoryQuery\n): IMemoryRecord<unknown>[] {\n  return entries.filter((entry) => indexedRecordMatchesQuery(entry, query)).map((entry) => entry.record);\n}\n\n/**\n * Truncate to `query.limit` records (a no-op when `limit` is absent). Applied\n * last, after ordering, so it always takes the top-N of the ordered result. A\n * non-positive `limit` is public query input and means \"no records\" — it returns\n * an empty array rather than letting a negative value slip into `slice`.\n * @public\n */\nexport function limitRecords(\n  records: ReadonlyArray<IMemoryRecord<unknown>>,\n  limit?: number\n): ReadonlyArray<IMemoryRecord<unknown>> {\n  if (limit === undefined) {\n    return records;\n  }\n  if (limit <= 0) {\n    return [];\n  }\n  return records.length > limit ? records.slice(0, limit) : records;\n}\n"]}
+{"version":3,"file":"retriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/retriever.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport { IEdgeTarget, IMemoryRecord, Kind, MemoryScopeKey, Tag } from '../types';\nimport { IIndexedMemoryRecord } from '../index';\n\n/**\n * The capabilities a retriever exposes. A consumer probes these before\n * dispatching a query so it never silently gets an empty result for a\n * capability the retriever does not implement.\n * @public\n */\nexport interface IMemoryRetrieverCapabilities {\n  /** Semantic / vector recall is operational (an {@link IVectorIndex} is wired). */\n  readonly supportsSemanticRecall: boolean;\n  /** Temporal \"as-of\" queries are operational (a temporal index is wired). */\n  readonly supportsTemporalQuery: boolean;\n  /** Link traversal is supported (an in-memory backlink index is present). */\n  readonly supportsLinkTraversal: boolean;\n}\n\n/**\n * A retrieval query. Every field is optional; an empty query is the \"recency\n * over everything\" request. `semantic` and `asOf` are present from day one (the\n * no-resignature guarantee): a backend that adds semantic or temporal recall\n * sets the matching capability flag, with no interface change.\n * @public\n */\nexport interface IMemoryQuery {\n  /** Restrict to records in this scope. */\n  readonly scope?: MemoryScopeKey;\n  /** Restrict to records carrying this tag (exact match). */\n  readonly tag?: Tag;\n  /**\n   * Restrict to records of this kind — the single-kind shorthand for\n   * {@link IMemoryQuery.kinds | kinds}. When both are set they compose as AND\n   * (the record's kind must satisfy both), so `kind` must itself be a member of\n   * `kinds` for anything to match.\n   */\n  readonly kind?: Kind;\n  /**\n   * Restrict to records in ANY of these kinds — the general (multi-kind) form of\n   * {@link IMemoryQuery.kind | kind}. Absent → no kind-set constraint (today's\n   * behavior). An explicit empty array `[]` matches NOTHING (mirroring the\n   * non-positive-`limit` \"explicit empty\" convention), never \"match all\".\n   */\n  readonly kinds?: ReadonlyArray<Kind>;\n  /** Restrict to records linked FROM this scope-qualified seed (outbound). */\n  readonly linkedFrom?: IEdgeTarget;\n  /** Restrict to records linked TO this scope-qualified seed (inbound / backlinks). */\n  readonly linkedTo?: IEdgeTarget;\n  /** BFS hop count for link traversal. Default: 1. */\n  readonly hops?: number;\n  /**\n   * Text query for semantic / vector recall. If set and the retriever's\n   * `supportsSemanticRecall` is `false`, the retriever returns a loud\n   * `Result.fail` ({@link SEMANTIC_UNWIRED_MESSAGE}) — never a silent empty.\n   */\n  readonly semantic?: string;\n  /** Top-K for semantic recall. Default: 10. */\n  readonly topK?: number;\n  /**\n   * As-of epoch ms for temporal \"valid at\" queries. If set and the retriever's\n   * `supportsTemporalQuery` is `false`, the retriever returns a loud\n   * `Result.fail` — never a silent empty.\n   */\n  readonly asOf?: number;\n  /**\n   * Ordering for the result set. `'recency'` (the default when absent — today's\n   * exact behavior) orders most-recently-updated first; `'rank'` orders by the\n   * store-computed {@link IMemoryEnvelope.rank} descending (records with an absent\n   * `rank` last), with recency as the tiebreak. Combined with `{ limit, offset }`\n   * this yields a bounded top-M rank-ordered page with no full-vault scan.\n   *\n   * @remarks\n   * `orderBy` governs the ordered non-semantic retrievers (recency / tag /\n   * structured-filter / link-traversal) and the {@link HybridRetriever}'s\n   * post-merge ordering. The {@link SemanticRetriever} is the sole exception: it\n   * preserves its native vector-similarity order regardless of `orderBy` —\n   * re-sorting semantic hits by `rank` would discard the similarity ranking that\n   * is the whole point of that path; a consumer that wants rank ordering uses a\n   * non-semantic query.\n   */\n  readonly orderBy?: 'recency' | 'rank';\n  /** Maximum records to return. Applied after all other filters. */\n  readonly limit?: number;\n  /**\n   * Records to skip after ordering, before `limit` — so `{ offset, limit }` is a\n   * stable page window over the ordered result set. Default 0. A non-positive or\n   * absent offset is today's behavior (no skip); an offset past the end yields an\n   * empty page, never a throw.\n   */\n  readonly offset?: number;\n  /** Arbitrary predicate applied after the scope / kind / tag pre-filter. */\n  readonly filter?: (record: IMemoryRecord<unknown>) => boolean;\n}\n\n/**\n * The retrieval contract. A retriever exposes its {@link\n * IMemoryRetrieverCapabilities | capabilities} and answers\n * {@link IMemoryRetriever.retrieve | queries}, degrading loudly (never silently\n * empty) when a requested capability is not wired.\n * @public\n */\nexport interface IMemoryRetriever {\n  /** The capabilities this retriever exposes. Probe before dispatch. */\n  readonly capabilities: IMemoryRetrieverCapabilities;\n  /**\n   * Retrieve records matching `query`. Returns a `Result.fail` with a\n   * diagnostic message when the query requests a capability this retriever does\n   * not support (never an empty success).\n   */\n  retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;\n}\n\n/**\n * The loud-degradation message a retriever returns when `query.semantic` is set\n * but no {@link IVectorIndex} is wired.\n * @public\n */\nexport const SEMANTIC_UNWIRED_MESSAGE: string = 'semantic recall requires a vector index; none configured';\n\n/**\n * The loud-degradation message a retriever returns when a link-traversal axis\n * (`linkedFrom` / `linkedTo` / `hops`) is requested but no backlink index is\n * wired.\n * @public\n */\nexport const LINK_TRAVERSAL_UNWIRED_MESSAGE: string =\n  'link traversal requires a backlink index; none configured';\n\n/**\n * The capabilities every non-semantic, non-temporal, non-link v1 retriever\n * exposes (all three flags `false`).\n * @public\n */\nexport const NON_SEMANTIC_CAPABILITIES: IMemoryRetrieverCapabilities = {\n  supportsSemanticRecall: false,\n  supportsTemporalQuery: false,\n  supportsLinkTraversal: false\n};\n\n/**\n * Build the loud-degradation message a retriever returns when `query.asOf` is\n * set but no temporal index is wired.\n * @public\n */\nexport function temporalUnwiredMessage(kind?: Kind): string {\n  return `temporal query requires temporal index; none configured${\n    kind !== undefined ? ` for kind ${kind}` : ''\n  }`;\n}\n\n/**\n * Enforce the loud-degradation contract for the `semantic` and `asOf` axes\n * against a retriever's `capabilities`: a requested capability the retriever\n * does not support fails loudly rather than returning a silent empty result.\n * @public\n */\nexport function guardRetrieverCapabilities(\n  query: IMemoryQuery,\n  capabilities: IMemoryRetrieverCapabilities\n): Result<true> {\n  if (query.semantic !== undefined && !capabilities.supportsSemanticRecall) {\n    return fail(SEMANTIC_UNWIRED_MESSAGE);\n  }\n  if (query.asOf !== undefined && !capabilities.supportsTemporalQuery) {\n    return fail(temporalUnwiredMessage(query.kind));\n  }\n  const requestsLinkTraversal: boolean =\n    query.linkedFrom !== undefined || query.linkedTo !== undefined || query.hops !== undefined;\n  if (requestsLinkTraversal && !capabilities.supportsLinkTraversal) {\n    return fail(LINK_TRAVERSAL_UNWIRED_MESSAGE);\n  }\n  return succeed(true);\n}\n\n/**\n * Recency comparator: most-recently-updated first, with a `seq` tiebreak so\n * equal-`updated` records sort deterministically. Mirrors the B1 index ordering.\n * @public\n */\nexport function recencyCompare(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number {\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 * Rank comparator: store-computed {@link IMemoryEnvelope.rank} descending, with\n * {@link recencyCompare} as the tiebreak. Records with an absent `rank` sort LAST\n * (after every ranked record), then by recency among themselves. Mirrors the\n * index's rank-view ordering.\n * @public\n */\nexport function rankCompare(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number {\n  const ra: number | undefined = a.envelope.rank;\n  const rb: number | undefined = b.envelope.rank;\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  return recencyCompare(a, b);\n}\n\n/**\n * Select the record comparator for a query's {@link IMemoryQuery.orderBy | orderBy}\n * axis: {@link rankCompare} for `'rank'`, {@link recencyCompare} otherwise (the\n * default, byte-identical to the pre-`orderBy` behavior).\n * @public\n */\nexport function orderingCompare(\n  orderBy?: IMemoryQuery['orderBy']\n): (a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>) => number {\n  return orderBy === 'rank' ? rankCompare : recencyCompare;\n}\n\n/**\n * Whether an indexed entry satisfies a query's scope / kind / tag / predicate\n * pre-filter (the axes shared by every v1 retriever). The `semantic` / `asOf` /\n * link axes are NOT applied here — those are each retriever's own concern.\n * @public\n */\nexport function indexedRecordMatchesQuery(entry: IIndexedMemoryRecord, query: IMemoryQuery): boolean {\n  if (query.scope !== undefined && entry.scope !== query.scope) {\n    return false;\n  }\n  if (query.kind !== undefined && entry.record.envelope.kind !== query.kind) {\n    return false;\n  }\n  if (query.kinds !== undefined && !query.kinds.includes(entry.record.envelope.kind)) {\n    return false;\n  }\n  if (query.tag !== undefined && !entry.record.envelope.tags.includes(query.tag)) {\n    return false;\n  }\n  if (query.filter !== undefined && !query.filter(entry.record)) {\n    return false;\n  }\n  return true;\n}\n\n/**\n * Apply the shared scope / kind / tag / predicate pre-filter to a set of indexed\n * entries, returning the surviving records (unordered, unlimited).\n * @public\n */\nexport function selectByQuery(\n  entries: ReadonlyArray<IIndexedMemoryRecord>,\n  query: IMemoryQuery\n): IMemoryRecord<unknown>[] {\n  return entries.filter((entry) => indexedRecordMatchesQuery(entry, query)).map((entry) => entry.record);\n}\n\n/**\n * Apply the `{ offset, limit }` page window to an ordered record set. Applied\n * last, after ordering, so it always takes a stable window of the ordered\n * result. `offset` is applied first (records to skip), then `limit` (top-N of\n * the remainder).\n *\n * @remarks\n * Both bounds are public query input and are guarded against non-positive\n * values slipping into `slice`:\n * - `offset` absent or non-positive → no skip (today's behavior). An offset past\n *   the end yields an empty page rather than a throw.\n * - `limit` absent → no truncation; a non-positive `limit` means \"no records\"\n *   and returns an empty array.\n * @public\n */\nexport function limitRecords(\n  records: ReadonlyArray<IMemoryRecord<unknown>>,\n  limit?: number,\n  offset?: number\n): ReadonlyArray<IMemoryRecord<unknown>> {\n  const skip: number = offset !== undefined && offset > 0 ? offset : 0;\n  const windowed: ReadonlyArray<IMemoryRecord<unknown>> = skip > 0 ? records.slice(skip) : records;\n  if (limit === undefined) {\n    return windowed;\n  }\n  if (limit <= 0) {\n    return [];\n  }\n  return windowed.length > limit ? windowed.slice(0, limit) : windowed;\n}\n"]}

package/dist/packlets/retrieve/semanticRetriever.js

@@ -3,6 +3,7 @@
  * SPDX-License-Identifier: MIT
  */
 import { fail, succeed } from '@fgv/ts-utils';
+import { edgeTargetKey } from '../types';
 import { SEMANTIC_UNWIRED_MESSAGE, indexedRecordMatchesQuery, limitRecords, temporalUnwiredMessage } from './retriever';
 /**
  * Vector-recall retriever. When a {@link ISemanticBackend | backend} is wired it
@@ -58,15 +59,20 @@ export class SemanticRetriever {
         if (hits.isFailure()) {
             return fail(hits.message);
         }
-        const byId = new Map(this._index.entries().map((entry) => [entry.record.envelope.id, entry]));
+        // Key by the canonical scope-qualified target so a hit re-resolves to the
+        // exact record it scored against — a bare id would alias two records that
+        // share a filename stem across scopes.
+        const byKey = new Map(this._index
+            .entries()
+            .map((entry) => [edgeTargetKey({ scope: entry.scope, id: entry.record.envelope.id }), entry]));
         const records = [];
         for (const hit of hits.value) {
-            const entry = byId.get(hit.id);
+            const entry = byKey.get(edgeTargetKey(hit.target));
             if (entry !== undefined && indexedRecordMatchesQuery(entry, query)) {
                 records.push(entry.record);
             }
         }
-        return succeed(limitRecords(records, query.limit));
+        return succeed(limitRecords(records, query.limit, query.offset));
     }
     /**
      * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`

package/dist/packlets/retrieve/semanticRetriever.js.map

@@ -1 +1 @@
-{"version":3,"file":"semanticRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/semanticRetriever.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord, MemoryId } from '../types';\nimport { IIndexedMemoryRecord, IMemoryIndex } from '../index';\nimport { IVectorIndex, IVectorQueryHit } from '../vector';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  SEMANTIC_UNWIRED_MESSAGE,\n  indexedRecordMatchesQuery,\n  limitRecords,\n  temporalUnwiredMessage\n} from './retriever';\n\n/**\n * Embeds a query string into a vector for {@link IVectorIndex.query}. Async and\n * `Result`-returning, since a real embedder does a network call.\n * @public\n */\nexport type QueryEmbedder = (text: string) => Promise<Result<Float32Array>>;\n\n/**\n * The semantic backend wired into a {@link SemanticRetriever}: the vector index\n * to query and the embedder that turns the query text into a vector. Both are\n * required together — a vector index is useless without a way to embed the\n * query, so {@link SemanticRetriever.create} treats them as one unit.\n * @public\n */\nexport interface ISemanticBackend {\n  /** The vector index to query. */\n  readonly vectorIndex: IVectorIndex;\n  /** Turns the query text into a vector. */\n  readonly embedQuery: QueryEmbedder;\n}\n\n/**\n * Construction options for {@link SemanticRetriever.create}.\n * @public\n */\nexport interface ISemanticRetrieverCreateParams {\n  /** The record index, used to resolve vector hits back to full records. */\n  readonly index: IMemoryIndex;\n  /**\n   * The semantic backend. When absent, the retriever reports\n   * `supportsSemanticRecall: false` and a `query.semantic` request degrades\n   * loudly ({@link SEMANTIC_UNWIRED_MESSAGE}) rather than returning empty.\n   */\n  readonly backend?: ISemanticBackend;\n}\n\n/**\n * Vector-recall retriever. When a {@link ISemanticBackend | backend} is wired it\n * embeds `query.semantic`, queries the vector index, and resolves the hits back\n * to records (preserving vector score order). When no backend is wired,\n * `supportsSemanticRecall` is `false` and any `query.semantic` request degrades\n * loudly — it NEVER returns a silent empty.\n *\n * @remarks\n * A consumer-supplied backend that rejects (throws) is normalized into a\n * `Failure` — `retrieve` always honors its `Promise<Result<...>>` contract.\n * @public\n */\nexport class SemanticRetriever implements IMemoryRetriever {\n  private readonly _index: IMemoryIndex;\n  private readonly _backend: ISemanticBackend | undefined;\n\n  private constructor(index: IMemoryIndex, backend: ISemanticBackend | undefined) {\n    this._index = index;\n    this._backend = backend;\n  }\n\n  /** {@inheritDoc IMemoryRetriever.capabilities} */\n  public get capabilities(): IMemoryRetrieverCapabilities {\n    return {\n      supportsSemanticRecall: this._backend !== undefined,\n      supportsTemporalQuery: false,\n      supportsLinkTraversal: false\n    };\n  }\n\n  /** Family-convention factory. */\n  public static create(params: ISemanticRetrieverCreateParams): Result<SemanticRetriever> {\n    return succeed(new SemanticRetriever(params.index, params.backend));\n  }\n\n  /** {@inheritDoc IMemoryRetriever.retrieve} */\n  public async retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {\n    if (query.asOf !== undefined) {\n      return fail(temporalUnwiredMessage(query.kind));\n    }\n    if (query.semantic === undefined) {\n      // The semantic term is this retriever's axis; without it there is nothing\n      // to recall (a no-op contribution to a HybridRetriever, not a failure).\n      return succeed([]);\n    }\n    if (this._backend === undefined) {\n      return fail(SEMANTIC_UNWIRED_MESSAGE);\n    }\n    const backend: ISemanticBackend = this._backend;\n    // The backend hooks are consumer-supplied; a rejecting (throwing) impl must\n    // still surface as a `Failure`, never escape `retrieve` as a rejected\n    // promise. `_callBackend` normalizes both a returned `fail` and a rejection.\n    const embedded: Result<Float32Array> = await SemanticRetriever._callBackend('query embedding', () =>\n      backend.embedQuery(query.semantic as string)\n    );\n    if (embedded.isFailure()) {\n      return fail(embedded.message);\n    }\n    const hits: Result<ReadonlyArray<IVectorQueryHit>> = await SemanticRetriever._callBackend(\n      'vector query',\n      () => backend.vectorIndex.query(embedded.value, query.topK ?? 10)\n    );\n    if (hits.isFailure()) {\n      return fail(hits.message);\n    }\n    const byId: Map<MemoryId, IIndexedMemoryRecord> = new Map(\n      this._index.entries().map((entry) => [entry.record.envelope.id, entry])\n    );\n    const records: IMemoryRecord<unknown>[] = [];\n    for (const hit of hits.value) {\n      const entry: IIndexedMemoryRecord | undefined = byId.get(hit.id);\n      if (entry !== undefined && indexedRecordMatchesQuery(entry, query)) {\n        records.push(entry.record);\n      }\n    }\n    return succeed(limitRecords(records, query.limit));\n  }\n\n  /**\n   * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`\n   * and a thrown/rejected promise into a single `semantic recall: <label> failed`\n   * `Failure`. Keeps `retrieve` within the `Promise<Result<...>>` contract even\n   * when the injected `embedQuery` / `vectorIndex` misbehaves.\n   */\n  private static async _callBackend<T>(label: string, op: () => Promise<Result<T>>): Promise<Result<T>> {\n    try {\n      return (await op()).withErrorFormat((msg) => `semantic recall: ${label} failed: ${msg}`);\n    } catch (err) {\n      return fail(`semantic recall: ${label} failed: ${String(err)}`);\n    }\n  }\n}\n"]}
+{"version":3,"file":"semanticRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/semanticRetriever.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord, edgeTargetKey } from '../types';\nimport { IIndexedMemoryRecord, IMemoryIndex } from '../index';\nimport { IVectorIndex, IVectorQueryHit } from '../vector';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  SEMANTIC_UNWIRED_MESSAGE,\n  indexedRecordMatchesQuery,\n  limitRecords,\n  temporalUnwiredMessage\n} from './retriever';\n\n/**\n * Embeds a query string into a vector for {@link IVectorIndex.query}. Async and\n * `Result`-returning, since a real embedder does a network call.\n * @public\n */\nexport type QueryEmbedder = (text: string) => Promise<Result<Float32Array>>;\n\n/**\n * The semantic backend wired into a {@link SemanticRetriever}: the vector index\n * to query and the embedder that turns the query text into a vector. Both are\n * required together — a vector index is useless without a way to embed the\n * query, so {@link SemanticRetriever.create} treats them as one unit.\n * @public\n */\nexport interface ISemanticBackend {\n  /** The vector index to query. */\n  readonly vectorIndex: IVectorIndex;\n  /** Turns the query text into a vector. */\n  readonly embedQuery: QueryEmbedder;\n}\n\n/**\n * Construction options for {@link SemanticRetriever.create}.\n * @public\n */\nexport interface ISemanticRetrieverCreateParams {\n  /** The record index, used to resolve vector hits back to full records. */\n  readonly index: IMemoryIndex;\n  /**\n   * The semantic backend. When absent, the retriever reports\n   * `supportsSemanticRecall: false` and a `query.semantic` request degrades\n   * loudly ({@link SEMANTIC_UNWIRED_MESSAGE}) rather than returning empty.\n   */\n  readonly backend?: ISemanticBackend;\n}\n\n/**\n * Vector-recall retriever. When a {@link ISemanticBackend | backend} is wired it\n * embeds `query.semantic`, queries the vector index, and resolves the hits back\n * to records (preserving vector score order). When no backend is wired,\n * `supportsSemanticRecall` is `false` and any `query.semantic` request degrades\n * loudly — it NEVER returns a silent empty.\n *\n * @remarks\n * A consumer-supplied backend that rejects (throws) is normalized into a\n * `Failure` — `retrieve` always honors its `Promise<Result<...>>` contract.\n * @public\n */\nexport class SemanticRetriever implements IMemoryRetriever {\n  private readonly _index: IMemoryIndex;\n  private readonly _backend: ISemanticBackend | undefined;\n\n  private constructor(index: IMemoryIndex, backend: ISemanticBackend | undefined) {\n    this._index = index;\n    this._backend = backend;\n  }\n\n  /** {@inheritDoc IMemoryRetriever.capabilities} */\n  public get capabilities(): IMemoryRetrieverCapabilities {\n    return {\n      supportsSemanticRecall: this._backend !== undefined,\n      supportsTemporalQuery: false,\n      supportsLinkTraversal: false\n    };\n  }\n\n  /** Family-convention factory. */\n  public static create(params: ISemanticRetrieverCreateParams): Result<SemanticRetriever> {\n    return succeed(new SemanticRetriever(params.index, params.backend));\n  }\n\n  /** {@inheritDoc IMemoryRetriever.retrieve} */\n  public async retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {\n    if (query.asOf !== undefined) {\n      return fail(temporalUnwiredMessage(query.kind));\n    }\n    if (query.semantic === undefined) {\n      // The semantic term is this retriever's axis; without it there is nothing\n      // to recall (a no-op contribution to a HybridRetriever, not a failure).\n      return succeed([]);\n    }\n    if (this._backend === undefined) {\n      return fail(SEMANTIC_UNWIRED_MESSAGE);\n    }\n    const backend: ISemanticBackend = this._backend;\n    // The backend hooks are consumer-supplied; a rejecting (throwing) impl must\n    // still surface as a `Failure`, never escape `retrieve` as a rejected\n    // promise. `_callBackend` normalizes both a returned `fail` and a rejection.\n    const embedded: Result<Float32Array> = await SemanticRetriever._callBackend('query embedding', () =>\n      backend.embedQuery(query.semantic as string)\n    );\n    if (embedded.isFailure()) {\n      return fail(embedded.message);\n    }\n    const hits: Result<ReadonlyArray<IVectorQueryHit>> = await SemanticRetriever._callBackend(\n      'vector query',\n      () => backend.vectorIndex.query(embedded.value, query.topK ?? 10)\n    );\n    if (hits.isFailure()) {\n      return fail(hits.message);\n    }\n    // Key by the canonical scope-qualified target so a hit re-resolves to the\n    // exact record it scored against — a bare id would alias two records that\n    // share a filename stem across scopes.\n    const byKey: Map<string, IIndexedMemoryRecord> = new Map(\n      this._index\n        .entries()\n        .map((entry) => [edgeTargetKey({ scope: entry.scope, id: entry.record.envelope.id }), entry])\n    );\n    const records: IMemoryRecord<unknown>[] = [];\n    for (const hit of hits.value) {\n      const entry: IIndexedMemoryRecord | undefined = byKey.get(edgeTargetKey(hit.target));\n      if (entry !== undefined && indexedRecordMatchesQuery(entry, query)) {\n        records.push(entry.record);\n      }\n    }\n    return succeed(limitRecords(records, query.limit, query.offset));\n  }\n\n  /**\n   * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`\n   * and a thrown/rejected promise into a single `semantic recall: <label> failed`\n   * `Failure`. Keeps `retrieve` within the `Promise<Result<...>>` contract even\n   * when the injected `embedQuery` / `vectorIndex` misbehaves.\n   */\n  private static async _callBackend<T>(label: string, op: () => Promise<Result<T>>): Promise<Result<T>> {\n    try {\n      return (await op()).withErrorFormat((msg) => `semantic recall: ${label} failed: ${msg}`);\n    } catch (err) {\n      return fail(`semantic recall: ${label} failed: ${String(err)}`);\n    }\n  }\n}\n"]}

package/dist/packlets/retrieve/structuredFilterRetriever.js

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: MIT
  */
 import { succeed } from '@fgv/ts-utils';
-import { NON_SEMANTIC_CAPABILITIES, guardRetrieverCapabilities, limitRecords, recencyCompare, selectByQuery } from './retriever';
+import { NON_SEMANTIC_CAPABILITIES, guardRetrieverCapabilities, limitRecords, orderingCompare, selectByQuery } from './retriever';
 /**
  * Returns records matching `query.filter`, narrowed by any scope / kind / tag
  * pre-filter and recency-ordered. The predicate is this retriever's axis: a
@@ -29,8 +29,8 @@ export class StructuredFilterRetriever {
             if (query.filter === undefined) {
                 return succeed([]);
             }
-            const ordered = selectByQuery(this._index.entries(), query).sort(recencyCompare);
-            return succeed(limitRecords(ordered, query.limit));
+            const ordered = selectByQuery(this._index.entries(), query).sort(orderingCompare(query.orderBy));
+            return succeed(limitRecords(ordered, query.limit, query.offset));
         }));
     }
 }

package/dist/packlets/retrieve/structuredFilterRetriever.js.map

@@ -1 +1 @@
-{"version":3,"file":"structuredFilterRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/structuredFilterRetriever.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,OAAO,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAIL,yBAAyB,EACzB,0BAA0B,EAC1B,YAAY,EACZ,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,OAAO,yBAAyB;IAGpC,YAAoB,KAAmB;QACrC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,kDAAkD;IAClD,IAAW,YAAY;QACrB,OAAO,yBAAyB,CAAC;IACnC,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM,CAAC,KAAmB;QACtC,OAAO,OAAO,CAAC,IAAI,yBAAyB,CAAC,KAAK,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,8CAA8C;IACvC,QAAQ,CAAC,KAAmB;QACjC,OAAO,OAAO,CAAC,OAAO,CACpB,0BAA0B,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE;YAClE,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC/B,OAAO,OAAO,CAAC,EAAE,CAAC,CAAC;YACrB,CAAC;YACD,MAAM,OAAO,GAA6B,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC,IAAI,CACxF,cAAc,CACf,CAAC;YACF,OAAO,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QACrD,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord } from '../types';\nimport { IMemoryIndex } from '../index';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  NON_SEMANTIC_CAPABILITIES,\n  guardRetrieverCapabilities,\n  limitRecords,\n  recencyCompare,\n  selectByQuery\n} from './retriever';\n\n/**\n * Returns records matching `query.filter`, narrowed by any scope / kind / tag\n * pre-filter and recency-ordered. The predicate is this retriever's axis: a\n * query without a `filter` is not its concern and yields an empty success (so it\n * contributes nothing to a {@link HybridRetriever}, rather than failing).\n * @public\n */\nexport class StructuredFilterRetriever implements IMemoryRetriever {\n  private readonly _index: IMemoryIndex;\n\n  private constructor(index: IMemoryIndex) {\n    this._index = index;\n  }\n\n  /** {@inheritDoc IMemoryRetriever.capabilities} */\n  public get capabilities(): IMemoryRetrieverCapabilities {\n    return NON_SEMANTIC_CAPABILITIES;\n  }\n\n  /** Family-convention factory. */\n  public static create(index: IMemoryIndex): Result<StructuredFilterRetriever> {\n    return succeed(new StructuredFilterRetriever(index));\n  }\n\n  /** {@inheritDoc IMemoryRetriever.retrieve} */\n  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {\n    return Promise.resolve(\n      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => {\n        if (query.filter === undefined) {\n          return succeed([]);\n        }\n        const ordered: IMemoryRecord<unknown>[] = selectByQuery(this._index.entries(), query).sort(\n          recencyCompare\n        );\n        return succeed(limitRecords(ordered, query.limit));\n      })\n    );\n  }\n}\n"]}
+{"version":3,"file":"structuredFilterRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/structuredFilterRetriever.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,OAAO,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAIL,yBAAyB,EACzB,0BAA0B,EAC1B,YAAY,EACZ,eAAe,EACf,aAAa,EACd,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,OAAO,yBAAyB;IAGpC,YAAoB,KAAmB;QACrC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,kDAAkD;IAClD,IAAW,YAAY;QACrB,OAAO,yBAAyB,CAAC;IACnC,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM,CAAC,KAAmB;QACtC,OAAO,OAAO,CAAC,IAAI,yBAAyB,CAAC,KAAK,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,8CAA8C;IACvC,QAAQ,CAAC,KAAmB;QACjC,OAAO,OAAO,CAAC,OAAO,CACpB,0BAA0B,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE;YAClE,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC/B,OAAO,OAAO,CAAC,EAAE,CAAC,CAAC;YACrB,CAAC;YACD,MAAM,OAAO,GAA6B,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC,IAAI,CACxF,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,CAC/B,CAAC;YACF,OAAO,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QACnE,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord } from '../types';\nimport { IMemoryIndex } from '../index';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  NON_SEMANTIC_CAPABILITIES,\n  guardRetrieverCapabilities,\n  limitRecords,\n  orderingCompare,\n  selectByQuery\n} from './retriever';\n\n/**\n * Returns records matching `query.filter`, narrowed by any scope / kind / tag\n * pre-filter and recency-ordered. The predicate is this retriever's axis: a\n * query without a `filter` is not its concern and yields an empty success (so it\n * contributes nothing to a {@link HybridRetriever}, rather than failing).\n * @public\n */\nexport class StructuredFilterRetriever implements IMemoryRetriever {\n  private readonly _index: IMemoryIndex;\n\n  private constructor(index: IMemoryIndex) {\n    this._index = index;\n  }\n\n  /** {@inheritDoc IMemoryRetriever.capabilities} */\n  public get capabilities(): IMemoryRetrieverCapabilities {\n    return NON_SEMANTIC_CAPABILITIES;\n  }\n\n  /** Family-convention factory. */\n  public static create(index: IMemoryIndex): Result<StructuredFilterRetriever> {\n    return succeed(new StructuredFilterRetriever(index));\n  }\n\n  /** {@inheritDoc IMemoryRetriever.retrieve} */\n  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {\n    return Promise.resolve(\n      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => {\n        if (query.filter === undefined) {\n          return succeed([]);\n        }\n        const ordered: IMemoryRecord<unknown>[] = selectByQuery(this._index.entries(), query).sort(\n          orderingCompare(query.orderBy)\n        );\n        return succeed(limitRecords(ordered, query.limit, query.offset));\n      })\n    );\n  }\n}\n"]}

package/dist/packlets/retrieve/tagRetriever.js

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: MIT
  */
 import { succeed } from '@fgv/ts-utils';
-import { NON_SEMANTIC_CAPABILITIES, guardRetrieverCapabilities, limitRecords, recencyCompare, selectByQuery } from './retriever';
+import { NON_SEMANTIC_CAPABILITIES, guardRetrieverCapabilities, limitRecords, orderingCompare, selectByQuery } from './retriever';
 /**
  * Returns records carrying `query.tag`, recency-ordered within the tag and
  * narrowed by any scope / kind / predicate filters. Tag is this retriever's
@@ -29,8 +29,8 @@ export class TagRetriever {
             if (query.tag === undefined) {
                 return succeed([]);
             }
-            const ordered = selectByQuery(this._index.entries(), query).sort(recencyCompare);
-            return succeed(limitRecords(ordered, query.limit));
+            const ordered = selectByQuery(this._index.entries(), query).sort(orderingCompare(query.orderBy));
+            return succeed(limitRecords(ordered, query.limit, query.offset));
         }));
     }
 }

package/dist/packlets/retrieve/tagRetriever.js.map

@@ -1 +1 @@
-{"version":3,"file":"tagRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/tagRetriever.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,OAAO,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAIL,yBAAyB,EACzB,0BAA0B,EAC1B,YAAY,EACZ,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IAGvB,YAAoB,KAAmB;QACrC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,kDAAkD;IAClD,IAAW,YAAY;QACrB,OAAO,yBAAyB,CAAC;IACnC,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM,CAAC,KAAmB;QACtC,OAAO,OAAO,CAAC,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED,8CAA8C;IACvC,QAAQ,CAAC,KAAmB;QACjC,OAAO,OAAO,CAAC,OAAO,CACpB,0BAA0B,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE;YAClE,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;gBAC5B,OAAO,OAAO,CAAC,EAAE,CAAC,CAAC;YACrB,CAAC;YACD,MAAM,OAAO,GAA6B,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC,IAAI,CACxF,cAAc,CACf,CAAC;YACF,OAAO,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QACrD,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord } from '../types';\nimport { IMemoryIndex } from '../index';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  NON_SEMANTIC_CAPABILITIES,\n  guardRetrieverCapabilities,\n  limitRecords,\n  recencyCompare,\n  selectByQuery\n} from './retriever';\n\n/**\n * Returns records carrying `query.tag`, recency-ordered within the tag and\n * narrowed by any scope / kind / predicate filters. Tag is this retriever's\n * axis: a query without a `tag` is not its concern and yields an empty success\n * (so it contributes nothing to a {@link HybridRetriever}, rather than failing).\n * @public\n */\nexport class TagRetriever implements IMemoryRetriever {\n  private readonly _index: IMemoryIndex;\n\n  private constructor(index: IMemoryIndex) {\n    this._index = index;\n  }\n\n  /** {@inheritDoc IMemoryRetriever.capabilities} */\n  public get capabilities(): IMemoryRetrieverCapabilities {\n    return NON_SEMANTIC_CAPABILITIES;\n  }\n\n  /** Family-convention factory. */\n  public static create(index: IMemoryIndex): Result<TagRetriever> {\n    return succeed(new TagRetriever(index));\n  }\n\n  /** {@inheritDoc IMemoryRetriever.retrieve} */\n  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {\n    return Promise.resolve(\n      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => {\n        if (query.tag === undefined) {\n          return succeed([]);\n        }\n        const ordered: IMemoryRecord<unknown>[] = selectByQuery(this._index.entries(), query).sort(\n          recencyCompare\n        );\n        return succeed(limitRecords(ordered, query.limit));\n      })\n    );\n  }\n}\n"]}
+{"version":3,"file":"tagRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/tagRetriever.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,OAAO,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAIL,yBAAyB,EACzB,0BAA0B,EAC1B,YAAY,EACZ,eAAe,EACf,aAAa,EACd,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IAGvB,YAAoB,KAAmB;QACrC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,kDAAkD;IAClD,IAAW,YAAY;QACrB,OAAO,yBAAyB,CAAC;IACnC,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM,CAAC,KAAmB;QACtC,OAAO,OAAO,CAAC,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED,8CAA8C;IACvC,QAAQ,CAAC,KAAmB;QACjC,OAAO,OAAO,CAAC,OAAO,CACpB,0BAA0B,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE;YAClE,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;gBAC5B,OAAO,OAAO,CAAC,EAAE,CAAC,CAAC;YACrB,CAAC;YACD,MAAM,OAAO,GAA6B,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC,IAAI,CACxF,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,CAC/B,CAAC;YACF,OAAO,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QACnE,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord } from '../types';\nimport { IMemoryIndex } from '../index';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  NON_SEMANTIC_CAPABILITIES,\n  guardRetrieverCapabilities,\n  limitRecords,\n  orderingCompare,\n  selectByQuery\n} from './retriever';\n\n/**\n * Returns records carrying `query.tag`, recency-ordered within the tag and\n * narrowed by any scope / kind / predicate filters. Tag is this retriever's\n * axis: a query without a `tag` is not its concern and yields an empty success\n * (so it contributes nothing to a {@link HybridRetriever}, rather than failing).\n * @public\n */\nexport class TagRetriever implements IMemoryRetriever {\n  private readonly _index: IMemoryIndex;\n\n  private constructor(index: IMemoryIndex) {\n    this._index = index;\n  }\n\n  /** {@inheritDoc IMemoryRetriever.capabilities} */\n  public get capabilities(): IMemoryRetrieverCapabilities {\n    return NON_SEMANTIC_CAPABILITIES;\n  }\n\n  /** Family-convention factory. */\n  public static create(index: IMemoryIndex): Result<TagRetriever> {\n    return succeed(new TagRetriever(index));\n  }\n\n  /** {@inheritDoc IMemoryRetriever.retrieve} */\n  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {\n    return Promise.resolve(\n      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => {\n        if (query.tag === undefined) {\n          return succeed([]);\n        }\n        const ordered: IMemoryRecord<unknown>[] = selectByQuery(this._index.entries(), query).sort(\n          orderingCompare(query.orderBy)\n        );\n        return succeed(limitRecords(ordered, query.limit, query.offset));\n      })\n    );\n  }\n}\n"]}