@fgv/ts-agent-memory 5.1.0-47 → 5.1.0-48

package/src/packlets/retrieve/linkTraversalRetriever.ts

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

package/src/packlets/retrieve/recencyRetriever.ts

@@ -1,54 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import { Result, succeed } from '@fgv/ts-utils';
-import { IMemoryRecord } from '../types';
-import { IMemoryIndex } from '../index';
-import {
-  IMemoryQuery,
-  IMemoryRetriever,
-  IMemoryRetrieverCapabilities,
-  NON_SEMANTIC_CAPABILITIES,
-  guardRetrieverCapabilities,
-  limitRecords,
-  orderingCompare,
-  selectByQuery
-} from './retriever';
-
-/**
- * Returns records matching the query's scope / kind / tag / predicate filters,
- * ordered most-recently-updated first. The universal v1 retriever — an empty
- * query returns the whole vault in recency order.
- * @public
- */
-export class RecencyRetriever implements IMemoryRetriever {
-  private readonly _index: IMemoryIndex;
-
-  private constructor(index: IMemoryIndex) {
-    this._index = index;
-  }
-
-  /** {@inheritDoc IMemoryRetriever.capabilities} */
-  public get capabilities(): IMemoryRetrieverCapabilities {
-    return NON_SEMANTIC_CAPABILITIES;
-  }
-
-  /** Family-convention factory. */
-  public static create(index: IMemoryIndex): Result<RecencyRetriever> {
-    return succeed(new RecencyRetriever(index));
-  }
-
-  /** {@inheritDoc IMemoryRetriever.retrieve} */
-  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {
-    return Promise.resolve(
-      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => {
-        const ordered: IMemoryRecord<unknown>[] = selectByQuery(this._index.entries(), query).sort(
-          orderingCompare(query.orderBy)
-        );
-        return succeed(limitRecords(ordered, query.limit, query.offset));
-      })
-    );
-  }
-}

package/src/packlets/retrieve/retriever.ts

