@nanobpm/urban 0.69.1 → 0.71.0

package/dist/context/retrieval/cache.d.ts

@@ -0,0 +1,35 @@
+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 declare class DerivedRecordIndex {
+    #private;
+    constructor(source: RecordSource);
+    /** `true` once a full snapshot is loaded; `false` when cold/invalidated. */
+    get isWarm(): boolean;
+    /** The read source this index is derived from (git, by default). */
+    get source(): RecordSource;
+    /**
+     * 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.
+     */
+    rebuild(): Promise<readonly StoredRecord[]>;
+    /** Drop the projection so the next read re-reads from git. */
+    invalidate(): void;
+    /**
+     * 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.
+     */
+    all(): Promise<readonly StoredRecord[]>;
+    /**
+     * 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.
+     */
+    namespace(selector: NamespaceSelector): Promise<readonly StoredRecord[]>;
+}

package/dist/context/retrieval/cache.js

@@ -0,0 +1,75 @@
+// 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.
+/**
+ * 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 {
+    #source;
+    // `undefined` == cold (never loaded / invalidated). An empty array is a valid
+    // WARM state (a store that genuinely has no records), distinct from cold.
+    #snapshot;
+    constructor(source) {
+        this.#source = source;
+    }
+    /** `true` once a full snapshot is loaded; `false` when cold/invalidated. */
+    get isWarm() {
+        return this.#snapshot !== undefined;
+    }
+    /** The read source this index is derived from (git, by default). */
+    get source() {
+        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() {
+        const snapshot = await this.#source.list();
+        this.#snapshot = snapshot;
+        return snapshot;
+    }
+    /** Drop the projection so the next read re-reads from git. */
+    invalidate() {
+        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() {
+        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) {
+        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, selector) {
+    if (stored.record.scope !== selector.scope) {
+        return false;
+    }
+    return (selector.scopeRef === undefined || stored.record.scopeRef === selector.scopeRef);
+}

package/dist/context/retrieval/embedding.d.ts

@@ -0,0 +1,27 @@
+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/dist/context/retrieval/embedding.js

@@ -0,0 +1,13 @@
+// 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.
+export {};

package/dist/context/retrieval/index.d.ts

@@ -1 +1,5 @@
-export {};
+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/dist/context/retrieval/index.js

@@ -1 +1,21 @@
-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, } from "./retriever.js";
+export { DerivedRecordIndex } from "./cache.js";
+export { GitRecordSource, RecordSourceError, selectorSubtree, } from "./source.js";
+export { compileQuery, matchesQuery, } from "./query.js";

package/dist/context/retrieval/query.d.ts

@@ -0,0 +1,50 @@
+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;
+}
+/**
+ * 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 declare function compileQuery(query: RetrievalQuery): CompiledQuery;
+/** `true` iff `record` satisfies every clause of the compiled query. */
+export declare function matchesQuery(record: MemoryRecord, query: CompiledQuery): boolean;

package/dist/context/retrieval/query.js

@@ -0,0 +1,62 @@
+// 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.
+function toSet(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return new Set(Array.isArray(value) ? value : [value]);
+}
+function matchesOneOf(allowed, actual) {
+    if (allowed === undefined) {
+        return true;
+    }
+    return actual !== undefined && allowed.has(actual);
+}
+/** Compile a raw query into membership sets + a normalised (lowercased) needle. */
+export function compileQuery(query) {
+    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, query) {
+    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, needle) {
+    if (needle === "") {
+        return true;
+    }
+    const haystacks = [record.statement, record.subject ?? "", record.id];
+    return haystacks.some((field) => field.toLowerCase().includes(needle));
+}

package/dist/context/retrieval/retriever.d.ts

