@nanobpm/urban 0.69.0 → 0.70.0

package/dist/context/retrieval/source.js

@@ -0,0 +1,141 @@
+// Slice S4 (retrieval) — the READ seam over the git system-of-record.
+//
+// Retrieval treats git as the authoritative store: records live on disk under
+// the exact layout S3 defines (`records/<scope>/<scopeRef-bucket>/<id>.json`),
+// and this module reads them back. It is deliberately abstracted behind a
+// {@link RecordSource} interface so the derived hot cache, the query layer, and
+// a future PII/mutable backend all read through one seam rather than assuming a
+// public-git working copy. {@link GitRecordSource} is the default MVP: it walks
+// a resolved substrate working copy (the local checkout S1 produces, pinned to
+// its ref) using the S3 layout helpers to select record files.
+//
+// The source NEVER caches — it always reflects what is on disk (== the git ref
+// that is checked out). Caching is the derived index's job (see cache.ts), and
+// the index is disposable: a cold/empty index falls back to reading here, so
+// retrieval is correct even before any index is built.
+import { readdir, readFile } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { isRecordPath, LAYOUT_ROOT, recordDir, scopeDir, } from "../git/index.js";
+import { validateMemoryRecord, } from "../schema/index.js";
+/** Thrown when the underlying substrate cannot be read at all. */
+export class RecordSourceError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "RecordSourceError";
+    }
+}
+function isEnoent(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+/** Convert a native absolute path to a substrate-root-relative POSIX path. */
+function toPosixRelative(root, absPath) {
+    return relative(root, absPath).split(sep).join("/");
+}
+/**
+ * The default git-backed read source: reads records straight off a local
+ * substrate working copy. Git is the system of record; this holds no state of
+ * its own, so every call reflects the current on-disk (== checked-out ref)
+ * content. That is what makes the derived index safe to throw away and rebuild.
+ */
+export class GitRecordSource {
+    #root;
+    constructor(handle) {
+        const root = typeof handle === "string" ? handle : handle.localPath;
+        if (!isAbsolute(root)) {
+            throw new RecordSourceError(`substrate root must be an absolute path, got: ${root}`);
+        }
+        this.#root = root;
+    }
+    /** Absolute path of the substrate working copy this source reads from. */
+    get root() {
+        return this.#root;
+    }
+    async list(selector) {
+        const subtree = selectorSubtree(selector);
+        const walkRoot = join(this.#root, subtree);
+        let entries;
+        try {
+            entries = await readdir(walkRoot, { recursive: true, withFileTypes: true });
+        }
+        catch (error) {
+            // A missing subtree (e.g. an empty store, or a namespace with no records)
+            // is an empty result, not an error — a cold read must degrade gracefully.
+            if (isEnoent(error)) {
+                return [];
+            }
+            throw new RecordSourceError(`failed to list substrate at ${walkRoot}`, {
+                cause: error,
+            });
+        }
+        const results = [];
+        for (const entry of entries) {
+            if (!entry.isFile()) {
+                continue;
+            }
+            const absPath = join(entry.parentPath, entry.name);
+            const relPath = toPosixRelative(this.#root, absPath);
+            if (!isRecordPath(relPath)) {
+                continue;
+            }
+            const stored = await this.#readAbsolute(absPath, relPath);
+            if (stored !== undefined) {
+                results.push(stored);
+            }
+        }
+        // Deterministic order regardless of filesystem enumeration order.
+        results.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+        return results;
+    }
+    async read(relPath) {
+        const normalised = relPath.replace(/\\/g, "/").replace(/^\.\//, "");
+        if (!isRecordPath(normalised)) {
+            return undefined;
+        }
+        return this.#readAbsolute(join(this.#root, normalised), normalised);
+    }
+    async #readAbsolute(absPath, relPath) {
+        let raw;
+        try {
+            raw = await readFile(absPath, "utf8");
+        }
+        catch (error) {
+            if (isEnoent(error)) {
+                return undefined;
+            }
+            throw new RecordSourceError(`failed to read record at ${relPath}`, {
+                cause: error,
+            });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            // A corrupt / non-JSON file under the layout is skipped, not fatal.
+            return undefined;
+        }
+        const result = validateMemoryRecord(parsed);
+        if (!result.ok) {
+            // A file that does not validate against the S2 schema is not a record we
+            // can safely surface — skip it rather than return an unchecked shape.
+            return undefined;
+        }
+        return { path: relPath, record: result.record };
+    }
+}
+/**
+ * The layout subtree to walk for a selector: one namespace bucket, one whole
+ * scope, or the entire layout root. Keeps path-scoping in one place so the
+ * cache and query layers never re-derive layout paths themselves.
+ */
+export function selectorSubtree(selector) {
+    if (selector === undefined) {
+        return LAYOUT_ROOT;
+    }
+    return selector.scopeRef === undefined
+        ? scopeDir(selector.scope)
+        : recordDir(selector.scope, selector.scopeRef);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.69.0",
+	"version": "0.70.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",
@@ -103,7 +103,7 @@
 		"@nanobpm/nano-sdk": "^1.2.5",
 		"@nanobpm/workflow": "^0.12.0",
 		"bpmn-auto-layout": "^2.0.0-alpha.2",
-		"create-urban-app": "^0.14.0",
+		"create-urban-app": "^0.15.0",
 		"yaml": "^2.9.0"
 	},
 	"devDependencies": {

package/src/context/retrieval/NOTES.md

@@ -0,0 +1,68 @@
+# `@nanobpm/urban/context/retrieval` — S4 retrieval over git
+
+The **read** side of the Urban context layer. It queries the git
+system-of-record that S3 (`@nanobpm/urban/context/git`) writes, using the exact
+path/namespace layout S3 publishes — it does **not** invent its own layout.
+MVP is **git-only**: no external service.
+
+## Query surface (`ContextRetriever`)
+
+Bind a retriever to a resolved substrate handle (the local checkout S1 produces,
+`{ localPath, ref }`):
+
+```ts
+import { ContextRetriever } from "@nanobpm/urban/context/retrieval";
+const retriever = new ContextRetriever({ localPath, ref: "main" });
+```
+
+- `query(q)` — the general query. Clauses are **ANDed**; a clause given as an
+  array is an **OR-set**. Supports:
+  - **structured / path-scoped**: `scope`, `scopeRef` (uses S3's partitioning);
+  - **frontmatter filtering**: `mode`, `provenance`, `authority`, `id`,
+    `subject` (typed record fields);
+  - **text search**: `text` — case-insensitive substring across the record body
+    (`statement`, `subject`, `id`);
+  - `limit`.
+- `byNamespace(scope, scopeRef?)` — path-scoped structured query for one layout
+  partition; reads just that subtree when the cache is cold.
+- `search(text, filters?)` — text search combined with structured filters.
+- `all()` — every record (warms the cache).
+- `get(relPath)` — one record by its S3 layout path (bypasses the cache).
+
+## Git is the system of record; the cache is DERIVED and disposable
+
+Retrieval is correct **with a cold/empty cache** — every query falls back to
+reading git through the `RecordSource` seam. A query pinned to exactly one
+namespace (`scope` + a single `scopeRef`) reads **only that layout partition**,
+so a targeted query never pays to build the whole index.
+
+The hot cache (`DerivedRecordIndex`) is a **snapshot projection**, rebuildable
+purely from git and never authoritative:
+
+- `retriever.invalidate()` — drop the projection; the next read re-reads git.
+- `retriever.rebuild()` — eagerly re-project the whole store from git.
+- `retriever.cache.isWarm` — whether a snapshot is currently held.
+
+Callers keep the cache honest by calling `invalidate()` after a write (git
+remains the source of truth). A warm cache serves its snapshot until
+invalidated/rebuilt — it does not observe writes made after it was warmed.
+
+## Read seam (`RecordSource` / `GitRecordSource`)
+
+Reads go through a `RecordSource` interface, not a hard-wired public-git
+assumption. `GitRecordSource` is the default git-only MVP: it walks the resolved
+working copy, selects record files with S3's `isRecordPath`, and validates each
+against the S2 schema (`validateMemoryRecord`). Corrupt / non-record / invalid
+files under the layout are **skipped, not fatal**. A future PII/mutable backend
+can implement `RecordSource` without the cache, query layer, or callers changing.
+
+## Seam for a future opt-in embedding index (NOT built)
+
+Semantic/vector retrieval (an OpenMemory / mem0-style **derived** embedding
+index) is deliberately **not built** here — MVP retrieval is git-only lexical.
+`embedding.ts` declares the `EmbeddingIndex` seam it would plug into
+(`reindex(records)` + `semanticSearch(query, k)`), and `ContextRetriever`
+accepts an optional `embeddingIndex` for forward-compat. Any such index MUST be
+derived and disposable (rebuildable from git, never authoritative), exactly like
+the hot cache — a cold embedding index must degrade to the git-backed lexical
+path, never to stale/wrong results.

package/src/context/retrieval/cache.ts

@@ -0,0 +1,95 @@
+// Slice S4 (retrieval) — the DERIVED hot read cache/index.
+//
+// Git is the system of record; this index is a disposable, rebuildable-from-git
+// projection kept hot for fast repeated reads. It is NEVER authoritative:
+//   - a cold (never-built) index transparently reads through to the source on
+//     first use, so retrieval is correct even before any rebuild;
+//   - `invalidate()` drops the projection so the next read re-reads from git;
+//   - `rebuild()` re-reads the whole store eagerly.
+// Because it holds nothing git does not, throwing it away can never lose data.
+
+import type { NamespaceSelector, RecordSource, StoredRecord } from "./source.ts";
+
+/**
+ * A derived, in-memory index over a {@link RecordSource}. Holds a full snapshot
+ * of the store once warmed; cold reads and namespace-scoped reads fall back to
+ * the source directly so a cold/empty index is always correct.
+ */
+export class DerivedRecordIndex {
+  readonly #source: RecordSource;
+  // `undefined` == cold (never loaded / invalidated). An empty array is a valid
+  // WARM state (a store that genuinely has no records), distinct from cold.
+  #snapshot: readonly StoredRecord[] | undefined;
+
+  constructor(source: RecordSource) {
+    this.#source = source;
+  }
+
+  /** `true` once a full snapshot is loaded; `false` when cold/invalidated. */
+  get isWarm(): boolean {
+    return this.#snapshot !== undefined;
+  }
+
+  /** The read source this index is derived from (git, by default). */
+  get source(): RecordSource {
+    return this.#source;
+  }
+
+  /**
+   * Eagerly (re)load the full store snapshot from the source, replacing any
+   * existing projection. Cheap to call and idempotent — the whole point is that
+   * rebuilding is always safe because git remains the source of truth.
+   */
+  async rebuild(): Promise<readonly StoredRecord[]> {
+    const snapshot = await this.#source.list();
+    this.#snapshot = snapshot;
+    return snapshot;
+  }
+
+  /** Drop the projection so the next read re-reads from git. */
+  invalidate(): void {
+    this.#snapshot = undefined;
+  }
+
+  /**
+   * Return the full store, warming the index on a cold read. After this the
+   * index is warm; subsequent calls serve the cached snapshot without touching
+   * the filesystem until {@link invalidate} or {@link rebuild} is called.
+   */
+  async all(): Promise<readonly StoredRecord[]> {
+    if (this.#snapshot !== undefined) {
+      return this.#snapshot;
+    }
+    return this.rebuild();
+  }
+
+  /**
+   * Return the records in one namespace partition. When the index is already
+   * warm this filters the in-memory snapshot (no I/O); when cold it does a
+   * cheap, path-scoped read of JUST that partition from the source WITHOUT
+   * warming the whole index — so a targeted query never pays to load the store.
+   */
+  async namespace(
+    selector: NamespaceSelector,
+  ): Promise<readonly StoredRecord[]> {
+    if (this.#snapshot !== undefined) {
+      return this.#snapshot.filter((stored) =>
+        inNamespace(stored, selector),
+      );
+    }
+    return this.#source.list(selector);
+  }
+}
+
+/** `true` iff a stored record belongs to the given namespace partition. */
+function inNamespace(
+  stored: StoredRecord,
+  selector: NamespaceSelector,
+): boolean {
+  if (stored.record.scope !== selector.scope) {
+    return false;
+  }
+  return (
+    selector.scopeRef === undefined || stored.record.scopeRef === selector.scopeRef
+  );
+}

package/src/context/retrieval/embedding.ts

@@ -0,0 +1,45 @@
+// Slice S4 (retrieval) — SEAM ONLY for a future opt-in derived embedding index.
+//
+// The MVP retrieval is git-only: structured/path-scoped queries, frontmatter
+// filtering, and substring text search over the git system-of-record, with a
+// disposable hot cache. Semantic (vector) retrieval — an OpenMemory / mem0-style
+// derived embedding index — is deliberately NOT built here. This file only
+// declares the seam it would plug into, so a later slice can add it without
+// reshaping the retriever or its public API.
+//
+// Like the hot cache, any such embedding index MUST be DERIVED and disposable:
+// rebuildable purely from git, never authoritative. Nothing in this file
+// performs embedding, network I/O, or persistence — it is a type contract.
+
+import type { RetrievalQuery } from "./query.ts";
+import type { StoredRecord } from "./source.ts";
+
+/** A semantic match: a stored record plus the backend's similarity score. */
+export interface SemanticMatch {
+  readonly stored: StoredRecord;
+  /** Backend-defined similarity score; higher is more similar. */
+  readonly score: number;
+}
+
+/**
+ * The seam a future opt-in embedding index would implement. A retriever could
+ * accept one and offer `semanticQuery`, but the MVP neither ships nor requires
+ * an implementation — retrieval is fully correct git-only without it.
+ *
+ * Implementations must treat the embedding store as a derived projection of git:
+ * {@link reindex} rebuilds it from the authoritative records, and a cold/missing
+ * embedding index must degrade to the git-backed lexical path, never to wrong
+ * or stale results.
+ */
+export interface EmbeddingIndex {
+  /** (Re)build the derived vector index from the authoritative git records. */
+  reindex(records: readonly StoredRecord[]): Promise<void>;
+  /**
+   * Return the semantically nearest records to `query.text`, honouring the
+   * structured/frontmatter clauses of `query` as pre/post filters.
+   */
+  semanticSearch(
+    query: RetrievalQuery,
+    k: number,
+  ): Promise<readonly SemanticMatch[]>;
+}

package/src/context/retrieval/index.ts

@@ -1,2 +1,47 @@
-// Slice S4 (retrieval) — owner replaces this placeholder barrel.
-export {};
+// @nanobpm/urban/context/retrieval — slice S4 (retrieval over git).
+//
+// Read-side of the Urban context layer: query the git system-of-record that S3
+// writes, using the exact path/namespace layout S3 publishes. MVP is git-only —
+// NO external service:
+//
+//  1. STRUCTURED / PATH-SCOPED queries by scope/namespace, reading just one
+//     layout partition when a query pins it (cheap, cold-cache friendly).
+//  2. FRONTMATTER filtering on typed record fields (scope/mode/provenance/
+//     authority/id/subject), ANDed clauses with OR-sets per field.
+//  3. TEXT SEARCH across record bodies (case-insensitive substring).
+//
+// Git is the system of record; the hot read cache (DerivedRecordIndex) is a
+// DISPOSABLE projection, rebuildable purely from git and never authoritative —
+// retrieval is correct even with a cold/empty cache by falling back to the
+// source. A future opt-in derived embedding index is left as a documented seam
+// (see embedding.ts / EmbeddingIndex) and is NOT built here.
+
+export {
+  ContextRetriever,
+  type ContextRetrieverOptions,
+} from "./retriever.ts";
+
+export { DerivedRecordIndex } from "./cache.ts";
+
+export {
+  GitRecordSource,
+  type NamespaceSelector,
+  type RecordSource,
+  RecordSourceError,
+  type ResolvedReadHandle,
+  selectorSubtree,
+  type StoredRecord,
+} from "./source.ts";
+
+export {
+  compileQuery,
+  type CompiledQuery,
+  matchesQuery,
+  type OneOrMany,
+  type RetrievalQuery,
+} from "./query.ts";
+
+export {
+  type EmbeddingIndex,
+  type SemanticMatch,
+} from "./embedding.ts";

package/src/context/retrieval/query.test.ts

@@ -0,0 +1,72 @@
+// Slice S4 (retrieval) — unit tests for the pure query model.
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type { MemoryRecord } from "../schema/index.ts";
+import { compileQuery, matchesQuery, type RetrievalQuery } from "./query.ts";
+
+function rec(overrides: Partial<MemoryRecord>): MemoryRecord {
+  const base: MemoryRecord = {
+    schemaVersion: 1,
+    id: "rec-1",
+    scope: "epic",
+    scopeRef: "issue-303",
+    mode: "empirical",
+    provenance: "measured",
+    authority: "authoritative",
+    statement: "the measured throughput was 42 rps",
+    createdAt: "2026-01-01T00:00:00Z",
+  };
+  return { ...base, ...overrides };
+}
+
+function matches(record: MemoryRecord, query: RetrievalQuery): boolean {
+  return matchesQuery(record, compileQuery(query));
+}
+
+test("an empty query matches every record", () => {
+  assert.equal(matches(rec({}), {}), true);
+});
+
+test("frontmatter clauses are ANDed", () => {
+  const record = rec({ provenance: "measured", mode: "empirical" });
+  assert.equal(matches(record, { provenance: "measured", mode: "empirical" }), true);
+  assert.equal(matches(record, { provenance: "measured", mode: "normative" }), false);
+});
+
+test("a clause given as an array is an OR-set", () => {
+  const record = rec({ scope: "repo" });
+  assert.equal(matches(record, { scope: ["epic", "repo"] }), true);
+  assert.equal(matches(record, { scope: ["epic", "corpus"] }), false);
+  assert.equal(matches(record, { scope: "repo" }), true);
+});
+
+test("scopeRef filter distinguishes namespaces", () => {
+  assert.equal(matches(rec({ scopeRef: "issue-303" }), { scopeRef: "issue-303" }), true);
+  assert.equal(matches(rec({ scopeRef: "issue-999" }), { scopeRef: "issue-303" }), false);
+});
+
+test("a scopeRef filter never matches a record without a scopeRef", () => {
+  const unscoped = rec({ scope: "corpus", scopeRef: undefined });
+  assert.equal(matches(unscoped, { scopeRef: "issue-303" }), false);
+  assert.equal(matches(unscoped, {}), true);
+});
+
+test("text search is a case-insensitive substring over the body", () => {
+  const record = rec({ statement: "The Measured Throughput was 42 RPS", subject: "latency" });
+  assert.equal(matches(record, { text: "throughput" }), true);
+  assert.equal(matches(record, { text: "THROUGHPUT" }), true);
+  assert.equal(matches(record, { text: "latency" }), true); // subject
+  assert.equal(matches(record, { text: "rec-1" }), true); // id
+  assert.equal(matches(record, { text: "absent" }), false);
+});
+
+test("an empty text needle matches everything", () => {
+  assert.equal(matches(rec({}), { text: "" }), true);
+});
+
+test("text search composes with structured filters (AND)", () => {
+  const record = rec({ provenance: "human", mode: "normative", statement: "prefer explicit errors" });
+  assert.equal(matches(record, { provenance: "human", text: "explicit" }), true);
+  assert.equal(matches(record, { provenance: "measured", text: "explicit" }), false);
+});

package/src/context/retrieval/query.ts

@@ -0,0 +1,118 @@
+// Slice S4 (retrieval) — the query model: frontmatter filtering + text search.
+//
+// A retrieval query is a conjunction of independent predicates: path-scoped
+// namespace narrowing (scope/scopeRef), frontmatter filtering on the typed
+// record fields (mode/provenance/authority/…), and a free-text search across
+// the record body. Every clause is optional; an empty query matches everything.
+// The matching here is pure and cache-agnostic — it runs identically over
+// records read straight from git (cold cache) or served from the hot index.
+
+import type {
+  MemoryAuthority,
+  MemoryMode,
+  MemoryProvenance,
+  MemoryRecord,
+  MemoryScope,
+} from "../schema/index.ts";
+
+/** A field value that may be given as a single value or an OR-set of values. */
+export type OneOrMany<T> = T | readonly T[];
+
+/**
+ * A retrieval query. All clauses are ANDed together; a clause given as an array
+ * is an OR over its members. Absent clauses impose no constraint.
+ */
+export interface RetrievalQuery {
+  /** Structured / path-scoped: restrict to one or more scope ladder levels. */
+  readonly scope?: OneOrMany<MemoryScope>;
+  /** Structured / path-scoped: restrict to one or more `scopeRef` namespaces. */
+  readonly scopeRef?: OneOrMany<string>;
+  /** Frontmatter filter: normative vs empirical. */
+  readonly mode?: OneOrMany<MemoryMode>;
+  /** Frontmatter filter: where the record came from. */
+  readonly provenance?: OneOrMany<MemoryProvenance>;
+  /** Frontmatter filter: hypothesis vs authoritative. */
+  readonly authority?: OneOrMany<MemoryAuthority>;
+  /** Frontmatter filter: exact record id(s). */
+  readonly id?: OneOrMany<string>;
+  /** Frontmatter filter: exact subject(s). */
+  readonly subject?: OneOrMany<string>;
+  /**
+   * Free-text search across the record body — case-insensitive substring match
+   * over `statement`, `subject` (when present), and `id`. This is the "text
+   * search across record bodies" clause; it composes with the structured filters.
+   */
+  readonly text?: string;
+  /** Cap the number of results returned (applied after ordering). */
+  readonly limit?: number;
+}
+
+function toSet<T>(value: OneOrMany<T> | undefined): ReadonlySet<T> | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  return new Set(Array.isArray(value) ? value : [value]);
+}
+
+function matchesOneOf<T>(
+  allowed: ReadonlySet<T> | undefined,
+  actual: T | undefined,
+): boolean {
+  if (allowed === undefined) {
+    return true;
+  }
+  return actual !== undefined && allowed.has(actual);
+}
+
+/**
+ * A query compiled to sets for O(1) membership tests. Building it once and
+ * reusing it across a candidate list avoids re-normalising the query per record.
+ */
+export interface CompiledQuery {
+  readonly scope?: ReadonlySet<MemoryScope>;
+  readonly scopeRef?: ReadonlySet<string>;
+  readonly mode?: ReadonlySet<MemoryMode>;
+  readonly provenance?: ReadonlySet<MemoryProvenance>;
+  readonly authority?: ReadonlySet<MemoryAuthority>;
+  readonly id?: ReadonlySet<string>;
+  readonly subject?: ReadonlySet<string>;
+  readonly text?: string;
+  readonly limit?: number;
+}
+
+/** Compile a raw query into membership sets + a normalised (lowercased) needle. */
+export function compileQuery(query: RetrievalQuery): CompiledQuery {
+  return {
+    scope: toSet(query.scope),
+    scopeRef: toSet(query.scopeRef),
+    mode: toSet(query.mode),
+    provenance: toSet(query.provenance),
+    authority: toSet(query.authority),
+    id: toSet(query.id),
+    subject: toSet(query.subject),
+    text: query.text === undefined ? undefined : query.text.toLowerCase(),
+    limit: query.limit,
+  };
+}
+
+/** `true` iff `record` satisfies every clause of the compiled query. */
+export function matchesQuery(record: MemoryRecord, query: CompiledQuery): boolean {
+  if (!matchesOneOf(query.scope, record.scope)) return false;
+  if (!matchesOneOf(query.scopeRef, record.scopeRef)) return false;
+  if (!matchesOneOf(query.mode, record.mode)) return false;
+  if (!matchesOneOf(query.provenance, record.provenance)) return false;
+  if (!matchesOneOf(query.authority, record.authority)) return false;
+  if (!matchesOneOf(query.id, record.id)) return false;
+  if (!matchesOneOf(query.subject, record.subject)) return false;
+  if (query.text !== undefined && !matchesText(record, query.text)) return false;
+  return true;
+}
+
+/** Case-insensitive substring search across the record's textual body. */
+function matchesText(record: MemoryRecord, needle: string): boolean {
+  if (needle === "") {
+    return true;
+  }
+  const haystacks = [record.statement, record.subject ?? "", record.id];
+  return haystacks.some((field) => field.toLowerCase().includes(needle));
+}