@nanobpm/urban 0.69.1 → 0.71.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.1",
+	"version": "0.71.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",

package/src/context/README.md

@@ -58,3 +58,47 @@ barrel.
 - `npm run test:conformance --workspace @nanobpm/urban` runs the conformance
   corpus.
 - `npm run check:pii --workspace @nanobpm/urban` runs the PII gate.
+
+## PII: no-PII by construction, and the immutability-vs-erasure boundary
+
+The MVP substrate is **no-PII by construction**. Nothing here stores personal
+data, and two independent nets keep it that way:
+
+1. **In-process, at write time (S6-core + S3).** `@nanobpm/urban/context/pii`
+   ships a pure classifier (`classifyPii`) and a mandatory, default-DENY
+   pre-commit guard (`preCommitPiiGuard`). S3's `ContextWriter` registers that
+   guard as a **non-optional** pre-commit step on **every** write path
+   (`PreCommitGuardRegistry`, seeded non-removably), so a record carrying PII is
+   rejected **before any commit** — a caller cannot opt out.
+
+2. **Build-time, in CI (this slice, s6-pii-ci).** `npm run check:pii` walks the
+   S3 record layout (`records/<scope>/<scopeRef-bucket>/<id>.json`, where
+   `<scopeRef-bucket>` is the sanitised `scopeRef` or the shared `_` bucket when a
+   record carries no `scopeRef` — see `recordRelativePath`) and re-classifies
+   every record with the **same** `classifyPii`, failing the build on any violation.
+   The `.github/workflows/urban-context-pii.yml` workflow runs it (plus
+   build/typecheck/test) as a second line of defence in case content reaches a
+   git-backed context by some path other than the writer.
+
+### Why the guard, not erasure
+
+The substrate is an **append-only git history**. "Deleting" a record is just
+another commit that removes the file from the *tip*; every prior value remains
+in the reachable history (and in every clone, fork, and reflog). On this
+substrate there is **no true erasure** — you cannot unpublish a fact that was
+ever committed short of a history rewrite that every consumer must also adopt.
+Because real erasure is not achievable append-only, the only sound MVP policy is
+to **never admit PII in the first place** — hence the by-construction guard + CI
+net above rather than an after-the-fact delete.
+
+### The seam left for a future PII/mutable backend
+
+Real erasure (GDPR-style "right to be forgotten", tombstoning, crypto-shredding)
+requires a **mutable** substrate that can genuinely destroy a value, not merely
+append over it. The write path is already abstracted over the substrate
+(`WriteSubstrate` / `GitWriteSubstrate` in `@nanobpm/urban/context/git`) and the
+binding layer does not assume "public git only", so a future opt-in
+PII/mutable backend can slot in behind that seam and offer erasure semantics
+**without** touching the record schema, the layout, or this guard. That backend
+is intentionally **not built** in the MVP — only its seam is documented here, and
+the deferred implementation is tracked in nano-ide#393.

package/src/context/pii/check-pii.test.ts