@@ -0,0 +1,63 @@
+import { DerivedRecordIndex } from "./cache.ts";
+import type { EmbeddingIndex } from "./embedding.ts";
+import { type RetrievalQuery } from "./query.ts";
+import { type NamespaceSelector, type RecordSource, type ResolvedReadHandle, type StoredRecord } from "./source.ts";
+/** Options for {@link ContextRetriever}. All optional; the defaults are safe. */
+export interface ContextRetrieverOptions {
+    /**
+     * Override the read source (seam for a future mutable/PII backend). Defaults
+     * to a {@link GitRecordSource} over the resolved handle's working copy.
+     */
+    readonly source?: RecordSource;
+    /**
+     * A future opt-in derived embedding index. Purely a forward-compat seam — the
+     * MVP does not build or require one, and no method here depends on it.
+     */
+    readonly embeddingIndex?: EmbeddingIndex;
+}
+/**
+ * Retrieval over the git-backed context store. Bind one to a resolved substrate
+ * handle (the local checkout S1 produces) and query it; the derived hot cache is
+ * built lazily and can be invalidated/rebuilt at will.
+ */
+export declare class ContextRetriever {
+    #private;
+    constructor(handle: ResolvedReadHandle | string, options?: ContextRetrieverOptions);
+    /** The derived hot cache (for explicit warm/invalidate/rebuild control). */
+    get cache(): DerivedRecordIndex;
+    /** The read source this retriever reads git through. */
+    get source(): RecordSource;
+    /**
+     * A future opt-in embedding index, if one was supplied. `undefined` in the
+     * MVP — retrieval is fully functional without it.
+     */
+    get embeddingIndex(): EmbeddingIndex | undefined;
+    /**
+     * Run a retrieval query. Structured/path-scoped clauses (`scope` + a single
+     * `scopeRef`) narrow the read to one layout partition when the cache is cold,
+     * so a targeted query is cheap and never forces a full index build; otherwise
+     * the frontmatter + text clauses filter the candidate set in memory. Results
+     * are ordered by layout path for determinism and capped by `limit`.
+     */
+    query(query?: RetrievalQuery): Promise<readonly StoredRecord[]>;
+    /**
+     * Path-scoped structured query: every record in one namespace partition
+     * (`scope` + optional `scopeRef`), read cheaply from just that subtree when
+     * the cache is cold. Equivalent to `query({ scope, scopeRef })` but expresses
+     * the S3-partition intent directly.
+     */
+    byNamespace(scope: NamespaceSelector["scope"], scopeRef?: string): Promise<readonly StoredRecord[]>;
+    /**
+     * Free-text search across record bodies, optionally combined with structured
+     * frontmatter filters. Convenience over {@link query} for the common case.
+     */
+    search(text: string, filters?: Omit<RetrievalQuery, "text">): Promise<readonly StoredRecord[]>;
+    /** Every record in the store, warming the cache. */
+    all(): Promise<readonly StoredRecord[]>;
+    /** Read a single record by its S3 layout path (bypasses the cache). */
+    get(relPath: string): Promise<StoredRecord | undefined>;
+    /** Drop the derived cache so the next query re-reads from git. */
+    invalidate(): void;
+    /** Eagerly rebuild the derived cache from git. */
+    rebuild(): Promise<readonly StoredRecord[]>;
+}

package/dist/context/retrieval/retriever.js

@@ -0,0 +1,136 @@
+// Slice S4 (retrieval) — the public retriever over the git system-of-record.
+//
+// `ContextRetriever` composes the three pieces of this slice into one API:
+//   - a RecordSource (git read seam, default GitRecordSource over a resolved
+//     substrate working copy),
+//   - a DerivedRecordIndex (disposable hot cache, rebuildable from git),
+//   - the pure query model (path-scoped + frontmatter + text search).
+//
+// Correctness does not depend on the cache: every query works from a cold/empty
+// index by reading through to git, and a query narrowed to one namespace reads
+// only that partition (a cheap, path-scoped read) without warming the whole
+// index. Callers keep the cache honest by calling `invalidate()` after a write
+// (git remains the source of truth); nothing here silently serves stale data
+// beyond what the caller has chosen to keep warm.
+import { DerivedRecordIndex } from "./cache.js";
+import { compileQuery, matchesQuery, } from "./query.js";
+import { GitRecordSource, } from "./source.js";
+/**
+ * Retrieval over the git-backed context store. Bind one to a resolved substrate
+ * handle (the local checkout S1 produces) and query it; the derived hot cache is
+ * built lazily and can be invalidated/rebuilt at will.
+ */
+export class ContextRetriever {
+    #source;
+    #index;
+    #embeddingIndex;
+    constructor(handle, options = {}) {
+        this.#source = options.source ?? new GitRecordSource(handle);
+        this.#index = new DerivedRecordIndex(this.#source);
+        this.#embeddingIndex = options.embeddingIndex;
+    }
+    /** The derived hot cache (for explicit warm/invalidate/rebuild control). */
+    get cache() {
+        return this.#index;
+    }
+    /** The read source this retriever reads git through. */
+    get source() {
+        return this.#source;
+    }
+    /**
+     * A future opt-in embedding index, if one was supplied. `undefined` in the
+     * MVP — retrieval is fully functional without it.
+     */
+    get embeddingIndex() {
+        return this.#embeddingIndex;
+    }
+    /**
+     * Run a retrieval query. Structured/path-scoped clauses (`scope` + a single
+     * `scopeRef`) narrow the read to one layout partition when the cache is cold,
+     * so a targeted query is cheap and never forces a full index build; otherwise
+     * the frontmatter + text clauses filter the candidate set in memory. Results
+     * are ordered by layout path for determinism and capped by `limit`.
+     */
+    async query(query = {}) {
+        const compiled = compileQuery(query);
+        const candidates = await this.#candidates(compiled);
+        const matched = candidates.filter((stored) => matchesQuery(stored.record, compiled));
+        return applyLimit(matched, compiled);
+    }
+    /**
+     * Path-scoped structured query: every record in one namespace partition
+     * (`scope` + optional `scopeRef`), read cheaply from just that subtree when
+     * the cache is cold. Equivalent to `query({ scope, scopeRef })` but expresses
+     * the S3-partition intent directly.
+     */
+    async byNamespace(scope, scopeRef) {
+        return this.#index.namespace({ scope, scopeRef });
+    }
+    /**
+     * Free-text search across record bodies, optionally combined with structured
+     * frontmatter filters. Convenience over {@link query} for the common case.
+     */
+    async search(text, filters = {}) {
+        return this.query({ ...filters, text });
+    }
+    /** Every record in the store, warming the cache. */
+    async all() {
+        return this.#index.all();
+    }
+    /** Read a single record by its S3 layout path (bypasses the cache). */
+    async get(relPath) {
+        return this.#source.read(relPath);
+    }
+    /** Drop the derived cache so the next query re-reads from git. */
+    invalidate() {
+        this.#index.invalidate();
+    }
+    /** Eagerly rebuild the derived cache from git. */
+    async rebuild() {
+        return this.#index.rebuild();
+    }
+    /**
+     * The candidate set to filter: when a query pins exactly one scope we read
+     * only that scope's subtree (cheap path-scoped read, cold-cache friendly) —
+     * pinning a single scopeRef narrows it further to that one namespace
+     * partition, otherwise the whole scope subtree (spanning its refs) is read;
+     * when no single scope is pinned we read the whole (cached) store.
+     */
+    async #candidates(query) {
+        const selector = singleNamespace(query);
+        if (selector !== undefined) {
+            return this.#index.namespace(selector);
+        }
+        return this.#index.all();
+    }
+}
+/**
+ * If a compiled query pins exactly ONE scope (and at most one scopeRef), return
+ * the namespace partition it lives in so retrieval can read just that subtree.
+ * Returns `undefined` when the query spans multiple scopes/refs (or none), in
+ * which case the whole store is the candidate set.
+ */
+function singleNamespace(query) {
+    const scope = onlyMember(query.scope);
+    if (scope === undefined) {
+        return undefined;
+    }
+    const scopeRef = onlyMember(query.scopeRef);
+    return { scope, ...(scopeRef === undefined ? {} : { scopeRef }) };
+}
+/** The sole member of a set of exactly one element, else `undefined`. */
+function onlyMember(set) {
+    if (set === undefined || set.size !== 1) {
+        return undefined;
+    }
+    for (const value of set) {
+        return value;
+    }
+    return undefined;
+}
+function applyLimit(records, query) {
+    if (query.limit === undefined || query.limit < 0) {
+        return records;
+    }
+    return records.slice(0, query.limit);
+}

