@fgv/ts-agent-memory 5.1.0-36

package/lib/packlets/retrieve/hybridRetriever.d.ts

@@ -0,0 +1,79 @@
+import { Result } from '@fgv/ts-utils';
+import { IMemoryRecord } from '../types';
+import { IMemoryQuery, IMemoryRetriever, IMemoryRetrieverCapabilities } from './retriever';
+/**
+ * Strategy for combining the result sets of the retrievers a
+ * {@link HybridRetriever} composes. Injectable so a consumer can weight,
+ * re-rank, or intersect instead of the default union.
+ * @public
+ */
+export interface IMergeStrategy {
+    /**
+     * Merge the per-retriever result sets into a single ordered result.
+     * @param resultSets - One entry per composed retriever, in composition order.
+     */
+    merge(resultSets: ReadonlyArray<ReadonlyArray<IMemoryRecord<unknown>>>): Result<ReadonlyArray<IMemoryRecord<unknown>>>;
+}
+/**
+ * The reference {@link IMergeStrategy}: a score-union. Every record is scored by
+ * the number of composed result sets it appears in (deduplicated by
+ * {@link IMemoryEnvelope.id | id}); the merged result is ordered by descending
+ * score, then by recency. Records surfaced by more retrievers rank higher.
+ *
+ * @remarks
+ * Dedup is by `id` alone, which is unambiguous for the flat (one-file-per-entity)
+ * kinds B2 ships. Phase-C versioned kinds that reuse a stem across scopes will
+ * extend the dedup key — additive, no API change.
+ * @public
+ */
+export declare class ScoreUnionMergeStrategy implements IMergeStrategy {
+    private constructor();
+    /** Family-convention factory. */
+    static create(): Result<ScoreUnionMergeStrategy>;
+    /** {@inheritDoc IMergeStrategy.merge} */
+    merge(resultSets: ReadonlyArray<ReadonlyArray<IMemoryRecord<unknown>>>): Result<ReadonlyArray<IMemoryRecord<unknown>>>;
+}
+/**
+ * Composes several retrievers, dispatches a query to each, and merges their
+ * results via an injectable {@link IMergeStrategy}. Its capabilities are the
+ * union of the composed retrievers' capabilities.
+ *
+ * @remarks
+ * The hybrid enforces the loud-degradation contract against its OWN (union)
+ * capabilities, then projects the query for each child: a child that does not
+ * support the `semantic` (or `asOf`) axis is handed a query with that axis
+ * stripped, so it returns its normal results instead of loud-failing on a field
+ * a sibling handles. A child that genuinely fails (e.g. a wired semantic backend
+ * erroring) propagates — the hybrid never silently drops a failure.
+ * @public
+ */
+export declare class HybridRetriever implements IMemoryRetriever {
+    private readonly _retrievers;
+    private readonly _mergeStrategy;
+    private readonly _capabilities;
+    private constructor();
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities(): IMemoryRetrieverCapabilities;
+    /**
+     * Family-convention factory.
+     * @param retrievers - The retrievers to compose (at least one).
+     * @param mergeStrategy - How to combine their results.
+     */
+    static create(retrievers: ReadonlyArray<IMemoryRetriever>, mergeStrategy: IMergeStrategy): Result<HybridRetriever>;
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    /**
+     * Project the query for one child retriever. Two adjustments:
+     *
+     * - Strip axes the child does not support (`semantic` / `topK` for a
+     *   non-semantic child, `asOf` for a non-temporal child, the link axes for a
+     *   non-link child) so it returns its normal results rather than loud-failing
+     *   on a field a sibling handles.
+     * - Strip `limit` unconditionally: limit is a post-merge concern. A child that
+     *   pre-truncated its result set would starve the merge strategy of candidates
+     *   it needs to score correctly (a record both children would surface must
+     *   reach the merge to score 2). The hybrid applies `limit` once, after merge.
+     */
+    private _projectQuery;
+}
+//# sourceMappingURL=hybridRetriever.d.ts.map

