@fgv/ts-agent-memory 5.1.0-36

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

@@ -0,0 +1,133 @@
+import { Result } from '@fgv/ts-utils';
+import { IMemoryRecord, Kind, MemoryId, MemoryScopeKey, Tag } from '../types';
+import { IIndexedMemoryRecord } from '../index';
+/**
+ * The capabilities a retriever exposes. A consumer probes these before
+ * dispatching a query so it never silently gets an empty result for a
+ * capability the retriever does not implement.
+ * @public
+ */
+export interface IMemoryRetrieverCapabilities {
+    /** Semantic / vector recall is operational (an {@link IVectorIndex} is wired). */
+    readonly supportsSemanticRecall: boolean;
+    /** Temporal "as-of" queries are operational (a temporal index is wired). */
+    readonly supportsTemporalQuery: boolean;
+    /** Link traversal is supported (an in-memory backlink index is present). */
+    readonly supportsLinkTraversal: boolean;
+}
+/**
+ * A retrieval query. Every field is optional; an empty query is the "recency
+ * over everything" request. `semantic` and `asOf` are present from day one (the
+ * no-resignature guarantee): a backend that adds semantic or temporal recall
+ * sets the matching capability flag, with no interface change.
+ * @public
+ */
+export interface IMemoryQuery {
+    /** Restrict to records in this scope. */
+    readonly scope?: MemoryScopeKey;
+    /** Restrict to records carrying this tag (exact match). */
+    readonly tag?: Tag;
+    /** Restrict to records of this kind. */
+    readonly kind?: Kind;
+    /** Restrict to records linked FROM this id (outbound). */
+    readonly linkedFrom?: MemoryId;
+    /** Restrict to records linked TO this id (inbound / backlinks). */
+    readonly linkedTo?: MemoryId;
+    /** BFS hop count for link traversal. Default: 1. */
+    readonly hops?: number;
+    /**
+     * Text query for semantic / vector recall. If set and the retriever's
+     * `supportsSemanticRecall` is `false`, the retriever returns a loud
+     * `Result.fail` ({@link SEMANTIC_UNWIRED_MESSAGE}) — never a silent empty.
+     */
+    readonly semantic?: string;
+    /** Top-K for semantic recall. Default: 10. */
+    readonly topK?: number;
+    /**
+     * As-of epoch ms for temporal "valid at" queries. If set and the retriever's
+     * `supportsTemporalQuery` is `false`, the retriever returns a loud
+     * `Result.fail` — never a silent empty.
+     */
+    readonly asOf?: number;
+    /** Maximum records to return. Applied after all other filters. */
+    readonly limit?: number;
+    /** Arbitrary predicate applied after the scope / kind / tag pre-filter. */
+    readonly filter?: (record: IMemoryRecord<unknown>) => boolean;
+}
+/**
+ * The retrieval contract. A retriever exposes its {@link
+ * IMemoryRetrieverCapabilities | capabilities} and answers
+ * {@link IMemoryRetriever.retrieve | queries}, degrading loudly (never silently
+ * empty) when a requested capability is not wired.
+ * @public
+ */
+export interface IMemoryRetriever {
+    /** The capabilities this retriever exposes. Probe before dispatch. */
+    readonly capabilities: IMemoryRetrieverCapabilities;
+    /**
+     * Retrieve records matching `query`. Returns a `Result.fail` with a
+     * diagnostic message when the query requests a capability this retriever does
+     * not support (never an empty success).
+     */
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+}
+/**
+ * The loud-degradation message a retriever returns when `query.semantic` is set
+ * but no {@link IVectorIndex} is wired.
+ * @public
+ */
+export declare const SEMANTIC_UNWIRED_MESSAGE: string;
+/**
+ * The loud-degradation message a retriever returns when a link-traversal axis
+ * (`linkedFrom` / `linkedTo` / `hops`) is requested but no backlink index is
+ * wired.
+ * @public
+ */
+export declare const LINK_TRAVERSAL_UNWIRED_MESSAGE: string;
+/**
+ * The capabilities every non-semantic, non-temporal, non-link v1 retriever
+ * exposes (all three flags `false`).
+ * @public
+ */
+export declare const NON_SEMANTIC_CAPABILITIES: IMemoryRetrieverCapabilities;
+/**
+ * Build the loud-degradation message a retriever returns when `query.asOf` is
+ * set but no temporal index is wired.
+ * @public
+ */
+export declare function temporalUnwiredMessage(kind?: Kind): string;
+/**
+ * Enforce the loud-degradation contract for the `semantic` and `asOf` axes
+ * against a retriever's `capabilities`: a requested capability the retriever
+ * does not support fails loudly rather than returning a silent empty result.
+ * @public
+ */
+export declare function guardRetrieverCapabilities(query: IMemoryQuery, capabilities: IMemoryRetrieverCapabilities): Result<true>;
+/**
+ * Recency comparator: most-recently-updated first, with a `seq` tiebreak so
+ * equal-`updated` records sort deterministically. Mirrors the B1 index ordering.
+ * @public
+ */
+export declare function recencyCompare(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number;
+/**
+ * Whether an indexed entry satisfies a query's scope / kind / tag / predicate
+ * pre-filter (the axes shared by every v1 retriever). The `semantic` / `asOf` /
+ * link axes are NOT applied here — those are each retriever's own concern.
+ * @public
+ */
+export declare function indexedRecordMatchesQuery(entry: IIndexedMemoryRecord, query: IMemoryQuery): boolean;
+/**
+ * Apply the shared scope / kind / tag / predicate pre-filter to a set of indexed
+ * entries, returning the surviving records (unordered, unlimited).
+ * @public
+ */
+export declare function selectByQuery(entries: ReadonlyArray<IIndexedMemoryRecord>, query: IMemoryQuery): IMemoryRecord<unknown>[];
+/**
+ * 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`.
+ * @public
+ */
+export declare function limitRecords(records: ReadonlyArray<IMemoryRecord<unknown>>, limit?: number): ReadonlyArray<IMemoryRecord<unknown>>;
+//# sourceMappingURL=retriever.d.ts.map

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

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

package/lib/packlets/retrieve/retriever.js

@@ -0,0 +1,119 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NON_SEMANTIC_CAPABILITIES = exports.LINK_TRAVERSAL_UNWIRED_MESSAGE = exports.SEMANTIC_UNWIRED_MESSAGE = void 0;
+exports.temporalUnwiredMessage = temporalUnwiredMessage;
+exports.guardRetrieverCapabilities = guardRetrieverCapabilities;
+exports.recencyCompare = recencyCompare;
+exports.indexedRecordMatchesQuery = indexedRecordMatchesQuery;
+exports.selectByQuery = selectByQuery;
+exports.limitRecords = limitRecords;
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * The loud-degradation message a retriever returns when `query.semantic` is set
+ * but no {@link IVectorIndex} is wired.
+ * @public
+ */
+exports.SEMANTIC_UNWIRED_MESSAGE = 'semantic recall requires a vector index; none configured';
+/**
+ * The loud-degradation message a retriever returns when a link-traversal axis
+ * (`linkedFrom` / `linkedTo` / `hops`) is requested but no backlink index is
+ * wired.
+ * @public
+ */
+exports.LINK_TRAVERSAL_UNWIRED_MESSAGE = 'link traversal requires a backlink index; none configured';
+/**
+ * The capabilities every non-semantic, non-temporal, non-link v1 retriever
+ * exposes (all three flags `false`).
+ * @public
+ */
+exports.NON_SEMANTIC_CAPABILITIES = {
+    supportsSemanticRecall: false,
+    supportsTemporalQuery: false,
+    supportsLinkTraversal: false
+};
+/**
+ * Build the loud-degradation message a retriever returns when `query.asOf` is
+ * set but no temporal index is wired.
+ * @public
+ */
+function temporalUnwiredMessage(kind) {
+    return `temporal query requires temporal index; none configured${kind !== undefined ? ` for kind ${kind}` : ''}`;
+}
+/**
+ * Enforce the loud-degradation contract for the `semantic` and `asOf` axes
+ * against a retriever's `capabilities`: a requested capability the retriever
+ * does not support fails loudly rather than returning a silent empty result.
+ * @public
+ */
+function guardRetrieverCapabilities(query, capabilities) {
+    if (query.semantic !== undefined && !capabilities.supportsSemanticRecall) {
+        return (0, ts_utils_1.fail)(exports.SEMANTIC_UNWIRED_MESSAGE);
+    }
+    if (query.asOf !== undefined && !capabilities.supportsTemporalQuery) {
+        return (0, ts_utils_1.fail)(temporalUnwiredMessage(query.kind));
+    }
+    const requestsLinkTraversal = query.linkedFrom !== undefined || query.linkedTo !== undefined || query.hops !== undefined;
+    if (requestsLinkTraversal && !capabilities.supportsLinkTraversal) {
+        return (0, ts_utils_1.fail)(exports.LINK_TRAVERSAL_UNWIRED_MESSAGE);
+    }
+    return (0, ts_utils_1.succeed)(true);
+}
+/**
+ * Recency comparator: most-recently-updated first, with a `seq` tiebreak so
+ * equal-`updated` records sort deterministically. Mirrors the B1 index ordering.
+ * @public
+ */
+function recencyCompare(a, b) {
+    const byUpdated = b.envelope.updated - a.envelope.updated;
+    return byUpdated !== 0 ? byUpdated : b.envelope.seq - a.envelope.seq;
+}
+/**
+ * Whether an indexed entry satisfies a query's scope / kind / tag / predicate
+ * pre-filter (the axes shared by every v1 retriever). The `semantic` / `asOf` /
+ * link axes are NOT applied here — those are each retriever's own concern.
+ * @public
+ */
+function indexedRecordMatchesQuery(entry, query) {
+    if (query.scope !== undefined && entry.scope !== query.scope) {
+        return false;
+    }
+    if (query.kind !== undefined && entry.record.envelope.kind !== query.kind) {
+        return false;
+    }
+    if (query.tag !== undefined && !entry.record.envelope.tags.includes(query.tag)) {
+        return false;
+    }
+    if (query.filter !== undefined && !query.filter(entry.record)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Apply the shared scope / kind / tag / predicate pre-filter to a set of indexed
+ * entries, returning the surviving records (unordered, unlimited).
+ * @public
+ */
+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`.
+ * @public
+ */
+function limitRecords(records, limit) {
+    if (limit === undefined) {
+        return records;
+    }
+    if (limit <= 0) {
+        return [];
+    }
+    return records.length > limit ? records.slice(0, limit) : records;
+}
+//# sourceMappingURL=retriever.js.map

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

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

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

@@ -0,0 +1,69 @@
+import { Result } from '@fgv/ts-utils';
+import { IMemoryRecord } from '../types';
+import { IMemoryIndex } from '../index';
+import { IVectorIndex } from '../vector';
+import { IMemoryQuery, IMemoryRetriever, IMemoryRetrieverCapabilities } from './retriever';
+/**
+ * Embeds a query string into a vector for {@link IVectorIndex.query}. Async and
+ * `Result`-returning, since a real embedder does a network call.
+ * @public
+ */
+export type QueryEmbedder = (text: string) => Promise<Result<Float32Array>>;
+/**
+ * The semantic backend wired into a {@link SemanticRetriever}: the vector index
+ * to query and the embedder that turns the query text into a vector. Both are
+ * required together — a vector index is useless without a way to embed the
+ * query, so {@link SemanticRetriever.create} treats them as one unit.
+ * @public
+ */
+export interface ISemanticBackend {
+    /** The vector index to query. */
+    readonly vectorIndex: IVectorIndex;
+    /** Turns the query text into a vector. */
+    readonly embedQuery: QueryEmbedder;
+}
+/**
+ * Construction options for {@link SemanticRetriever.create}.
+ * @public
+ */
+export interface ISemanticRetrieverCreateParams {
+    /** The record index, used to resolve vector hits back to full records. */
+    readonly index: IMemoryIndex;
+    /**
+     * The semantic backend. When absent, the retriever reports
+     * `supportsSemanticRecall: false` and a `query.semantic` request degrades
+     * loudly ({@link SEMANTIC_UNWIRED_MESSAGE}) rather than returning empty.
+     */
+    readonly backend?: ISemanticBackend;
+}
+/**
+ * Vector-recall retriever. When a {@link ISemanticBackend | backend} is wired it
+ * embeds `query.semantic`, queries the vector index, and resolves the hits back
+ * to records (preserving vector score order). When no backend is wired,
+ * `supportsSemanticRecall` is `false` and any `query.semantic` request degrades
+ * loudly — it NEVER returns a silent empty.
+ *
+ * @remarks
+ * A consumer-supplied backend that rejects (throws) is normalized into a
+ * `Failure` — `retrieve` always honors its `Promise<Result<...>>` contract.
+ * @public
+ */
+export declare class SemanticRetriever implements IMemoryRetriever {
+    private readonly _index;
+    private readonly _backend;
+    private constructor();
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities(): IMemoryRetrieverCapabilities;
+    /** Family-convention factory. */
+    static create(params: ISemanticRetrieverCreateParams): Result<SemanticRetriever>;
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    /**
+     * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`
+     * and a thrown/rejected promise into a single `semantic recall: <label> failed`
+     * `Failure`. Keeps `retrieve` within the `Promise<Result<...>>` contract even
+     * when the injected `embedQuery` / `vectorIndex` misbehaves.
+     */
+    private static _callBackend;
+}
+//# sourceMappingURL=semanticRetriever.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"semanticRetriever.d.ts","sourceRoot":"","sources":["../../../src/packlets/retrieve/semanticRetriever.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,EAAE,YAAY,EAAmB,MAAM,WAAW,CAAC;AAC1D,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,4BAA4B,EAK7B,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;AAE5E;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;IACnC,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,8BAA8B;IAC7C,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,YAAW,gBAAgB;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IAExD,OAAO;IAKP,kDAAkD;IAClD,IAAW,YAAY,IAAI,4BAA4B,CAMtD;IAED,iCAAiC;WACnB,MAAM,CAAC,MAAM,EAAE,8BAA8B,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAIvF,8CAA8C;IACjC,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IA0ClG;;;;;OAKG;mBACkB,YAAY;CAOlC"}

package/lib/packlets/retrieve/semanticRetriever.js

@@ -0,0 +1,90 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SemanticRetriever = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const retriever_1 = require("./retriever");
+/**
+ * Vector-recall retriever. When a {@link ISemanticBackend | backend} is wired it
+ * embeds `query.semantic`, queries the vector index, and resolves the hits back
+ * to records (preserving vector score order). When no backend is wired,
+ * `supportsSemanticRecall` is `false` and any `query.semantic` request degrades
+ * loudly — it NEVER returns a silent empty.
+ *
+ * @remarks
+ * A consumer-supplied backend that rejects (throws) is normalized into a
+ * `Failure` — `retrieve` always honors its `Promise<Result<...>>` contract.
+ * @public
+ */
+class SemanticRetriever {
+    constructor(index, backend) {
+        this._index = index;
+        this._backend = backend;
+    }
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities() {
+        return {
+            supportsSemanticRecall: this._backend !== undefined,
+            supportsTemporalQuery: false,
+            supportsLinkTraversal: false
+        };
+    }
+    /** Family-convention factory. */
+    static create(params) {
+        return (0, ts_utils_1.succeed)(new SemanticRetriever(params.index, params.backend));
+    }
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    async retrieve(query) {
+        if (query.asOf !== undefined) {
+            return (0, ts_utils_1.fail)((0, retriever_1.temporalUnwiredMessage)(query.kind));
+        }
+        if (query.semantic === undefined) {
+            // The semantic term is this retriever's axis; without it there is nothing
+            // to recall (a no-op contribution to a HybridRetriever, not a failure).
+            return (0, ts_utils_1.succeed)([]);
+        }
+        if (this._backend === undefined) {
+            return (0, ts_utils_1.fail)(retriever_1.SEMANTIC_UNWIRED_MESSAGE);
+        }
+        const backend = this._backend;
+        // The backend hooks are consumer-supplied; a rejecting (throwing) impl must
+        // still surface as a `Failure`, never escape `retrieve` as a rejected
+        // promise. `_callBackend` normalizes both a returned `fail` and a rejection.
+        const embedded = await SemanticRetriever._callBackend('query embedding', () => backend.embedQuery(query.semantic));
+        if (embedded.isFailure()) {
+            return (0, ts_utils_1.fail)(embedded.message);
+        }
+        const hits = await SemanticRetriever._callBackend('vector query', () => { var _a; return backend.vectorIndex.query(embedded.value, (_a = query.topK) !== null && _a !== void 0 ? _a : 10); });
+        if (hits.isFailure()) {
+            return (0, ts_utils_1.fail)(hits.message);
+        }
+        const byId = new Map(this._index.entries().map((entry) => [entry.record.envelope.id, entry]));
+        const records = [];
+        for (const hit of hits.value) {
+            const entry = byId.get(hit.id);
+            if (entry !== undefined && (0, retriever_1.indexedRecordMatchesQuery)(entry, query)) {
+                records.push(entry.record);
+            }
+        }
+        return (0, ts_utils_1.succeed)((0, retriever_1.limitRecords)(records, query.limit));
+    }
+    /**
+     * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`
+     * and a thrown/rejected promise into a single `semantic recall: <label> failed`
+     * `Failure`. Keeps `retrieve` within the `Promise<Result<...>>` contract even
+     * when the injected `embedQuery` / `vectorIndex` misbehaves.
+     */
+    static async _callBackend(label, op) {
+        try {
+            return (await op()).withErrorFormat((msg) => `semantic recall: ${label} failed: ${msg}`);
+        }
+        catch (err) {
+            return (0, ts_utils_1.fail)(`semantic recall: ${label} failed: ${String(err)}`);
+        }
+    }
+}
+exports.SemanticRetriever = SemanticRetriever;
+//# sourceMappingURL=semanticRetriever.js.map

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

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

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

@@ -0,0 +1,22 @@
+import { Result } from '@fgv/ts-utils';
+import { IMemoryRecord } from '../types';
+import { IMemoryIndex } from '../index';
+import { IMemoryQuery, IMemoryRetriever, IMemoryRetrieverCapabilities } 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
+ * query without a `filter` is not its concern and yields an empty success (so it
+ * contributes nothing to a {@link HybridRetriever}, rather than failing).
+ * @public
+ */
+export declare class StructuredFilterRetriever implements IMemoryRetriever {
+    private readonly _index;
+    private constructor();
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities(): IMemoryRetrieverCapabilities;
+    /** Family-convention factory. */
+    static create(index: IMemoryIndex): Result<StructuredFilterRetriever>;
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+}
+//# sourceMappingURL=structuredFilterRetriever.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"structuredFilterRetriever.d.ts","sourceRoot":"","sources":["../../../src/packlets/retrieve/structuredFilterRetriever.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;;;;;;GAMG;AACH,qBAAa,yBAA0B,YAAW,gBAAgB;IAChE,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,yBAAyB,CAAC;IAI5E,8CAA8C;IACvC,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;CAa7F"}

package/lib/packlets/retrieve/structuredFilterRetriever.js

@@ -0,0 +1,41 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StructuredFilterRetriever = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const retriever_1 = require("./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
+ * query without a `filter` is not its concern and yields an empty success (so it
+ * contributes nothing to a {@link HybridRetriever}, rather than failing).
+ * @public
+ */
+class StructuredFilterRetriever {
+    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 StructuredFilterRetriever(index));
+    }
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query) {
+        return Promise.resolve((0, retriever_1.guardRetrieverCapabilities)(query, this.capabilities).onSuccess(() => {
+            if (query.filter === undefined) {
+                return (0, ts_utils_1.succeed)([]);
+            }
+            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.StructuredFilterRetriever = StructuredFilterRetriever;
+//# sourceMappingURL=structuredFilterRetriever.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"structuredFilterRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/structuredFilterRetriever.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,4CAAgD;AAGhD,2CASqB;AAErB;;;;;;GAMG;AACH,MAAa,yBAAyB;IAGpC,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,yBAAyB,CAAC,KAAK,CAAC,CAAC,CAAC;IACvD,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,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC/B,OAAO,IAAA,kBAAO,EAAC,EAAE,CAAC,CAAC;YACrB,CAAC;YACD,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;AA/BD,8DA+BC","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"]}

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

@@ -0,0 +1,22 @@
+import { Result } from '@fgv/ts-utils';
+import { IMemoryRecord } from '../types';
+import { IMemoryIndex } from '../index';
+import { IMemoryQuery, IMemoryRetriever, IMemoryRetrieverCapabilities } 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
+ * axis: a query without a `tag` is not its concern and yields an empty success
+ * (so it contributes nothing to a {@link HybridRetriever}, rather than failing).
+ * @public
+ */
+export declare class TagRetriever implements IMemoryRetriever {
+    private readonly _index;
+    private constructor();
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities(): IMemoryRetrieverCapabilities;
+    /** Family-convention factory. */
+    static create(index: IMemoryIndex): Result<TagRetriever>;
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+}
+//# sourceMappingURL=tagRetriever.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tagRetriever.d.ts","sourceRoot":"","sources":["../../../src/packlets/retrieve/tagRetriever.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;;;;;;GAMG;AACH,qBAAa,YAAa,YAAW,gBAAgB;IACnD,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,YAAY,CAAC;IAI/D,8CAA8C;IACvC,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;CAa7F"}

package/lib/packlets/retrieve/tagRetriever.js

@@ -0,0 +1,41 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TagRetriever = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const retriever_1 = require("./retriever");
+/**
+ * Returns records carrying `query.tag`, recency-ordered within the tag and
+ * narrowed by any scope / kind / predicate filters. Tag is this retriever's
+ * axis: a query without a `tag` is not its concern and yields an empty success
+ * (so it contributes nothing to a {@link HybridRetriever}, rather than failing).
+ * @public
+ */
+class TagRetriever {
+    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 TagRetriever(index));
+    }
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query) {
+        return Promise.resolve((0, retriever_1.guardRetrieverCapabilities)(query, this.capabilities).onSuccess(() => {
+            if (query.tag === undefined) {
+                return (0, ts_utils_1.succeed)([]);
+            }
+            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.TagRetriever = TagRetriever;
+//# sourceMappingURL=tagRetriever.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tagRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/tagRetriever.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,4CAAgD;AAGhD,2CASqB;AAErB;;;;;;GAMG;AACH,MAAa,YAAY;IAGvB,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,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1C,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,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;gBAC5B,OAAO,IAAA,kBAAO,EAAC,EAAE,CAAC,CAAC;YACrB,CAAC;YACD,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;AA/BD,oCA+BC","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"]}