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

package/dist/packlets/retrieve/semanticRetriever.js

@@ -3,8 +3,7 @@
  * SPDX-License-Identifier: MIT
  */
 import { fail, succeed } from '@fgv/ts-utils';
-import { edgeTargetKey } from '../types';
-import { SEMANTIC_UNWIRED_MESSAGE, indexedRecordMatchesQuery, limitRecords, temporalUnwiredMessage } from './retriever';
+import { SEMANTIC_UNWIRED_MESSAGE, indexedRecordMatchesQuery, materializePage, temporalUnwiredMessage } from './retriever';
 /**
  * Vector-recall retriever. When a {@link ISemanticBackend | backend} is wired it
  * embeds `query.semantic`, queries the vector index, and resolves the hits back
@@ -18,9 +17,10 @@ import { SEMANTIC_UNWIRED_MESSAGE, indexedRecordMatchesQuery, limitRecords, temp
  * @public
  */
 export class SemanticRetriever {
-    constructor(index, backend) {
-        this._index = index;
-        this._backend = backend;
+    constructor(params) {
+        this._index = params.index;
+        this._resolver = params.resolver;
+        this._backend = params.backend;
     }
     /** {@inheritDoc IMemoryRetriever.capabilities} */
     get capabilities() {
@@ -32,7 +32,7 @@ export class SemanticRetriever {
     }
     /** Family-convention factory. */
     static create(params) {
-        return succeed(new SemanticRetriever(params.index, params.backend));
+        return succeed(new SemanticRetriever(params));
     }
     /** {@inheritDoc IMemoryRetriever.retrieve} */
     async retrieve(query) {
@@ -59,20 +59,20 @@ export class SemanticRetriever {
         if (hits.isFailure()) {
             return fail(hits.message);
         }
-        // Key by the canonical scope-qualified target so a hit re-resolves to the
-        // exact record it scored against — a bare id would alias two records that
-        // share a filename stem across scopes.
-        const byKey = new Map(this._index
-            .entries()
-            .map((entry) => [edgeTargetKey({ scope: entry.scope, id: entry.record.envelope.id }), entry]));
-        const records = [];
+        // Resolve each hit by its canonical scope-qualified target — a bare id would
+        // alias two records that share a filename stem across scopes. This used to
+        // build a Map over the ENTIRE index to look up at most `topK` of them; the
+        // index's own `get` makes it O(hits).
+        const selected = [];
         for (const hit of hits.value) {
-            const entry = byKey.get(edgeTargetKey(hit.target));
+            const entry = this._index.get(hit.target);
             if (entry !== undefined && indexedRecordMatchesQuery(entry, query)) {
-                records.push(entry.record);
+                selected.push(entry);
             }
         }
-        return succeed(limitRecords(records, query.limit, query.offset));
+        // Hit order IS the ranking, so the page is taken before materializing and
+        // only the returned records are read.
+        return materializePage(selected, query, this._resolver);
     }
     /**
      * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`

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

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

package/dist/packlets/retrieve/structuredFilterRetriever.js

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: MIT
  */
 import { succeed } from '@fgv/ts-utils';
-import { NON_SEMANTIC_CAPABILITIES, guardRetrieverCapabilities, limitRecords, orderingCompare, selectByQuery } from './retriever';
+import { NON_SEMANTIC_CAPABILITIES, guardRetrieverCapabilities, resolveQuery } from './retriever';
 /**
  * Returns records matching `query.filter` or `query.provenanceSource`, narrowed
  * by any scope / kind / tag / provenance-source pre-filter and recency-ordered.
@@ -34,16 +34,17 @@ import { NON_SEMANTIC_CAPABILITIES, guardRetrieverCapabilities, limitRecords, or
  * @public
  */
 export class StructuredFilterRetriever {
-    constructor(index) {
-        this._index = index;
+    constructor(params) {
+        this._index = params.index;
+        this._resolver = params.resolver;
     }
     /** {@inheritDoc IMemoryRetriever.capabilities} */
     get capabilities() {
         return NON_SEMANTIC_CAPABILITIES;
     }
     /** Family-convention factory. */
-    static create(index) {
-        return succeed(new StructuredFilterRetriever(index));
+    static create(params) {
+        return succeed(new StructuredFilterRetriever(params));
     }
     /** {@inheritDoc IMemoryRetriever.retrieve} */
     retrieve(query) {
@@ -51,8 +52,7 @@ export class StructuredFilterRetriever {
             if (query.filter === undefined && query.provenanceSource === undefined) {
                 return succeed([]);
             }
-            const ordered = selectByQuery(this._index.entries(), query).sort(orderingCompare(query.orderBy));
-            return succeed(limitRecords(ordered, query.limit, query.offset));
+            return resolveQuery(this._index.entries(), query, this._resolver);
         }));
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"structuredFilterRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/structuredFilterRetriever.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,OAAO,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAIL,yBAAyB,EACzB,0BAA0B,EAC1B,YAAY,EACZ,eAAe,EACf,aAAa,EACd,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAO,yBAAyB;IAGpC,YAAoB,KAAmB;QACrC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,kDAAkD;IAClD,IAAW,YAAY;QACrB,OAAO,yBAAyB,CAAC;IACnC,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM,CAAC,KAAmB;QACtC,OAAO,OAAO,CAAC,IAAI,yBAAyB,CAAC,KAAK,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,8CAA8C;IACvC,QAAQ,CAAC,KAAmB;QACjC,OAAO,OAAO,CAAC,OAAO,CACpB,0BAA0B,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE;YAClE,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;gBACvE,OAAO,OAAO,CAAC,EAAE,CAAC,CAAC;YACrB,CAAC;YACD,MAAM,OAAO,GAA6B,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC,IAAI,CACxF,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,CAC/B,CAAC;YACF,OAAO,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QACnE,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord } from '../types';\nimport { IMemoryIndex } from '../index';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  NON_SEMANTIC_CAPABILITIES,\n  guardRetrieverCapabilities,\n  limitRecords,\n  orderingCompare,\n  selectByQuery\n} from './retriever';\n\n/**\n * Returns records matching `query.filter` or `query.provenanceSource`, narrowed\n * by any scope / kind / tag / provenance-source pre-filter and recency-ordered.\n * Those two are this retriever's axes: a query carrying neither is not its\n * concern and yields an empty success (so it contributes nothing to a\n * {@link HybridRetriever}, rather than failing).\n *\n * Note `provenanceSource` appears on both sides of that sentence, and the\n * duplication is real rather than sloppy: it is one of this retriever's two\n * *dispatch* axes (it decides whether the query is this retriever's concern at\n * all) **and** a member of the shared *pre-filter* (it narrows the result set,\n * as it does for every other retriever). `filter` is likewise both.\n *\n * @remarks\n * `provenanceSource` is *applied* by the shared pre-filter, so every retriever\n * narrows by it. What this retriever adds is *answering* a query whose only axis\n * is `provenanceSource` — the \"show me everything this source produced\" request,\n * which would otherwise fall through the `filter`-absent guard and come back\n * empty.\n *\n * Consequently, inside a {@link HybridRetriever} composed with the universal\n * {@link RecencyRetriever}, a `provenanceSource`-only query is answered by both\n * children and every matching record scores twice under a score-union merge.\n * That is the established behavior for a dedicated-axis retriever composed with\n * the universal one — {@link TagRetriever} double-scores a `tag`-only query the\n * same way — and is intentional here, not an artifact of grafting a second axis\n * onto a retriever whose original concern was arbitrary predicates.\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 && query.provenanceSource === undefined) {\n          return succeed([]);\n        }\n        const ordered: IMemoryRecord<unknown>[] = selectByQuery(this._index.entries(), query).sort(\n          orderingCompare(query.orderBy)\n        );\n        return succeed(limitRecords(ordered, query.limit, query.offset));\n      })\n    );\n  }\n}\n"]}
+{"version":3,"file":"structuredFilterRetriever.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/structuredFilterRetriever.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,OAAO,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAKL,yBAAyB,EACzB,0BAA0B,EAC1B,YAAY,EACb,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAO,yBAAyB;IAIpC,YAAoB,MAA8B;QAChD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC;IACnC,CAAC;IAED,kDAAkD;IAClD,IAAW,YAAY;QACrB,OAAO,yBAAyB,CAAC;IACnC,CAAC;IAED,iCAAiC;IAC1B,MAAM,CAAC,MAAM,CAAC,MAA8B;QACjD,OAAO,OAAO,CAAC,IAAI,yBAAyB,CAAC,MAAM,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,8CAA8C;IACvC,QAAQ,CAAC,KAAmB;QACjC,OAAO,OAAO,CAAC,OAAO,CACpB,0BAA0B,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE;YAClE,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;gBACvE,OAAO,OAAO,CAAC,EAAE,CAAC,CAAC;YACrB,CAAC;YACD,OAAO,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACpE,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord, IMemoryRecordResolver } from '../types';\nimport { IMemoryIndex } from '../index';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  IRetrieverCreateParams,\n  NON_SEMANTIC_CAPABILITIES,\n  guardRetrieverCapabilities,\n  resolveQuery\n} from './retriever';\n\n/**\n * Returns records matching `query.filter` or `query.provenanceSource`, narrowed\n * by any scope / kind / tag / provenance-source pre-filter and recency-ordered.\n * Those two are this retriever's axes: a query carrying neither is not its\n * concern and yields an empty success (so it contributes nothing to a\n * {@link HybridRetriever}, rather than failing).\n *\n * Note `provenanceSource` appears on both sides of that sentence, and the\n * duplication is real rather than sloppy: it is one of this retriever's two\n * *dispatch* axes (it decides whether the query is this retriever's concern at\n * all) **and** a member of the shared *pre-filter* (it narrows the result set,\n * as it does for every other retriever). `filter` is likewise both.\n *\n * @remarks\n * `provenanceSource` is *applied* by the shared pre-filter, so every retriever\n * narrows by it. What this retriever adds is *answering* a query whose only axis\n * is `provenanceSource` — the \"show me everything this source produced\" request,\n * which would otherwise fall through the `filter`-absent guard and come back\n * empty.\n *\n * Consequently, inside a {@link HybridRetriever} composed with the universal\n * {@link RecencyRetriever}, a `provenanceSource`-only query is answered by both\n * children and every matching record scores twice under a score-union merge.\n * That is the established behavior for a dedicated-axis retriever composed with\n * the universal one — {@link TagRetriever} double-scores a `tag`-only query the\n * same way — and is intentional here, not an artifact of grafting a second axis\n * onto a retriever whose original concern was arbitrary predicates.\n * @public\n */\nexport class StructuredFilterRetriever implements IMemoryRetriever {\n  private readonly _index: IMemoryIndex;\n  private readonly _resolver: IMemoryRecordResolver;\n\n  private constructor(params: IRetrieverCreateParams) {\n    this._index = params.index;\n    this._resolver = params.resolver;\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(params: IRetrieverCreateParams): Result<StructuredFilterRetriever> {\n    return succeed(new StructuredFilterRetriever(params));\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 && query.provenanceSource === undefined) {\n          return succeed([]);\n        }\n        return resolveQuery(this._index.entries(), query, this._resolver);\n      })\n    );\n  }\n}\n"]}

package/dist/packlets/retrieve/tagRetriever.js

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: MIT
  */
 import { succeed } from '@fgv/ts-utils';
-import { NON_SEMANTIC_CAPABILITIES, guardRetrieverCapabilities, limitRecords, orderingCompare, selectByQuery } from './retriever';
+import { NON_SEMANTIC_CAPABILITIES, guardRetrieverCapabilities, resolveQuery } from './retriever';
 /**
  * Returns records carrying `query.tag`, recency-ordered within the tag and
  * narrowed by any scope / kind / provenance-source / predicate filters. Tag is this retriever's
@@ -12,16 +12,17 @@ import { NON_SEMANTIC_CAPABILITIES, guardRetrieverCapabilities, limitRecords, or
  * @public
  */
 export class TagRetriever {
-    constructor(index) {
-        this._index = index;
+    constructor(params) {
+        this._index = params.index;
+        this._resolver = params.resolver;
     }
     /** {@inheritDoc IMemoryRetriever.capabilities} */
     get capabilities() {
         return NON_SEMANTIC_CAPABILITIES;
     }
     /** Family-convention factory. */
-    static create(index) {
-        return succeed(new TagRetriever(index));
+    static create(params) {
+        return succeed(new TagRetriever(params));
     }
     /** {@inheritDoc IMemoryRetriever.retrieve} */
     retrieve(query) {
@@ -29,8 +30,7 @@ export class TagRetriever {
             if (query.tag === undefined) {
                 return succeed([]);
             }
-            const ordered = selectByQuery(this._index.entries(), query).sort(orderingCompare(query.orderBy));
-            return succeed(limitRecords(ordered, query.limit, query.offset));
+            return resolveQuery(this._index.entries(), query, this._resolver);
         }));
     }
 }

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

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

package/dist/packlets/retrieve/temporalRetrievers.js

@@ -4,7 +4,7 @@
  */
 import { succeed } from '@fgv/ts-utils';
 import { isTemporalRecord, selectCurrentVersion, selectVersionAsOf } from '../types';
-import { guardRetrieverCapabilities, indexedRecordMatchesQuery, limitRecords, recencyCompare } from './retriever';
+import { guardRetrieverCapabilities, indexedRecordMatchesQuery, materializePage, recencyCompare } from './retriever';
 /**
  * The capabilities every temporal retriever exposes: temporal "as-of" queries
  * are operational (semantic recall and link traversal are not this retriever's
@@ -25,16 +25,16 @@ export const TEMPORAL_CAPABILITIES = {
 function groupTemporalVersionsByEntity(index, query) {
     const groups = new Map();
     for (const entry of index.entries()) {
-        if (!isTemporalRecord(entry.record) || !indexedRecordMatchesQuery(entry, query)) {
+        if (!isTemporalRecord(entry) || !indexedRecordMatchesQuery(entry, query)) {
             continue;
         }
-        const key = `${entry.record.envelope.kind}\0${entry.record.envelope.entityId}`;
+        const key = `${entry.envelope.kind}\0${entry.envelope.entityId}`;
         const existing = groups.get(key);
         if (existing === undefined) {
-            groups.set(key, [entry.record]);
+            groups.set(key, [entry]);
         }
         else {
-            existing.push(entry.record);
+            existing.push(entry);
         }
     }
     return groups;
@@ -47,16 +47,17 @@ function groupTemporalVersionsByEntity(index, query) {
  * @public
  */
 export class CurrentValidRetriever {
-    constructor(index) {
-        this._index = index;
+    constructor(params) {
+        this._index = params.index;
+        this._resolver = params.resolver;
     }
     /** {@inheritDoc IMemoryRetriever.capabilities} */
     get capabilities() {
         return TEMPORAL_CAPABILITIES;
     }
     /** Family-convention factory. */
-    static create(index) {
-        return succeed(new CurrentValidRetriever(index));
+    static create(params) {
+        return succeed(new CurrentValidRetriever(params));
     }
     /** {@inheritDoc IMemoryRetriever.retrieve} */
     retrieve(query) {
@@ -69,7 +70,7 @@ export class CurrentValidRetriever {
                 }
             }
             selected.sort(recencyCompare);
-            return succeed(limitRecords(selected, query.limit, query.offset));
+            return materializePage(selected, query, this._resolver);
         }));
     }
 }
@@ -82,16 +83,17 @@ export class CurrentValidRetriever {
  * @public
  */
 export class AsOfRetriever {
-    constructor(index) {
-        this._index = index;
+    constructor(params) {
+        this._index = params.index;
+        this._resolver = params.resolver;
     }
     /** {@inheritDoc IMemoryRetriever.capabilities} */
     get capabilities() {
         return TEMPORAL_CAPABILITIES;
     }
     /** Family-convention factory. */
-    static create(index) {
-        return succeed(new AsOfRetriever(index));
+    static create(params) {
+        return succeed(new AsOfRetriever(params));
     }
     /** {@inheritDoc IMemoryRetriever.retrieve} */
     retrieve(query) {
@@ -108,7 +110,7 @@ export class AsOfRetriever {
                 }
             }
             selected.sort(recencyCompare);
-            return succeed(limitRecords(selected, query.limit, query.offset));
+            return materializePage(selected, query, this._resolver);
         }));
     }
 }