package/lib/packlets/retrieve/hybridRetriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybridRetriever.d.ts","sourceRoot":"","sources":["../../../src/packlets/retrieve/hybridRetriever.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAA6B,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,aAAa,EAAY,MAAM,UAAU,CAAC;AACnD,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,4BAA4B,EAI7B,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,KAAK,CACH,UAAU,EAAE,aAAa,CAAC,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,GAC/D,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;CAClD;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,uBAAwB,YAAW,cAAc;IAC5D,OAAO;IAEP,iCAAiC;WACnB,MAAM,IAAI,MAAM,CAAC,uBAAuB,CAAC;IAIvD,yCAAyC;IAClC,KAAK,CACV,UAAU,EAAE,aAAa,CAAC,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,GAC/D,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;CAyBjD;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAgB,YAAW,gBAAgB;IACtD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkC;IAC9D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+B;IAE7D,OAAO;IAUP,kDAAkD;IAClD,IAAW,YAAY,IAAI,4BAA4B,CAEtD;IAED;;;;OAIG;WACW,MAAM,CAClB,UAAU,EAAE,aAAa,CAAC,gBAAgB,CAAC,EAC3C,aAAa,EAAE,cAAc,GAC5B,MAAM,CAAC,eAAe,CAAC;IAe1B,8CAA8C;IACjC,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAWlG;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;CAiBtB"}

package/lib/packlets/retrieve/hybridRetriever.js

@@ -0,0 +1,140 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HybridRetriever = exports.ScoreUnionMergeStrategy = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const retriever_1 = require("./retriever");
+/**
+ * The reference {@link IMergeStrategy}: a score-union. Every record is scored by
+ * the number of composed result sets it appears in (deduplicated by
+ * {@link IMemoryEnvelope.id | id}); the merged result is ordered by descending
+ * score, then by recency. Records surfaced by more retrievers rank higher.
+ *
+ * @remarks
+ * Dedup is by `id` alone, which is unambiguous for the flat (one-file-per-entity)
+ * kinds B2 ships. Phase-C versioned kinds that reuse a stem across scopes will
+ * extend the dedup key — additive, no API change.
+ * @public
+ */
+class ScoreUnionMergeStrategy {
+    constructor() { }
+    /** Family-convention factory. */
+    static create() {
+        return (0, ts_utils_1.succeed)(new ScoreUnionMergeStrategy());
+    }
+    /** {@inheritDoc IMergeStrategy.merge} */
+    merge(resultSets) {
+        const scored = new Map();
+        for (const set of resultSets) {
+            // Count each id at most once per result set, so the score is "how many
+            // retrievers surfaced this record" rather than "how many copies total".
+            const seenInSet = new Set();
+            for (const record of set) {
+                const id = record.envelope.id;
+                if (seenInSet.has(id)) {
+                    continue;
+                }
+                seenInSet.add(id);
+                const existing = scored.get(id);
+                if (existing === undefined) {
+                    scored.set(id, { record, score: 1 });
+                }
+                else {
+                    existing.score += 1;
+                }
+            }
+        }
+        const merged = Array.from(scored.values())
+            .sort((a, b) => (b.score !== a.score ? b.score - a.score : (0, retriever_1.recencyCompare)(a.record, b.record)))
+            .map((entry) => entry.record);
+        return (0, ts_utils_1.succeed)(merged);
+    }
+}
+exports.ScoreUnionMergeStrategy = ScoreUnionMergeStrategy;
+/**
+ * Composes several retrievers, dispatches a query to each, and merges their
+ * results via an injectable {@link IMergeStrategy}. Its capabilities are the
+ * union of the composed retrievers' capabilities.
+ *
+ * @remarks
+ * The hybrid enforces the loud-degradation contract against its OWN (union)
+ * capabilities, then projects the query for each child: a child that does not
+ * support the `semantic` (or `asOf`) axis is handed a query with that axis
+ * stripped, so it returns its normal results instead of loud-failing on a field
+ * a sibling handles. A child that genuinely fails (e.g. a wired semantic backend
+ * erroring) propagates — the hybrid never silently drops a failure.
+ * @public
+ */
+class HybridRetriever {
+    constructor(retrievers, mergeStrategy, capabilities) {
+        this._retrievers = retrievers;
+        this._mergeStrategy = mergeStrategy;
+        this._capabilities = capabilities;
+    }
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities() {
+        return this._capabilities;
+    }
+    /**
+     * Family-convention factory.
+     * @param retrievers - The retrievers to compose (at least one).
+     * @param mergeStrategy - How to combine their results.
+     */
+    static create(retrievers, mergeStrategy) {
+        if (retrievers.length === 0) {
+            return (0, ts_utils_1.fail)('HybridRetriever: at least one retriever is required');
+        }
+        // Snapshot the caller's array so a later mutation cannot make `retrieve()`
+        // and the cached `capabilities` disagree.
+        const stableRetrievers = [...retrievers];
+        const capabilities = {
+            supportsSemanticRecall: stableRetrievers.some((r) => r.capabilities.supportsSemanticRecall),
+            supportsTemporalQuery: stableRetrievers.some((r) => r.capabilities.supportsTemporalQuery),
+            supportsLinkTraversal: stableRetrievers.some((r) => r.capabilities.supportsLinkTraversal)
+        };
+        return (0, ts_utils_1.succeed)(new HybridRetriever(stableRetrievers, mergeStrategy, capabilities));
+    }
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    async retrieve(query) {
+        return (0, retriever_1.guardRetrieverCapabilities)(query, this._capabilities).thenOnSuccess(async () => {
+            const perRetriever = await Promise.all(this._retrievers.map((retriever) => retriever.retrieve(this._projectQuery(query, retriever))));
+            return (0, ts_utils_1.mapResults)(perRetriever)
+                .onSuccess((resultSets) => this._mergeStrategy.merge(resultSets))
+                .onSuccess((merged) => (0, ts_utils_1.succeed)((0, retriever_1.limitRecords)(merged, query.limit)));
+        });
+    }
+    /**
+     * Project the query for one child retriever. Two adjustments:
+     *
+     * - Strip axes the child does not support (`semantic` / `topK` for a
+     *   non-semantic child, `asOf` for a non-temporal child, the link axes for a
+     *   non-link child) so it returns its normal results rather than loud-failing
+     *   on a field a sibling handles.
+     * - Strip `limit` unconditionally: limit is a post-merge concern. A child that
+     *   pre-truncated its result set would starve the merge strategy of candidates
+     *   it needs to score correctly (a record both children would surface must
+     *   reach the merge to score 2). The hybrid applies `limit` once, after merge.
+     */
+    _projectQuery(query, retriever) {
+        const projected = Object.assign({}, query);
+        delete projected.limit;
+        if (!retriever.capabilities.supportsSemanticRecall) {
+            delete projected.semantic;
+            delete projected.topK;
+        }
+        if (!retriever.capabilities.supportsTemporalQuery) {
+            delete projected.asOf;
+        }
+        if (!retriever.capabilities.supportsLinkTraversal) {
+            delete projected.linkedFrom;
+            delete projected.linkedTo;
+            delete projected.hops;
+        }
+        return projected;
+    }
+}
+exports.HybridRetriever = HybridRetriever;
+//# sourceMappingURL=hybridRetriever.js.map

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