@@ -1,291 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import { Result, fail, succeed } from '@fgv/ts-utils';
-import { IEdgeTarget, IMemoryRecord, Kind, 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 — the single-kind shorthand for
-   * {@link IMemoryQuery.kinds | kinds}. When both are set they compose as AND
-   * (the record's kind must satisfy both), so `kind` must itself be a member of
-   * `kinds` for anything to match.
-   */
-  readonly kind?: Kind;
-  /**
-   * Restrict to records in ANY of these kinds — the general (multi-kind) form of
-   * {@link IMemoryQuery.kind | kind}. Absent → no kind-set constraint (today's
-   * behavior). An explicit empty array `[]` matches NOTHING (mirroring the
-   * non-positive-`limit` "explicit empty" convention), never "match all".
-   */
-  readonly kinds?: ReadonlyArray<Kind>;
-  /** Restrict to records linked FROM this scope-qualified seed (outbound). */
-  readonly linkedFrom?: IEdgeTarget;
-  /** Restrict to records linked TO this scope-qualified seed (inbound / backlinks). */
-  readonly linkedTo?: IEdgeTarget;
-  /** 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;
-  /**
-   * Ordering for the result set. `'recency'` (the default when absent — today's
-   * exact behavior) orders most-recently-updated first; `'rank'` orders by the
-   * store-computed {@link IMemoryEnvelope.rank} descending (records with an absent
-   * `rank` last), with recency as the tiebreak. Combined with `{ limit, offset }`
-   * this yields a bounded top-M rank-ordered page with no full-vault scan.
-   *
-   * @remarks
-   * `orderBy` governs the ordered non-semantic retrievers (recency / tag /
-   * structured-filter / link-traversal) and the {@link HybridRetriever}'s
-   * post-merge ordering. The {@link SemanticRetriever} is the sole exception: it
-   * preserves its native vector-similarity order regardless of `orderBy` —
-   * re-sorting semantic hits by `rank` would discard the similarity ranking that
-   * is the whole point of that path; a consumer that wants rank ordering uses a
-   * non-semantic query.
-   */
-  readonly orderBy?: 'recency' | 'rank';
-  /** Maximum records to return. Applied after all other filters. */
-  readonly limit?: number;
-  /**
-   * Records to skip after ordering, before `limit` — so `{ offset, limit }` is a
-   * stable page window over the ordered result set. Default 0. A non-positive or
-   * absent offset is today's behavior (no skip); an offset past the end yields an
-   * empty page, never a throw.
-   */
-  readonly offset?: 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 const SEMANTIC_UNWIRED_MESSAGE: string = '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
- */
-export const LINK_TRAVERSAL_UNWIRED_MESSAGE: string =
-  '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
- */
-export const NON_SEMANTIC_CAPABILITIES: IMemoryRetrieverCapabilities = {
-  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
- */
-export function temporalUnwiredMessage(kind?: Kind): string {
-  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
- */
-export function guardRetrieverCapabilities(
-  query: IMemoryQuery,
-  capabilities: IMemoryRetrieverCapabilities
-): Result<true> {
-  if (query.semantic !== undefined && !capabilities.supportsSemanticRecall) {
-    return fail(SEMANTIC_UNWIRED_MESSAGE);
-  }
-  if (query.asOf !== undefined && !capabilities.supportsTemporalQuery) {
-    return fail(temporalUnwiredMessage(query.kind));
-  }
-  const requestsLinkTraversal: boolean =
-    query.linkedFrom !== undefined || query.linkedTo !== undefined || query.hops !== undefined;
-  if (requestsLinkTraversal && !capabilities.supportsLinkTraversal) {
-    return fail(LINK_TRAVERSAL_UNWIRED_MESSAGE);
-  }
-  return succeed(true);
-}
-
-/**
- * Recency comparator: most-recently-updated first, with a `seq` tiebreak so
- * equal-`updated` records sort deterministically. Mirrors the B1 index ordering.
- * @public
- */
-export function recencyCompare(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number {
-  const byUpdated: number = b.envelope.updated - a.envelope.updated;
-  return byUpdated !== 0 ? byUpdated : b.envelope.seq - a.envelope.seq;
-}
-
-/**
- * Rank comparator: store-computed {@link IMemoryEnvelope.rank} descending, with
- * {@link recencyCompare} as the tiebreak. Records with an absent `rank` sort LAST
- * (after every ranked record), then by recency among themselves. Mirrors the
- * index's rank-view ordering.
- * @public
- */
-export function rankCompare(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number {
-  const ra: number | undefined = a.envelope.rank;
-  const rb: number | undefined = b.envelope.rank;
-  if (ra === undefined && rb !== undefined) {
-    return 1;
-  }
-  if (rb === undefined && ra !== undefined) {
-    return -1;
-  }
-  if (ra !== undefined && rb !== undefined && ra !== rb) {
-    return rb - ra;
-  }
-  return recencyCompare(a, b);
-}
-
-/**
- * Select the record comparator for a query's {@link IMemoryQuery.orderBy | orderBy}
- * axis: {@link rankCompare} for `'rank'`, {@link recencyCompare} otherwise (the
- * default, byte-identical to the pre-`orderBy` behavior).
- * @public
- */
-export function orderingCompare(
-  orderBy?: IMemoryQuery['orderBy']
-): (a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>) => number {
-  return orderBy === 'rank' ? rankCompare : recencyCompare;
-}
-
-/**
- * Whether an indexed entry satisfies a query's scope / kind / tag / predicate
- * pre-filter (the axes shared by every v1 retriever). The `semantic` / `asOf` /
- * link axes are NOT applied here — those are each retriever's own concern.
- * @public
- */
-export function indexedRecordMatchesQuery(entry: IIndexedMemoryRecord, query: IMemoryQuery): boolean {
-  if (query.scope !== undefined && entry.scope !== query.scope) {
-    return false;
-  }
-  if (query.kind !== undefined && entry.record.envelope.kind !== query.kind) {
-    return false;
-  }
-  if (query.kinds !== undefined && !query.kinds.includes(entry.record.envelope.kind)) {
-    return false;
-  }
-  if (query.tag !== undefined && !entry.record.envelope.tags.includes(query.tag)) {
-    return false;
-  }
-  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
- */
-export function selectByQuery(
-  entries: ReadonlyArray<IIndexedMemoryRecord>,
-  query: IMemoryQuery
-): IMemoryRecord<unknown>[] {
-  return entries.filter((entry) => indexedRecordMatchesQuery(entry, query)).map((entry) => entry.record);
-}
-
-/**
- * Apply the `{ offset, limit }` page window to an ordered record set. Applied
- * last, after ordering, so it always takes a stable window of the ordered
- * result. `offset` is applied first (records to skip), then `limit` (top-N of
- * the remainder).
- *
- * @remarks
- * Both bounds are public query input and are guarded against non-positive
- * values slipping into `slice`:
- * - `offset` absent or non-positive → no skip (today's behavior). An offset past
- *   the end yields an empty page rather than a throw.
- * - `limit` absent → no truncation; a non-positive `limit` means "no records"
- *   and returns an empty array.
- * @public
- */
-export function limitRecords(
-  records: ReadonlyArray<IMemoryRecord<unknown>>,
-  limit?: number,
-  offset?: number
-): ReadonlyArray<IMemoryRecord<unknown>> {
-  const skip: number = offset !== undefined && offset > 0 ? offset : 0;
-  const windowed: ReadonlyArray<IMemoryRecord<unknown>> = skip > 0 ? records.slice(skip) : records;
-  if (limit === undefined) {
-    return windowed;
-  }
-  if (limit <= 0) {
-    return [];
-  }
-  return windowed.length > limit ? windowed.slice(0, limit) : windowed;
-}

package/src/packlets/retrieve/semanticRetriever.ts

@@ -1,152 +0,0 @@
-/*
- * Copyright (c) 2026 Erik Fortune
- * SPDX-License-Identifier: MIT
- */
-
-import { Result, fail, succeed } from '@fgv/ts-utils';
-import { IMemoryRecord, edgeTargetKey } from '../types';
-import { IIndexedMemoryRecord, IMemoryIndex } from '../index';
-import { IVectorIndex, IVectorQueryHit } from '../vector';
-import {
-  IMemoryQuery,
-  IMemoryRetriever,
-  IMemoryRetrieverCapabilities,
-  SEMANTIC_UNWIRED_MESSAGE,
-  indexedRecordMatchesQuery,
-  limitRecords,
-  temporalUnwiredMessage
-} 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 class SemanticRetriever implements IMemoryRetriever {
-  private readonly _index: IMemoryIndex;
-  private readonly _backend: ISemanticBackend | undefined;
-
-  private constructor(index: IMemoryIndex, backend: ISemanticBackend | undefined) {
-    this._index = index;
-    this._backend = backend;
-  }
-
-  /** {@inheritDoc IMemoryRetriever.capabilities} */
-  public get capabilities(): IMemoryRetrieverCapabilities {
-    return {
-      supportsSemanticRecall: this._backend !== undefined,
-      supportsTemporalQuery: false,
-      supportsLinkTraversal: false
-    };
-  }
-
-  /** Family-convention factory. */
-  public static create(params: ISemanticRetrieverCreateParams): Result<SemanticRetriever> {
-    return succeed(new SemanticRetriever(params.index, params.backend));
-  }
-
-  /** {@inheritDoc IMemoryRetriever.retrieve} */
-  public async retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {
-    if (query.asOf !== undefined) {
-      return fail(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 succeed([]);
-    }
-    if (this._backend === undefined) {
-      return fail(SEMANTIC_UNWIRED_MESSAGE);
-    }
-    const backend: ISemanticBackend = 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: Result<Float32Array> = await SemanticRetriever._callBackend('query embedding', () =>
-      backend.embedQuery(query.semantic as string)
-    );
-    if (embedded.isFailure()) {
-      return fail(embedded.message);
-    }
-    const hits: Result<ReadonlyArray<IVectorQueryHit>> = await SemanticRetriever._callBackend(
-      'vector query',
-      () => backend.vectorIndex.query(embedded.value, query.topK ?? 10)
-    );
-    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: Map<string, IIndexedMemoryRecord> = new Map(
-      this._index
-        .entries()
-        .map((entry) => [edgeTargetKey({ scope: entry.scope, id: entry.record.envelope.id }), entry])
-    );
-    const records: IMemoryRecord<unknown>[] = [];
-    for (const hit of hits.value) {
-      const entry: IIndexedMemoryRecord | undefined = byKey.get(edgeTargetKey(hit.target));
-      if (entry !== undefined && indexedRecordMatchesQuery(entry, query)) {
-        records.push(entry.record);
-      }
-    }
-    return succeed(limitRecords(records, query.limit, query.offset));
-  }
-
-  /**
-   * 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 async _callBackend<T>(label: string, op: () => Promise<Result<T>>): Promise<Result<T>> {
-    try {
-      return (await op()).withErrorFormat((msg) => `semantic recall: ${label} failed: ${msg}`);
-    } catch (err) {
-      return fail(`semantic recall: ${label} failed: ${String(err)}`);
-    }
-  }
-}