@@ -126,16 +128,17 @@ export class AsOfRetriever {
  * @public
  */
 export class HistoryRetriever {
-    constructor(index) {
-        this._index = index;
+    constructor(params) {
+        this._index = params.index;
+        this._resolver = params.resolver;
     }
     /** {@inheritDoc IMemoryRetriever.capabilities} */
     get capabilities() {
         return TEMPORAL_CAPABILITIES;
     }
     /** Family-convention factory. */
-    static create(index) {
-        return succeed(new HistoryRetriever(index));
+    static create(params) {
+        return succeed(new HistoryRetriever(params));
     }
     /** {@inheritDoc IMemoryRetriever.retrieve} */
     retrieve(query) {
@@ -145,7 +148,7 @@ export class HistoryRetriever {
                 history.push(...versions);
             }
             history.sort(HistoryRetriever._byValidAtAscending);
-            return succeed(limitRecords(history, query.limit, query.offset));
+            return materializePage(history, query, this._resolver);
         }));
     }
     /** A version's world-truth start: its `valid_at`, defaulting to `created` when absent. */

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

@@ -1 +1 @@
-{"version":3,"file":"temporalRetrievers.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/temporalRetrievers.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, succeed } from '@fgv/ts-utils';\nimport { IMemoryRecord, isTemporalRecord, selectCurrentVersion, selectVersionAsOf } from '../types';\nimport { IMemoryIndex } from '../index';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  guardRetrieverCapabilities,\n  indexedRecordMatchesQuery,\n  limitRecords,\n  recencyCompare\n} from './retriever';\n\n/**\n * The capabilities every temporal retriever exposes: temporal \"as-of\" queries\n * are operational (semantic recall and link traversal are not this retriever's\n * concern).\n * @public\n */\nexport const TEMPORAL_CAPABILITIES: IMemoryRetrieverCapabilities = {\n  supportsSemanticRecall: false,\n  supportsTemporalQuery: true,\n  supportsLinkTraversal: false\n};\n\n/**\n * Group the temporal records surviving a query's scope / kind / tag / provenance-source / predicate\n * pre-filter by entity (`kind` + `entityId`). Non-temporal records are excluded —\n * the temporal retrievers operate only over versioned entities. The map values\n * are each entity's versions (unordered).\n */\nfunction groupTemporalVersionsByEntity(\n  index: IMemoryIndex,\n  query: IMemoryQuery\n): Map<string, IMemoryRecord<unknown>[]> {\n  const groups: Map<string, IMemoryRecord<unknown>[]> = new Map<string, IMemoryRecord<unknown>[]>();\n  for (const entry of index.entries()) {\n    if (!isTemporalRecord(entry.record) || !indexedRecordMatchesQuery(entry, query)) {\n      continue;\n    }\n    const key: string = `${entry.record.envelope.kind}\\0${entry.record.envelope.entityId}`;\n    const existing: IMemoryRecord<unknown>[] | undefined = groups.get(key);\n    if (existing === undefined) {\n      groups.set(key, [entry.record]);\n    } else {\n      existing.push(entry.record);\n    }\n  }\n  return groups;\n}\n\n/**\n * Temporal retriever returning the **current** version of each temporal entity\n * matching the query (the newest version whose `invalid_at` is null/absent),\n * recency-ordered and limited. A fully-invalidated (soft-deleted) entity\n * contributes nothing. Non-temporal records are not this retriever's concern.\n * @public\n */\nexport class CurrentValidRetriever 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 TEMPORAL_CAPABILITIES;\n  }\n\n  /** Family-convention factory. */\n  public static create(index: IMemoryIndex): Result<CurrentValidRetriever> {\n    return succeed(new CurrentValidRetriever(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 selected: IMemoryRecord<unknown>[] = [];\n        for (const versions of groupTemporalVersionsByEntity(this._index, query).values()) {\n          const current: IMemoryRecord<unknown> | undefined = selectCurrentVersion(versions);\n          if (current !== undefined) {\n            selected.push(current);\n          }\n        }\n        selected.sort(recencyCompare);\n        return succeed(limitRecords(selected, query.limit, query.offset));\n      })\n    );\n  }\n}\n\n/**\n * Temporal retriever returning, for each temporal entity matching the query, the\n * version valid at `query.asOf` (epoch ms). `asOf` is this retriever's axis: a\n * query without it yields an empty success (a no-op contribution to a\n * {@link HybridRetriever}, not a failure). Results are recency-ordered and\n * limited.\n * @public\n */\nexport class AsOfRetriever 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 TEMPORAL_CAPABILITIES;\n  }\n\n  /** Family-convention factory. */\n  public static create(index: IMemoryIndex): Result<AsOfRetriever> {\n    return succeed(new AsOfRetriever(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.asOf === undefined) {\n          return succeed([]);\n        }\n        const asOf: number = query.asOf;\n        const selected: IMemoryRecord<unknown>[] = [];\n        for (const versions of groupTemporalVersionsByEntity(this._index, query).values()) {\n          const valid: IMemoryRecord<unknown> | undefined = selectVersionAsOf(versions, asOf);\n          if (valid !== undefined) {\n            selected.push(valid);\n          }\n        }\n        selected.sort(recencyCompare);\n        return succeed(limitRecords(selected, query.limit, query.offset));\n      })\n    );\n  }\n}\n\n/**\n * Temporal retriever returning **every** version of each temporal entity matching\n * the query, ordered ascending by `valid_at` (then `seq` as a stable tiebreak) —\n * the entity's full history. Limited after ordering.\n *\n * @remarks\n * When the query matches more than one entity, the result is a single\n * CROSS-entity list globally sorted by `valid_at` — versions of different\n * entities interleave, NOT grouped per entity — so `limit` truncates that\n * globally-sorted list. Constrain to one entity (e.g. via `query.scope`) for a\n * single entity's contiguous history.\n * @public\n */\nexport class HistoryRetriever 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 TEMPORAL_CAPABILITIES;\n  }\n\n  /** Family-convention factory. */\n  public static create(index: IMemoryIndex): Result<HistoryRetriever> {\n    return succeed(new HistoryRetriever(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 history: IMemoryRecord<unknown>[] = [];\n        for (const versions of groupTemporalVersionsByEntity(this._index, query).values()) {\n          history.push(...versions);\n        }\n        history.sort(HistoryRetriever._byValidAtAscending);\n        return succeed(limitRecords(history, query.limit, query.offset));\n      })\n    );\n  }\n\n  /** A version's world-truth start: its `valid_at`, defaulting to `created` when absent. */\n  private static _startOf(record: IMemoryRecord<unknown>): number {\n    const temporal: IMemoryRecord<unknown>['envelope']['temporal'] = record.envelope.temporal;\n    /* c8 ignore next 3 -- unreachable: HistoryRetriever orders only temporal records (pre-filtered by isTemporalRecord), so `temporal` is always present; the guard keeps the type honest */\n    if (temporal === undefined) {\n      return record.envelope.created;\n    }\n    return temporal.valid_at ?? record.envelope.created;\n  }\n\n  /**\n   * Ascending-by-`valid_at` comparator (a version's `valid_at` defaults to its\n   * `created` when absent), with `seq` as a stable ascending tiebreak so\n   * same-instant versions order by write sequence.\n   */\n  private static _byValidAtAscending(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number {\n    const aStart: number = HistoryRetriever._startOf(a);\n    const bStart: number = HistoryRetriever._startOf(b);\n    return aStart !== bStart ? aStart - bStart : a.envelope.seq - b.envelope.seq;\n  }\n}\n"]}
+{"version":3,"file":"temporalRetrievers.js","sourceRoot":"","sources":["../../../src/packlets/retrieve/temporalRetrievers.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Result, succeed } from '@fgv/ts-utils';\nimport {\n  IMemoryRecord,\n  IMemoryRecordResolver,\n  isTemporalRecord,\n  selectCurrentVersion,\n  selectVersionAsOf\n} from '../types';\nimport { IIndexedMemoryEntry, IMemoryIndex } from '../index';\nimport {\n  IMemoryQuery,\n  IMemoryRetriever,\n  IMemoryRetrieverCapabilities,\n  IRetrieverCreateParams,\n  guardRetrieverCapabilities,\n  indexedRecordMatchesQuery,\n  materializePage,\n  recencyCompare\n} from './retriever';\n\n/**\n * The capabilities every temporal retriever exposes: temporal \"as-of\" queries\n * are operational (semantic recall and link traversal are not this retriever's\n * concern).\n * @public\n */\nexport const TEMPORAL_CAPABILITIES: IMemoryRetrieverCapabilities = {\n  supportsSemanticRecall: false,\n  supportsTemporalQuery: true,\n  supportsLinkTraversal: false\n};\n\n/**\n * Group the temporal records surviving a query's scope / kind / tag / provenance-source / predicate\n * pre-filter by entity (`kind` + `entityId`). Non-temporal records are excluded —\n * the temporal retrievers operate only over versioned entities. The map values\n * are each entity's versions (unordered).\n */\nfunction groupTemporalVersionsByEntity(\n  index: IMemoryIndex,\n  query: IMemoryQuery\n): Map<string, IIndexedMemoryEntry[]> {\n  const groups: Map<string, IIndexedMemoryEntry[]> = new Map<string, IIndexedMemoryEntry[]>();\n  for (const entry of index.entries()) {\n    if (!isTemporalRecord(entry) || !indexedRecordMatchesQuery(entry, query)) {\n      continue;\n    }\n    const key: string = `${entry.envelope.kind}\\0${entry.envelope.entityId}`;\n    const existing: IIndexedMemoryEntry[] | undefined = groups.get(key);\n    if (existing === undefined) {\n      groups.set(key, [entry]);\n    } else {\n      existing.push(entry);\n    }\n  }\n  return groups;\n}\n\n/**\n * Temporal retriever returning the **current** version of each temporal entity\n * matching the query (the newest version whose `invalid_at` is null/absent),\n * recency-ordered and limited. A fully-invalidated (soft-deleted) entity\n * contributes nothing. Non-temporal records are not this retriever's concern.\n * @public\n */\nexport class CurrentValidRetriever implements IMemoryRetriever {\n  private readonly _index: IMemoryIndex;\n  private readonly _resolver: IMemoryRecordResolver;\n\n  private constructor(params: IRetrieverCreateParams) {\n    this._index = params.index;\n    this._resolver = params.resolver;\n  }\n\n  /** {@inheritDoc IMemoryRetriever.capabilities} */\n  public get capabilities(): IMemoryRetrieverCapabilities {\n    return TEMPORAL_CAPABILITIES;\n  }\n\n  /** Family-convention factory. */\n  public static create(params: IRetrieverCreateParams): Result<CurrentValidRetriever> {\n    return succeed(new CurrentValidRetriever(params));\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 selected: IIndexedMemoryEntry[] = [];\n        for (const versions of groupTemporalVersionsByEntity(this._index, query).values()) {\n          const current: IIndexedMemoryEntry | undefined = selectCurrentVersion(versions);\n          if (current !== undefined) {\n            selected.push(current);\n          }\n        }\n        selected.sort(recencyCompare);\n        return materializePage(selected, query, this._resolver);\n      })\n    );\n  }\n}\n\n/**\n * Temporal retriever returning, for each temporal entity matching the query, the\n * version valid at `query.asOf` (epoch ms). `asOf` is this retriever's axis: a\n * query without it yields an empty success (a no-op contribution to a\n * {@link HybridRetriever}, not a failure). Results are recency-ordered and\n * limited.\n * @public\n */\nexport class AsOfRetriever implements IMemoryRetriever {\n  private readonly _index: IMemoryIndex;\n  private readonly _resolver: IMemoryRecordResolver;\n\n  private constructor(params: IRetrieverCreateParams) {\n    this._index = params.index;\n    this._resolver = params.resolver;\n  }\n\n  /** {@inheritDoc IMemoryRetriever.capabilities} */\n  public get capabilities(): IMemoryRetrieverCapabilities {\n    return TEMPORAL_CAPABILITIES;\n  }\n\n  /** Family-convention factory. */\n  public static create(params: IRetrieverCreateParams): Result<AsOfRetriever> {\n    return succeed(new AsOfRetriever(params));\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.asOf === undefined) {\n          return succeed([]);\n        }\n        const asOf: number = query.asOf;\n        const selected: IIndexedMemoryEntry[] = [];\n        for (const versions of groupTemporalVersionsByEntity(this._index, query).values()) {\n          const valid: IIndexedMemoryEntry | undefined = selectVersionAsOf(versions, asOf);\n          if (valid !== undefined) {\n            selected.push(valid);\n          }\n        }\n        selected.sort(recencyCompare);\n        return materializePage(selected, query, this._resolver);\n      })\n    );\n  }\n}\n\n/**\n * Temporal retriever returning **every** version of each temporal entity matching\n * the query, ordered ascending by `valid_at` (then `seq` as a stable tiebreak) —\n * the entity's full history. Limited after ordering.\n *\n * @remarks\n * When the query matches more than one entity, the result is a single\n * CROSS-entity list globally sorted by `valid_at` — versions of different\n * entities interleave, NOT grouped per entity — so `limit` truncates that\n * globally-sorted list. Constrain to one entity (e.g. via `query.scope`) for a\n * single entity's contiguous history.\n * @public\n */\nexport class HistoryRetriever implements IMemoryRetriever {\n  private readonly _index: IMemoryIndex;\n  private readonly _resolver: IMemoryRecordResolver;\n\n  private constructor(params: IRetrieverCreateParams) {\n    this._index = params.index;\n    this._resolver = params.resolver;\n  }\n\n  /** {@inheritDoc IMemoryRetriever.capabilities} */\n  public get capabilities(): IMemoryRetrieverCapabilities {\n    return TEMPORAL_CAPABILITIES;\n  }\n\n  /** Family-convention factory. */\n  public static create(params: IRetrieverCreateParams): Result<HistoryRetriever> {\n    return succeed(new HistoryRetriever(params));\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 history: IIndexedMemoryEntry[] = [];\n        for (const versions of groupTemporalVersionsByEntity(this._index, query).values()) {\n          history.push(...versions);\n        }\n        history.sort(HistoryRetriever._byValidAtAscending);\n        return materializePage(history, query, this._resolver);\n      })\n    );\n  }\n\n  /** A version's world-truth start: its `valid_at`, defaulting to `created` when absent. */\n  private static _startOf(record: IIndexedMemoryEntry): number {\n    const temporal: IMemoryRecord<unknown>['envelope']['temporal'] = record.envelope.temporal;\n    /* c8 ignore next 3 -- unreachable: HistoryRetriever orders only temporal records (pre-filtered by isTemporalRecord), so `temporal` is always present; the guard keeps the type honest */\n    if (temporal === undefined) {\n      return record.envelope.created;\n    }\n    return temporal.valid_at ?? record.envelope.created;\n  }\n\n  /**\n   * Ascending-by-`valid_at` comparator (a version's `valid_at` defaults to its\n   * `created` when absent), with `seq` as a stable ascending tiebreak so\n   * same-instant versions order by write sequence.\n   */\n  private static _byValidAtAscending(a: IIndexedMemoryEntry, b: IIndexedMemoryEntry): number {\n    const aStart: number = HistoryRetriever._startOf(a);\n    const bStart: number = HistoryRetriever._startOf(b);\n    return aStart !== bStart ? aStart - bStart : a.envelope.seq - b.envelope.seq;\n  }\n}\n"]}