@@ -0,0 +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"]}

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

@@ -0,0 +1,8 @@
+export * from './retriever';
+export * from './recencyRetriever';
+export * from './linkTraversalRetriever';
+export * from './tagRetriever';
+export * from './structuredFilterRetriever';
+export * from './semanticRetriever';
+export * from './hybridRetriever';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/retrieve/index.ts"],"names":[],"mappings":"AAKA,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC"}

package/lib/packlets/retrieve/index.js

@@ -0,0 +1,28 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./retriever"), exports);
+__exportStar(require("./recencyRetriever"), exports);
+__exportStar(require("./linkTraversalRetriever"), exports);
+__exportStar(require("./tagRetriever"), exports);
+__exportStar(require("./structuredFilterRetriever"), exports);
+__exportStar(require("./semanticRetriever"), exports);
+__exportStar(require("./hybridRetriever"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,8CAA4B;AAC5B,qDAAmC;AACnC,2DAAyC;AACzC,iDAA+B;AAC/B,8DAA4C;AAC5C,sDAAoC;AACpC,oDAAkC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nexport * from './retriever';\nexport * from './recencyRetriever';\nexport * from './linkTraversalRetriever';\nexport * from './tagRetriever';\nexport * from './structuredFilterRetriever';\nexport * from './semanticRetriever';\nexport * from './hybridRetriever';\n"]}

package/lib/packlets/retrieve/linkTraversalRetriever.d.ts

@@ -0,0 +1,61 @@
+import { Result } from '@fgv/ts-utils';
+import { IMemoryRecord } from '../types';
+import { IMemoryIndex } from '../index';
+import { IMemoryQuery, IMemoryRetriever, IMemoryRetrieverCapabilities } from './retriever';
+/**
+ * The loud-degradation message returned when a link-traversal query supplies no
+ * seed (`linkedFrom` / `linkedTo`).
+ * @public
+ */
+export declare const LINK_TRAVERSAL_NO_SEED_MESSAGE: string;
+/**
+ * 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.
+ *
+ * @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.
+ * - **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.
+ * - **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
+ */
+export declare class LinkTraversalRetriever implements IMemoryRetriever {
+    private readonly _index;
+    private constructor();
+    /** Family-convention factory. */
+    static create(index: IMemoryIndex): Result<LinkTraversalRetriever>;
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities(): IMemoryRetrieverCapabilities;
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    /** Run the bounded, cycle-safe BFS and post-filter the reached records. */
+    private _traverse;
+    /**
+     * 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).
+     */
+    private _indexById;
+    /** Outbound neighbors: the targets of every edge on the records with this id. */
+    private _outbound;
+    /** Inbound neighbors: the ids whose edges point AT this id (the backlinks). */
+    private _inbound;
+}
+//# sourceMappingURL=linkTraversalRetriever.d.ts.map

package/lib/packlets/retrieve/linkTraversalRetriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linkTraversalRetriever.d.ts","sourceRoot":"","sources":["../../../src/packlets/retrieve/linkTraversalRetriever.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAiB,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,aAAa,EAAY,MAAM,UAAU,CAAC;AACnD,OAAO,EAAwB,YAAY,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,4BAA4B,EAK7B,MAAM,aAAa,CAAC;AAYrB;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,MACiB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,sBAAuB,YAAW,gBAAgB;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IAEtC,OAAO;IAIP,iCAAiC;WACnB,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAAC,sBAAsB,CAAC;IAIzE,kDAAkD;IAClD,IAAW,YAAY,IAAI,4BAA4B,CAEtD;IAED,8CAA8C;IACvC,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAM5F,2EAA2E;IAC3E,OAAO,CAAC,SAAS;IA0CjB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,UAAU;IAclB,iFAAiF;IACjF,OAAO,CAAC,SAAS;IAajB,+EAA+E;IAC/E,OAAO,CAAC,QAAQ;CAGjB"}

package/lib/packlets/retrieve/linkTraversalRetriever.js

@@ -0,0 +1,147 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LinkTraversalRetriever = exports.LINK_TRAVERSAL_NO_SEED_MESSAGE = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const retriever_1 = require("./retriever");
+/** The capabilities a link-traversal retriever exposes (link traversal only). */
+const LINK_TRAVERSAL_CAPABILITIES = {
+    supportsSemanticRecall: false,
+    supportsTemporalQuery: false,
+    supportsLinkTraversal: true
+};
+/** Default BFS hop count when `query.hops` is not supplied. */
+const DEFAULT_HOPS = 1;
+/**
+ * The loud-degradation message returned when a link-traversal query supplies no
+ * seed (`linkedFrom` / `linkedTo`).
+ * @public
+ */
+exports.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.
+ *
+ * @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.
+ * - **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.
+ * - **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
+ */
+class LinkTraversalRetriever {
+    constructor(index) {
+        this._index = index;
+    }
+    /** Family-convention factory. */
+    static create(index) {
+        return (0, ts_utils_1.succeed)(new LinkTraversalRetriever(index));
+    }
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities() {
+        return LINK_TRAVERSAL_CAPABILITIES;
+    }
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query) {
+        return Promise.resolve((0, retriever_1.guardRetrieverCapabilities)(query, this.capabilities).onSuccess(() => this._traverse(query)));
+    }
+    /** Run the bounded, cycle-safe BFS and post-filter the reached records. */
+    _traverse(query) {
+        var _a, _b;
+        const outbound = query.linkedFrom !== undefined;
+        const seed = (_a = query.linkedFrom) !== null && _a !== void 0 ? _a : query.linkedTo;
+        if (seed === undefined) {
+            return (0, ts_utils_1.fail)(exports.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 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);
+                        reached.push(neighbor);
+                        next.push(neighbor);
+                    }
+                }
+            }
+            frontier = next;
+        }
+        const entries = [];
+        for (const id of reached) {
+            const matches = byId.get(id);
+            if (matches !== undefined) {
+                entries.push(...matches);
+            }
+        }
+        const ordered = entries
+            .filter((entry) => (0, retriever_1.indexedRecordMatchesQuery)(entry, query))
+            .map((entry) => entry.record)
+            .sort(retriever_1.recencyCompare);
+        return (0, ts_utils_1.succeed)((0, retriever_1.limitRecords)(ordered, query.limit));
+    }
+    /**
+     * 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).
+     */
+    _indexById() {
+        const byId = 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);
+            }
+        }
+        return byId;
+    }
+    /** Outbound neighbors: the targets of every edge on the records with this id. */
+    _outbound(id, byId) {
+        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);
+                }
+            }
+        }
+        return targets;
+    }
+    /** Inbound neighbors: the ids whose edges point AT this id (the backlinks). */
+    _inbound(id) {
+        return this._index.backlinks(id);
+    }
+}
+exports.LinkTraversalRetriever = LinkTraversalRetriever;
+//# sourceMappingURL=linkTraversalRetriever.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"linkTraversalRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/linkTraversalRetriever.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,4CAAsD;AAGtD,2CAQqB;AAErB,iFAAiF;AACjF,MAAM,2BAA2B,GAAiC;IAChE,sBAAsB,EAAE,KAAK;IAC7B,qBAAqB,EAAE,KAAK;IAC5B,qBAAqB,EAAE,IAAI;CAC5B,CAAC;AAEF,+DAA+D;AAC/D,MAAM,YAAY,GAAW,CAAC,CAAC;AAE/B;;;;GAIG;AACU,QAAA,8BAA8B,GACzC,4DAA4D,CAAC;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAa,sBAAsB;IAGjC,YAAoB,KAAmB;QACrC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM,CAAC,KAAmB;QACtC,OAAO,IAAA,kBAAO,EAAC,IAAI,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC;IACpD,CAAC;IAED,kDAAkD;IAClD,IAAW,YAAY;QACrB,OAAO,2BAA2B,CAAC;IACrC,CAAC;IAED,8CAA8C;IACvC,QAAQ,CAAC,KAAmB;QACjC,OAAO,OAAO,CAAC,OAAO,CACpB,IAAA,sCAA0B,EAAC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAC5F,CAAC;IACJ,CAAC;IAED,2EAA2E;IACnE,SAAS,CAAC,KAAmB;;QACnC,MAAM,QAAQ,GAAY,KAAK,CAAC,UAAU,KAAK,SAAS,CAAC;QACzD,MAAM,IAAI,GAAyB,MAAA,KAAK,CAAC,UAAU,mCAAI,KAAK,CAAC,QAAQ,CAAC;QACtE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,IAAA,eAAI,EAAC,sCAA8B,CAAC,CAAC;QAC9C,CAAC;QACD,MAAM,IAAI,GAAW,MAAA,KAAK,CAAC,IAAI,mCAAI,YAAY,CAAC;QAChD,MAAM,IAAI,GAAkD,IAAI,CAAC,UAAU,EAAE,CAAC;QAE9E,4EAA4E;QAC5E,2EAA2E;QAC3E,MAAM,OAAO,GAAgB,IAAI,GAAG,CAAS,CAAC,IAAI,CAAC,CAAC,CAAC;QACrD,MAAM,OAAO,GAAe,EAAE,CAAC;QAC/B,IAAI,QAAQ,GAAe,CAAC,IAAI,CAAC,CAAC;QAClC,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,IAAI,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC;YAC3D,MAAM,IAAI,GAAe,EAAE,CAAC;YAC5B,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;gBAC1B,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;oBAC/E,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;wBAC3B,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;wBACtB,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;wBACvB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;oBACtB,CAAC;gBACH,CAAC;YACH,CAAC;YACD,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;QAED,MAAM,OAAO,GAA2B,EAAE,CAAC;QAC3C,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;YACzB,MAAM,OAAO,GAAuC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACjE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,MAAM,OAAO,GAA6B,OAAO;aAC9C,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAA,qCAAyB,EAAC,KAAK,EAAE,KAAK,CAAC,CAAC;aAC1D,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC;aAC5B,IAAI,CAAC,0BAAc,CAAC,CAAC;QACxB,OAAO,IAAA,kBAAO,EAAC,IAAA,wBAAY,EAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IACrD,CAAC;IAED;;;;;;;;;;;;;OAaG;IACK,UAAU;QAChB,MAAM,IAAI,GAA0C,IAAI,GAAG,EAAoC,CAAC;QAChG,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;YAC1C,MAAM,EAAE,GAAa,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9C,MAAM,QAAQ,GAAuC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAClE,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;YACxB,CAAC;iBAAM,CAAC;gBACN,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,iFAAiF;IACzE,SAAS,CAAC,EAAY,EAAE,IAAmD;QACjF,MAAM,OAAO,GAAe,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAuC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACjE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;oBAC/C,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC5B,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,+EAA+E;IACvE,QAAQ,CAAC,EAAY;QAC3B,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;CACF;AAjHD,wDAiHC","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"]}