package/dist/context/retrieval/source.d.ts

@@ -0,0 +1,71 @@
+import { type MemoryRecord, type MemoryScope } from "../schema/index.ts";
+/** A record as it is stored in the substrate: its layout path + the record. */
+export interface StoredRecord {
+    /** Substrate-root-relative POSIX path the record lives at (S3 layout). */
+    readonly path: string;
+    /** The validated memory record parsed from that file. */
+    readonly record: MemoryRecord;
+}
+/**
+ * A path-scoped selector for a namespace partition in the S3 layout. Reading a
+ * single `(scope, scopeRef)` — or a whole `scope` — is a cheap structured query
+ * because the layout partitions records into one directory per namespace, so the
+ * source can walk just that subtree instead of the whole store.
+ */
+export interface NamespaceSelector {
+    readonly scope: MemoryScope;
+    /** When present, narrows to one namespace bucket; absent lists the scope. */
+    readonly scopeRef?: string;
+}
+/**
+ * The read seam retrieval is built on. A future mutable/PII backend can
+ * implement this differently (e.g. against a database) without the cache, the
+ * query layer, or callers changing.
+ */
+export interface RecordSource {
+    /**
+     * List every stored record, optionally narrowed to one namespace partition
+     * (a cheap, path-scoped read that walks only that subtree of the S3 layout).
+     * Invalid / unparseable files under the layout root are skipped, not fatal —
+     * a single corrupt file must never make the whole store unreadable.
+     */
+    list(selector?: NamespaceSelector): Promise<readonly StoredRecord[]>;
+    /**
+     * Read a single record by its substrate-relative layout path, or `undefined`
+     * when it is absent or not a valid record file.
+     */
+    read(relPath: string): Promise<StoredRecord | undefined>;
+}
+/** The minimal resolved-handle shape the read source consumes (from S1). */
+export interface ResolvedReadHandle {
+    /** Absolute path to the local substrate working copy (checked out at `ref`). */
+    readonly localPath: string;
+    /** The git ref the working copy is pinned to (informational for reads). */
+    readonly ref?: string;
+}
+/** Thrown when the underlying substrate cannot be read at all. */
+export declare class RecordSourceError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare class GitRecordSource implements RecordSource {
+    #private;
+    constructor(handle: ResolvedReadHandle | string);
+    /** Absolute path of the substrate working copy this source reads from. */
+    get root(): string;
+    list(selector?: NamespaceSelector): Promise<readonly StoredRecord[]>;
+    read(relPath: string): Promise<StoredRecord | undefined>;
+}
+/**
+ * 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 declare function selectorSubtree(selector?: NamespaceSelector): string;