package/dist/packlets/store/coverage.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+export {};
+//# sourceMappingURL=coverage.js.map

package/dist/packlets/store/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../../../src/packlets/store/coverage.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport { Kind } from '../types';\n\n/**\n * How much of one derived artifact exists, for one {@link Kind}.\n *\n * @remarks\n * Two numbers rather than a percentage, deliberately: a ratio cannot express\n * *\"nothing was expected\"*, and a kind that is intentionally not derived (an\n * excluded kind, a kind with no projector) is a normal and healthy state that a\n * `0%` would render as an alarm.\n * @public\n */\nexport interface IArtifactCoverage {\n  /**\n   * Records of this kind the store would derive this artifact for, **after** any\n   * exclusion. Read against {@link IDerivedStateCoverage.records} for the same\n   * kind: `records: 40, expected: 0` is the exclusion story, stated rather than\n   * inferred.\n   */\n  readonly expected: number;\n  /**\n   * Of those, how many the **store believes** are covered. See\n   * {@link IIndexCoverage.indexSize} for why the word \"believes\" is load-bearing.\n   */\n  readonly covered: number;\n}\n\n/**\n * Coverage of the record-granular vector index.\n * @public\n */\nexport interface IIndexCoverage {\n  /** Per-kind expected/covered, derived from the envelope walk. */\n  readonly perKind: ReadonlyMap<Kind, IArtifactCoverage>;\n  /**\n   * What the index **actually holds**, whole-index.\n   *\n   * @remarks\n   * **This is a fact and {@link IArtifactCoverage.covered} is a belief, and the\n   * two are reported separately because their disagreement is the only free\n   * signal that distinguishes a persistent index from a fresh one.** `covered`\n   * counts envelopes carrying an `embeddingRef`; `indexSize` counts vectors. With\n   * a persistent index they agree. With an in-memory index at open they do not —\n   * the envelopes still claim references from previous sessions while the index\n   * holds nothing, so `covered` **lies, in the confident direction**.\n   *\n   * Collapsing them into one \"coverage %\" would destroy that signal, which is why\n   * this type does not offer one.\n   */\n  readonly indexSize: number;\n}\n\n/**\n * Coverage of the fragment-granular vector index.\n *\n * @remarks\n * **Aggregate only, and the reason is structural rather than an omission.** The\n * record lane has a per-record marker on the envelope (`embeddingRef`), so its\n * numerator falls out of the same free walk that produces the denominator. The\n * fragment lane has **no envelope marker at all** — nothing on a record says\n * whether it has fragments — so a per-kind numerator would cost one\n * `IFragmentVectorIndex.has` call per record, and coverage is contractually\n * cheap (see {@link IMemoryStore.coverage}).\n *\n * The per-kind **denominator** is still available on\n * {@link IDerivedStateCoverage.records}. A caller who needs the per-kind\n * numerator runs `reconcile(kind, 'fragment-vector')`, which reports it because\n * it is already paying for the walk.\n * @public\n */\nexport interface IFragmentIndexCoverage {\n  /** Records with at least one fragment held. Mirrors `IFragmentVectorIndex.recordCount`. */\n  readonly indexRecordCount: number;\n  /** Total fragments held — the fan-out. Mirrors `IFragmentVectorIndex.fragmentCount`. */\n  readonly indexFragmentCount: number;\n}\n\n/**\n * A snapshot of how much of the store's **derived state** exists, resolved by\n * {@link Kind} — the answer to *\"is my derived state consistent with my\n * records?\"*.\n *\n * @remarks\n * **Absent is not zero.** Each artifact member is optional, and `undefined` means\n * *this artifact is not derived here at all* — no rank projector is registered,\n * or that index lane is not wired. It never means *nothing is covered*. Folding\n * the two would make a health surface render a confident `0%` for a feature the\n * deployment deliberately did not turn on, which is the same defect as\n * `embeddingRef`'s three-way ambiguity one level up.\n *\n * So: `fragmentVectors: undefined` is a store with no fragment index and is not a\n * problem. `fragmentVectors: { indexRecordCount: 0, indexFragmentCount: 0 }` is a\n * wired fragment index holding nothing, and probably is.\n * @public\n */\nexport interface IDerivedStateCoverage {\n  /** Records per kind — the denominator every other number is read against. */\n  readonly records: ReadonlyMap<Kind, number>;\n  /** Absent when no kind has a registered {@link RankProjector}. */\n  readonly rank?: ReadonlyMap<Kind, IArtifactCoverage>;\n  /** Absent when the record-vector lane is not wired. */\n  readonly recordVectors?: IIndexCoverage;\n  /** Absent when the fragment lane is not wired. */\n  readonly fragmentVectors?: IFragmentIndexCoverage;\n}\n"]}