package/lib/packlets/retrieve/recencyRetriever.d.ts

@@ -0,0 +1,21 @@
+import { Result } from '@fgv/ts-utils';
+import { IMemoryRecord } from '../types';
+import { IMemoryIndex } from '../index';
+import { IMemoryQuery, IMemoryRetriever, IMemoryRetrieverCapabilities } from './retriever';
+/**
+ * Returns records matching the query's scope / kind / tag / predicate filters,
+ * ordered most-recently-updated first. The universal v1 retriever — an empty
+ * query returns the whole vault in recency order.
+ * @public
+ */
+export declare class RecencyRetriever implements IMemoryRetriever {
+    private readonly _index;
+    private constructor();
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities(): IMemoryRetrieverCapabilities;
+    /** Family-convention factory. */
+    static create(index: IMemoryIndex): Result<RecencyRetriever>;
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+}
+//# sourceMappingURL=recencyRetriever.d.ts.map

package/lib/packlets/retrieve/recencyRetriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recencyRetriever.d.ts","sourceRoot":"","sources":["../../../src/packlets/retrieve/recencyRetriever.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAW,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,4BAA4B,EAM7B,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,qBAAa,gBAAiB,YAAW,gBAAgB;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IAEtC,OAAO;IAIP,kDAAkD;IAClD,IAAW,YAAY,IAAI,4BAA4B,CAEtD;IAED,iCAAiC;WACnB,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAInE,8CAA8C;IACvC,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;CAU7F"}