@@ -0,0 +1,196 @@
+// Slice s6-pii-ci — tests for the build-time PII gate (`scripts/check-pii.ts`).
+//
+// These seed records into the SAME S3 path/namespace layout the writer uses
+// (`recordRelativePath`), then run the real check-pii.ts script against a local
+// temp substrate and assert its exit code: non-zero on a seeded PII violation,
+// zero on clean content. Nothing touches the network.
+
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { after, test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { recordRelativePath } from "../git/index.ts";
+import type { MemoryRecord } from "../schema/index.ts";
+
+const execFileAsync = promisify(execFile);
+const HERE = dirname(fileURLToPath(import.meta.url));
+// packages/urban/src/context/pii → packages/urban/scripts/check-pii.ts
+const CHECK_PII = join(HERE, "..", "..", "..", "scripts", "check-pii.ts");
+const TEMP_ROOTS: string[] = [];
+
+after(async () => {
+  await Promise.all(TEMP_ROOTS.map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+function record(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 };
+}
+
+/** Write a record into a substrate root at its canonical S3 layout path. */
+async function seed(root: string, rec: MemoryRecord): Promise<void> {
+  const rel = recordRelativePath(rec);
+  const abs = join(root, rel);
+  await mkdir(dirname(abs), { recursive: true });
+  await writeFile(abs, `${JSON.stringify(rec, null, 2)}\n`, "utf8");
+}
+
+/** Write raw file content into a substrate root at a record's canonical path. */
+async function seedRaw(root: string, rec: MemoryRecord, content: string): Promise<void> {
+  const rel = recordRelativePath(rec);
+  const abs = join(root, rel);
+  await mkdir(dirname(abs), { recursive: true });
+  await writeFile(abs, content, "utf8");
+}
+
+async function makeRoot(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "s6ci-substrate-"));
+  TEMP_ROOTS.push(dir);
+  return dir;
+}
+
+/** Run check-pii.ts against a root; resolve with its exit code + stderr. */
+async function runCheck(root: string): Promise<{ code: number; stderr: string; stdout: string }> {
+  try {
+    const { stdout, stderr } = await execFileAsync(
+      process.execPath,
+      ["--experimental-strip-types", CHECK_PII, root],
+      { cwd: root },
+    );
+    return { code: 0, stdout, stderr };
+  } catch (error) {
+    return {
+      code: numberProp(error, "code") ?? 1,
+      stdout: stringProp(error, "stdout"),
+      stderr: stringProp(error, "stderr"),
+    };
+  }
+}
+
+function numberProp(error: unknown, key: string): number | undefined {
+  const value =
+    typeof error === "object" && error !== null ? Reflect.get(error, key) : undefined;
+  return typeof value === "number" ? value : undefined;
+}
+
+function stringProp(error: unknown, key: string): string {
+  const value =
+    typeof error === "object" && error !== null ? Reflect.get(error, key) : undefined;
+  return typeof value === "string" ? value : "";
+}
+
+test("check:pii passes (exit 0) on clean records in the S3 layout", async () => {
+  const root = await makeRoot();
+  await seed(root, record({ id: "clean-a" }));
+  await seed(
+    root,
+    record({ id: "clean-b", scope: "repo", scopeRef: undefined, statement: "latency held at 42ms" }),
+  );
+
+  const { code, stdout } = await runCheck(root);
+  assert.equal(code, 0, `expected clean content to pass; stdout=${stdout}`);
+  assert.match(stdout, /no PII detected/);
+});
+
+test("check:pii fails (non-zero) on a seeded PII violation in the S3 layout", async () => {
+  const root = await makeRoot();
+  await seed(root, record({ id: "clean-a" }));
+  // A record whose statement carries an email address — a PII violation.
+  await seed(
+    root,
+    record({ id: "leaky", statement: "reported by alice.example@contoso.com during the run" }),
+  );
+
+  const { code, stderr } = await runCheck(root);
+  assert.equal(code, 1, "expected a seeded PII violation to fail the build");
+  assert.match(stderr, /PII detected/);
+  assert.match(stderr, /email/);
+  // The gate must NOT re-leak the raw PII it caught (length-only redaction).
+  assert.doesNotMatch(stderr, /alice\.example@contoso\.com/);
+});
+
+test("check:pii catches PII in a JSON array record (arrays are not plain objects)", async () => {
+  const root = await makeRoot();
+  // A record file whose top-level JSON value is an array carrying an email
+  // address. Arrays must NOT be narrowed as plain objects — they fall through
+  // to the raw-text scan, so the leak is still caught.
+  await seedRaw(
+    root,
+    record({ id: "arr-leak" }),
+    `${JSON.stringify(["contact alice.example@contoso.com for details"], null, 2)}\n`,
+  );
+
+  const { code, stderr } = await runCheck(root);
+  assert.equal(code, 1, "expected a PII violation inside a JSON array record to fail the build");
+  assert.match(stderr, /PII detected/);
+  assert.match(stderr, /email/);
+  assert.doesNotMatch(stderr, /alice\.example@contoso\.com/);
+});
+
+test("check:pii is a no-op (exit 0) on a root with no records/ layout", async () => {
+  const root = await makeRoot();
+  const { code, stdout } = await runCheck(root);
+  assert.equal(code, 0);
+  assert.match(stdout, /0 record\(s\) scanned/);
+});
+
+test("check:pii does not follow a symlink record into a target outside the root", async () => {
+  const root = await makeRoot();
+  // A secret file OUTSIDE the substrate root (e.g. a CI secret the scanner
+  // should never touch), carrying an email address.
+  const secret = join(await makeRoot(), "ci-secret.txt");
+  await writeFile(secret, "token owner: alice.example@contoso.com\n", "utf8");
+  // A symlink placed at a canonical record path that points at that secret. The
+  // scanner must reject non-regular files (symlinks) up front — otherwise a
+  // crafted `records/**.json` symlink would make it read and classify content
+  // outside the intended substrate root.
+  const rel = recordRelativePath(record({ id: "evil-link" }));
+  const linkPath = join(root, rel);
+  await mkdir(dirname(linkPath), { recursive: true });
+  await symlink(secret, linkPath);
+
+  const { code, stdout } = await runCheck(root);
+  assert.equal(code, 0, `symlinked record must be skipped, not scanned; stdout=${stdout}`);
+  assert.match(stdout, /0 record\(s\) scanned/);
+});
+
+test("check:pii does not follow a symlinked DIRECTORY into a target outside the root", async () => {
+  const root = await makeRoot();
+  // A directory OUTSIDE the substrate root holding a record-shaped file that
+  // carries an email address — content the scanner must never reach.
+  const outsideDir = join(await makeRoot(), "outside-bucket");
+  await mkdir(outsideDir, { recursive: true });
+  await writeFile(
+    join(outsideDir, "rec-leak.json"),
+    `${JSON.stringify(record({ id: "rec-leak", statement: "owned by alice.example@contoso.com" }), null, 2)}\n`,
+    "utf8",
+  );
+  // Symlink an INTERMEDIATE bucket directory in the layout to that outside dir.
+  // `records/epic/issue-303` → outsideDir makes `records/epic/issue-303/rec-leak.json`
+  // look like a canonical record path. `readdir(recursive:true)` would follow
+  // the symlinked directory and scan (and re-leak) the outside file; the walk
+  // must refuse to descend into any symlinked directory.
+  const bucketLink = join(root, "records", "epic", "issue-303");
+  await mkdir(dirname(bucketLink), { recursive: true });
+  await symlink(outsideDir, bucketLink);
+
+  const { code, stdout, stderr } = await runCheck(root);
+  assert.equal(code, 0, `symlinked bucket dir must not be traversed; stderr=${stderr}`);
+  assert.match(stdout, /0 record\(s\) scanned/);
+  // And it must never re-leak the outside PII it refused to scan.
+  assert.doesNotMatch(stderr, /alice\.example@contoso\.com/);
+});

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";