package/lib/packlets/retrieve/recencyRetriever.js

@@ -0,0 +1,37 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecencyRetriever = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const retriever_1 = require("./retriever");
+/**
+ * Returns records matching the query's scope / kind / tag / predicate filters,
+ * ordered most-recently-updated first. The universal v1 retriever — an empty
+ * query returns the whole vault in recency order.
+ * @public
+ */
+class RecencyRetriever {
+    constructor(index) {
+        this._index = index;
+    }
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities() {
+        return retriever_1.NON_SEMANTIC_CAPABILITIES;
+    }
+    /** Family-convention factory. */
+    static create(index) {
+        return (0, ts_utils_1.succeed)(new RecencyRetriever(index));
+    }
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query) {
+        return Promise.resolve((0, retriever_1.guardRetrieverCapabilities)(query, this.capabilities).onSuccess(() => {
+            const ordered = (0, retriever_1.selectByQuery)(this._index.entries(), query).sort(retriever_1.recencyCompare);
+            return (0, ts_utils_1.succeed)((0, retriever_1.limitRecords)(ordered, query.limit));
+        }));
+    }
+}
+exports.RecencyRetriever = RecencyRetriever;
+//# sourceMappingURL=recencyRetriever.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recencyRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/recencyRetriever.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,4CAAgD;AAGhD,2CASqB;AAErB;;;;;GAKG;AACH,MAAa,gBAAgB;IAG3B,YAAoB,KAAmB;QACrC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,kDAAkD;IAClD,IAAW,YAAY;QACrB,OAAO,qCAAyB,CAAC;IACnC,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM,CAAC,KAAmB;QACtC,OAAO,IAAA,kBAAO,EAAC,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,8CAA8C;IACvC,QAAQ,CAAC,KAAmB;QACjC,OAAO,OAAO,CAAC,OAAO,CACpB,IAAA,sCAA0B,EAAC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE;YAClE,MAAM,OAAO,GAA6B,IAAA,yBAAa,EAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC,IAAI,CACxF,0BAAc,CACf,CAAC;YACF,OAAO,IAAA,kBAAO,EAAC,IAAA,wBAAY,EAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QACrD,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;CACF;AA5BD,4CA4BC","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"]}