@north-light/crouter 0.3.154

package/dist/core/substrate/schema.d.ts

@@ -0,0 +1,125 @@
+import type { MemoryDoc, MemoryScope } from '../memory-resolver.js';
+export declare const KINDS: readonly ["knowledge", "preference"];
+export type DocKind = (typeof KINDS)[number];
+/** Is `v` one of the two valid document kinds? */
+export declare function isDocKind(v: unknown): v is DocKind;
+export declare const RUNGS: readonly ["none", "name", "preview", "content"];
+export type Rung = (typeof RUNGS)[number];
+/** Ordinal of a rung on the ladder (none=0 … content=3). */
+export declare function rungRank(r: Rung): number;
+/** Does rung `r` disclose at least as much as `min`? — e.g.
+ *  `rungAtLeast(doc.systemPromptVisibility, 'name')` ⇒ "shows at boot at all". */
+export declare function rungAtLeast(r: Rung, min: Rung): boolean;
+export declare const FALLBACK_RUNG: Rung;
+/** Strip an optional `NN-` ordering prefix from ONE path segment (file or
+ *  directory display name). `00-runtime-base` -> `runtime-base`; `spine` (no
+ *  prefix) is unchanged. */
+export declare function normalizeNameSegment(segment: string): string;
+/** Normalize a full slash-separated path-derived doc name by stripping the
+ *  optional numeric prefix from EVERY segment: `01-spine/00-has-manager` ->
+ *  `spine/has-manager`. This is the identity a doc displays, dedups, and
+ *  resolves under — distinct from its physical path, which keeps the prefix. */
+export declare function normalizeDocName(name: string): string;
+/** Resolve a doc's identity from its raw frontmatter record: an explicit
+ *  `name` field wins (trimmed + normalized), else `fallbackName` (the
+ *  normalized path-derived name). */
+export declare function resolveDocName(fm: Record<string, unknown> | null | undefined, fallbackName: string): string;
+/** A gate predicate tree, evaluated by predicate.ts (`evalCondition`) against
+ *  the node-config subject. Typed loosely on purpose — the matcher engine owns
+ *  validation; structurally it is a field→matcher map with optional
+ *  `all`/`any`/`not` combinators (design §4). */
+export type GatePredicate = Record<string, unknown>;
+/** The frontmatter-derived schema of a substrate document, with kind-aware
+ *  defaults applied. Required fields (`kind`/`when-and-why-to-read`) and
+ *  optionals all resolved to concrete typed values. */
+export interface SubstrateSchema {
+    /** Which of the two semantic kinds (knowledge | preference). */
+    kind: DocKind;
+    /** The read-routing line — a single sentence answering WHEN to read this doc
+     *  and WHY it is worth the read: "When <circumstance>, this <kind> should be
+     *  read because <broader downstream payoff>." (design §4). This is
+     *  read-routing: WHY is the reader's payoff for the task in front of them,
+     *  NEVER a document summary, its rule, or that rule reworded as an outcome (a
+     *  benefit-shaped restatement still fails). It IS the preview verbatim.
+     *  Frontmatter key `when-and-why-to-read`. */
+    whenAndWhyToRead: string;
+    /** Human-facing abbreviation for `crtr memory list`. NEVER loaded into an
+     *  agent's context (design §3). Empty string when absent. */
+    shortForm: string;
+    /** How much surfaces at boot (system prompt / autoloaded context). */
+    systemPromptVisibility: Rung;
+    /** How much surfaces on-read (when a related file is read). */
+    fileReadVisibility: Rung;
+    /** Optional eligibility predicate over the node's own config. Absent ⇒ always
+     *  eligible. An empty `{}` is carried as-is and is inert (never matches) — see
+     *  `gatePasses`. */
+    gate?: GatePredicate;
+    /** Optional glob list narrowing the on-read trigger to matching read files.
+     *  Absent ⇒ positional trigger only. A single glob is normalized to a 1-list. */
+    appliesTo?: string[];
+    /** Optional condition over the READ FILE's own frontmatter — the on-read
+     *  frontmatter trigger (Stream A native rules). Same coercion + predicate
+     *  vocabulary as `gate` (non-null non-array object carried; empty `{}` inert),
+     *  but evaluated by `evalCondition` against the read file's parsed YAML rather
+     *  than the node subject. Absent ⇒ no frontmatter trigger. Frontmatter key
+     *  `read-when`. */
+    readWhen?: GatePredicate;
+    /** Opt-in: this doc is invocable as a pi slash command (`/<name>`, `/` in a
+     *  nested name rendered as `:`). Default `false` — most docs are consulted,
+     *  not invoked. Frontmatter key `slash`. */
+    slash: boolean;
+    /** The gap this doc exists to close — the observed agent failure that
+     *  prompted it (CTO ruling 2026-07-03, `taste/document-substrate` §"Rationale
+     *  is a frontmatter field, never delivered"). MAINTAINER-FACING ONLY: excluded
+     *  from every delivered surface by construction — it is frontmatter, never
+     *  body, so it never reaches a boot render, on-read injection, or `memory
+     *  read` content output; only the raw file at `path` (or `memory read
+     *  --frontmatter`) shows it. It is NOT read-routing (`whenAndWhyToRead` owns
+     *  that) and NOT a content summary (`shortForm` owns that) — it answers
+     *  "what observed failure made this doc exist," never "why obey it." Absent
+     *  when the doc carries none. Frontmatter key `rationale`. */
+    rationale?: string;
+}
+/** A fully-resolved substrate document: the parsed schema PLUS the resolver's
+ *  identity (explicit frontmatter `name` when present, otherwise the normalized
+ *  path-derived fallback) and body. This single object flows through the whole
+ *  pipeline (gate eval → boot/on-read render), so a renderer never re-parses. */
+export interface SubstrateDoc extends SubstrateSchema {
+    /** Resolver-supplied identity, e.g. `taste/document-substrate` or an explicit
+     *  frontmatter name when one is present. */
+    name: string;
+    /** The scope this doc resolved from. */
+    scope: MemoryScope;
+    /** Absolute path to the source .md. */
+    path: string;
+    /** Document body, frontmatter stripped. */
+    body: string;
+}
+/** Parse a raw frontmatter record (from `parseFrontmatterGeneric`, via the
+ *  resolver) into a typed schema with defaults applied. Returns `null` when the
+ *  record is absent or carries no valid `kind` — i.e. it is not a substrate
+ *  document and cannot be classified. Tolerant of every other imperfection (a
+ *  missing `when-and-why-to-read` defaults to '', a missing/bad rung falls back
+ *  to the neutral floor `none`), so a renderer mapping over many docs never
+ *  throws. Authoring-time enforcement of these fields lives in `crtr memory
+ *  write` (on create) and `crtr memory lint`. */
+export declare function parseSubstrateFrontmatter(fm: Record<string, unknown> | null): SubstrateSchema | null;
+/** Parse a resolved MemoryDoc into a fully-typed SubstrateDoc (schema + the
+ *  resolver's name/scope/path/body). Returns `null` for a non-substrate doc
+ *  (no valid `kind`), so callers can `docs.map(parseSubstrateDoc).filter(...)`. */
+export declare function parseSubstrateDoc(doc: MemoryDoc): SubstrateDoc | null;
+/** The kind a doc resolves to for `--kind` filtering/matching: the substrate
+ *  kind when the frontmatter parses as a valid substrate doc, else the raw
+ *  frontmatter `kind` string when present (even if not one of the two valid
+ *  kinds — an authoring error, not grounds to silently reclassify it), else
+ *  the legacy default `knowledge` for a frontmatter-less/kindless doc. The
+ *  single coercion `memory read`'s resolution and result display share, so a
+ *  `--kind` filter and the displayed `kind` field never disagree. */
+export declare function effectiveDocKind(doc: MemoryDoc): string;
+/** The `preview`-rung routing line (design §4): the `when-and-why-to-read`
+ *  field rendered essentially verbatim — it is already authored as the complete
+ *  routing sentence ("When …, this <kind> should be read …"), so there is no
+ *  template to compose. Both boot and on-read render this identical line, so it
+ *  lives once here to prevent drift. Light cleanup normalizes the trailing
+ *  period. */
+export declare function previewLine(doc: Pick<SubstrateSchema, 'whenAndWhyToRead'>): string;

package/dist/core/substrate/schema.js

@@ -0,0 +1,191 @@
+// schema.ts — the typed shape of a substrate document's frontmatter, the
+// visibility ladder, and the parse/validate function that turns a resolved
+// MemoryDoc into a fully-typed SubstrateDoc. This is the keystone every
+// downstream track (CLI verbs, boot render, on-read render, migrator) builds
+// against — pure and side-effect free. See design-substrate.md §4 (schema).
+//
+// There is NO kind-based default for visibility: the right rung is a
+// case-by-case authoring call, so both rungs are required at authoring time
+// (enforced by `crtr memory write` on create and by `crtr memory lint`). The
+// runtime parser is tolerant by contract (it maps over many docs and must
+// never throw), so a doc missing/with an invalid rung falls back to the neutral
+// floor `none` — a malformed doc renders invisible rather than crashing, and
+// lint flags it. Valid docs never hit the fallback.
+// ---------------------------------------------------------------------------
+// Kinds — the two semantic kinds (design §3): `knowledge` (consult — procedural
+// playbooks + factual references merged) vs `preference` (behave — standing
+// directives). `kind` is a load-bearing binary, not a content taxonomy.
+// ---------------------------------------------------------------------------
+export const KINDS = ['knowledge', 'preference'];
+/** Is `v` one of the two valid document kinds? */
+export function isDocKind(v) {
+    return typeof v === 'string' && KINDS.includes(v);
+}
+// ---------------------------------------------------------------------------
+// The 4-rung visibility ladder (design §4). A strict, monotone ordering where
+// each rung is a superset of disclosure over the one before:
+//   none < name < preview < content
+// ---------------------------------------------------------------------------
+export const RUNGS = ['none', 'name', 'preview', 'content'];
+/** Ordinal of a rung on the ladder (none=0 … content=3). */
+export function rungRank(r) {
+    return RUNGS.indexOf(r);
+}
+/** Does rung `r` disclose at least as much as `min`? — e.g.
+ *  `rungAtLeast(doc.systemPromptVisibility, 'name')` ⇒ "shows at boot at all". */
+export function rungAtLeast(r, min) {
+    return rungRank(r) >= rungRank(min);
+}
+// ---------------------------------------------------------------------------
+// The neutral fallback rung used only when a doc omits a visibility field or
+// carries an invalid one. NOT a default an author may lean on — authoring-time
+// enforcement requires explicit rungs; this is purely the runtime parser's
+// never-throw floor (a malformed doc renders invisible, and lint flags it).
+// ---------------------------------------------------------------------------
+export const FALLBACK_RUNG = 'none';
+// ---------------------------------------------------------------------------
+// Display-name normalization — the optional `NN-` ordering pin. A doc's
+// physical path may carry a two-digit numeric prefix on a file or directory
+// segment (`00-runtime-base.md`, `01-spine/`) purely to pin structural order
+// against natural sort (design: builtin prompt corpus, used sparingly). The
+// prefix is NEVER part of the doc's identity: every identity-facing surface —
+// MemoryDoc.name, direct lookup, leaf fallback, `crtr memory read`/`list`,
+// prompt render, on-read display — derives from the NORMALIZED segments, so
+// `00-runtime-base` displays/dedups/resolves as `runtime-base`. When a doc
+// sets an explicit frontmatter `name`, that normalized name wins instead of
+// the path-derived fallback. Only the physical path keeps the prefix.
+// ---------------------------------------------------------------------------
+const NUMERIC_PREFIX_RE = /^\d{2}-/;
+/** Strip an optional `NN-` ordering prefix from ONE path segment (file or
+ *  directory display name). `00-runtime-base` -> `runtime-base`; `spine` (no
+ *  prefix) is unchanged. */
+export function normalizeNameSegment(segment) {
+    return segment.replace(NUMERIC_PREFIX_RE, '');
+}
+/** Normalize a full slash-separated path-derived doc name by stripping the
+ *  optional numeric prefix from EVERY segment: `01-spine/00-has-manager` ->
+ *  `spine/has-manager`. This is the identity a doc displays, dedups, and
+ *  resolves under — distinct from its physical path, which keeps the prefix. */
+export function normalizeDocName(name) {
+    return name.split('/').map(normalizeNameSegment).join('/');
+}
+// ---------------------------------------------------------------------------
+// Substrate identity — the ONE explicit-name-then-path-fallback rule. A doc's
+// resolver identity is its explicit frontmatter `name` when present (normalized),
+// otherwise the caller-supplied path-derived fallback. Every loader that turns a
+// physical .md file into a named doc (the resolver's `listMemoryDocsInDir`, the
+// on-read positional loader) calls this ONE helper, so a doc's identity never
+// depends on which path loaded it.
+// ---------------------------------------------------------------------------
+/** Resolve a doc's identity from its raw frontmatter record: an explicit
+ *  `name` field wins (trimmed + normalized), else `fallbackName` (the
+ *  normalized path-derived name). */
+export function resolveDocName(fm, fallbackName) {
+    const raw = fm?.['name'];
+    const explicit = typeof raw === 'string' && raw.trim() !== '' ? normalizeDocName(raw.trim()) : '';
+    return explicit !== '' ? explicit : fallbackName;
+}
+// ---------------------------------------------------------------------------
+// Parse / validate.
+// ---------------------------------------------------------------------------
+/** Parse a raw frontmatter record (from `parseFrontmatterGeneric`, via the
+ *  resolver) into a typed schema with defaults applied. Returns `null` when the
+ *  record is absent or carries no valid `kind` — i.e. it is not a substrate
+ *  document and cannot be classified. Tolerant of every other imperfection (a
+ *  missing `when-and-why-to-read` defaults to '', a missing/bad rung falls back
+ *  to the neutral floor `none`), so a renderer mapping over many docs never
+ *  throws. Authoring-time enforcement of these fields lives in `crtr memory
+ *  write` (on create) and `crtr memory lint`. */
+export function parseSubstrateFrontmatter(fm) {
+    if (fm === null)
+        return null;
+    if (!isDocKind(fm.kind))
+        return null;
+    const kind = fm.kind;
+    return {
+        kind,
+        whenAndWhyToRead: strField(fm['when-and-why-to-read']),
+        shortForm: strField(fm['short-form']),
+        systemPromptVisibility: parseRung(fm['system-prompt-visibility'], FALLBACK_RUNG),
+        fileReadVisibility: parseRung(fm['file-read-visibility'], FALLBACK_RUNG),
+        gate: parseGate(fm.gate),
+        appliesTo: parseAppliesTo(fm['applies-to']),
+        readWhen: parseGate(fm['read-when']),
+        slash: fm.slash === true,
+        rationale: parseRationale(fm['rationale']),
+    };
+}
+/** Parse a resolved MemoryDoc into a fully-typed SubstrateDoc (schema + the
+ *  resolver's name/scope/path/body). Returns `null` for a non-substrate doc
+ *  (no valid `kind`), so callers can `docs.map(parseSubstrateDoc).filter(...)`. */
+export function parseSubstrateDoc(doc) {
+    const schema = parseSubstrateFrontmatter(doc.frontmatter);
+    if (schema === null)
+        return null;
+    return { ...schema, name: doc.name, scope: doc.scope, path: doc.path, body: doc.body };
+}
+/** The kind a doc resolves to for `--kind` filtering/matching: the substrate
+ *  kind when the frontmatter parses as a valid substrate doc, else the raw
+ *  frontmatter `kind` string when present (even if not one of the two valid
+ *  kinds — an authoring error, not grounds to silently reclassify it), else
+ *  the legacy default `knowledge` for a frontmatter-less/kindless doc. The
+ *  single coercion `memory read`'s resolution and result display share, so a
+ *  `--kind` filter and the displayed `kind` field never disagree. */
+export function effectiveDocKind(doc) {
+    const sub = parseSubstrateDoc(doc);
+    if (sub !== null)
+        return sub.kind;
+    const raw = doc.frontmatter?.['kind'];
+    return typeof raw === 'string' ? raw : 'knowledge';
+}
+/** The `preview`-rung routing line (design §4): the `when-and-why-to-read`
+ *  field rendered essentially verbatim — it is already authored as the complete
+ *  routing sentence ("When …, this <kind> should be read …"), so there is no
+ *  template to compose. Both boot and on-read render this identical line, so it
+ *  lives once here to prevent drift. Light cleanup normalizes the trailing
+ *  period. */
+export function previewLine(doc) {
+    const line = doc.whenAndWhyToRead.trim().replace(/\.+$/, '');
+    return line === '' ? '' : `${line}.`;
+}
+// ---------------------------------------------------------------------------
+// Field coercion helpers (private).
+// ---------------------------------------------------------------------------
+function strField(v) {
+    return typeof v === 'string' ? v : '';
+}
+/** Resolve an optional `rationale` field: a non-empty string is carried as-is
+ *  (multi-line YAML block scalars parse to a plain string, so no special
+ *  handling is needed); anything else (absent, blank, non-string) yields
+ *  `undefined` — the doc simply carries no rationale. */
+function parseRationale(v) {
+    return typeof v === 'string' && v.trim() !== '' ? v : undefined;
+}
+/** Resolve a visibility field to a ladder rung, falling back to the neutral
+ *  floor when absent/invalid. */
+function parseRung(v, fallback) {
+    return typeof v === 'string' && RUNGS.includes(v)
+        ? v
+        : fallback;
+}
+/** A gate is engaged only when frontmatter carries a non-null, non-array object
+ *  (the predicate vocabulary's field→matcher map). Anything else (absent, null,
+ *  scalar, array) ⇒ no gate ⇒ always eligible — the safe default that never
+ *  silently hides a doc. An empty `{}` IS carried (and is inert per design §4). */
+function parseGate(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v)
+        ? v
+        : undefined;
+}
+/** Normalize `applies-to` to a non-empty glob list, or undefined (positional
+ *  trigger only). Accepts a single string or an array of strings. */
+function parseAppliesTo(v) {
+    if (typeof v === 'string') {
+        return v.trim() === '' ? undefined : [v];
+    }
+    if (Array.isArray(v)) {
+        const globs = v.filter((g) => typeof g === 'string' && g.trim() !== '');
+        return globs.length > 0 ? globs : undefined;
+    }
+    return undefined;
+}

package/dist/core/substrate/session-cache.d.ts

@@ -0,0 +1,25 @@
+import type { MemoryDoc } from '../memory-resolver.js';
+import type { SubstrateDoc } from './schema.js';
+type ListAllMemoryDocsFn = () => MemoryDoc[];
+type ParseSubstrateDocFn = (doc: MemoryDoc) => SubstrateDoc | null;
+/** Called by canvas-doc-substrate.ts on every `session_start`.
+ *  Resets all cached values so the next access triggers a fresh scan.  */
+export declare function clearSessionCache(): void;
+/** The FULL corpus (listAllMemoryDocs()), INCLUDING node scope, scanned at
+ *  most once per session. `listFn` is injected by the caller to avoid
+ *  circular imports at module init. This is the single filesystem walk the
+ *  whole module performs — `cachedAllMemoryDocs` below derives its
+ *  node-excluded view from this result rather than re-scanning. Consumers
+ *  that need every referenceable doc (inline memory-reference inventory) call
+ *  this directly instead of `cachedAllMemoryDocs`. */
+export declare function cachedAllMemoryDocsInclusive(listFn: ListAllMemoryDocsFn): MemoryDoc[];
+/** allMemoryDocsInclusive mapped through parseSubstrateDoc + null-filtered,
+ *  INCLUDING node scope. */
+export declare function cachedSubstrateDocsInclusive(listFn: ListAllMemoryDocsFn, parseFn: ParseSubstrateDocFn): SubstrateDoc[];
+/** All memory docs (listAllMemoryDocs()), scanned once per session.
+ *  `listFn` is injected by the caller to avoid circular imports at module init. */
+export declare function cachedAllMemoryDocs(listFn: ListAllMemoryDocsFn): MemoryDoc[];
+/** allMemoryDocs mapped through parseSubstrateDoc + null-filtered.
+ *  Both render.ts and on-read.ts consume this. */
+export declare function cachedSubstrateDocs(listFn: ListAllMemoryDocsFn, parseFn: ParseSubstrateDocFn): SubstrateDoc[];
+export {};

package/dist/core/substrate/session-cache.js

@@ -0,0 +1,101 @@
+// session-cache.ts — a per-session parse cache for the document substrate.
+//
+// Both substrate hooks (boot render in render.ts, on-read in on-read.ts) re-walk
+// and re-YAML-parse the full corpus on every invocation without memoization.  At
+// the two highest-frequency hook sites this is O(reads × corpus) and O(turns ×
+// corpus) respectively.  This module provides a single session-scoped cache that
+// the hooks read from, so the corpus is scanned and parsed AT MOST ONCE per
+// session turn/read burst.
+//
+// Lifecycle:
+//   • clearSessionCache() — called on every `session_start` by canvas-doc-
+//     substrate.ts.  It does NOT need to be called before the first use: a
+//     cold cache (null) triggers a fresh scan on the next read.
+//   • All getters lazily populate on first call after a clear.
+//   • The cache is a module-level singleton (one JS module instance per pi
+//     process, and each pi process hosts exactly one canvas node session).
+//
+// Cached entries:
+//   • allMemoryDocsInclusive — the full listAllMemoryDocs() corpus, UNFILTERED
+//                        (includes node scope). This is the ONE underlying
+//                        filesystem scan+parse the whole module performs per
+//                        session; every other entry below derives from it by
+//                        filtering/mapping, never by calling listFn() again.
+//   • substrateDocsInclusive — allMemoryDocsInclusive mapped through
+//                        parseSubstrateDoc and null-filtered, still including
+//                        node scope. Consumers that need every referenceable
+//                        doc (e.g. the inline memory-reference inventory) use
+//                        this pair.
+//   • allMemoryDocs    — allMemoryDocsInclusive with node-scope docs excluded
+//                        (unchanged boot/on-read behavior — see the comment on
+//                        cachedAllMemoryDocs). Shared by both render.ts and
+//                        on-read.ts.
+//   • substrateDocs    — allMemoryDocs mapped through parseSubstrateDoc and
+//                        null-filtered.  Used by render.ts's resolverDocs and
+//                        on-read.ts's appliesToCandidates.
+// Node subjects are deliberately NOT cached: lifecycle, mode, kind, and other
+// gate inputs can change while a resident broker/session remains live. Rendering
+// must always gate against the current persisted node metadata.
+const _cache = {
+    allMemoryDocsInclusive: null,
+    substrateDocsInclusive: null,
+    allMemoryDocs: null,
+    substrateDocs: null,
+};
+/** Called by canvas-doc-substrate.ts on every `session_start`.
+ *  Resets all cached values so the next access triggers a fresh scan.  */
+export function clearSessionCache() {
+    _cache.allMemoryDocsInclusive = null;
+    _cache.substrateDocsInclusive = null;
+    _cache.allMemoryDocs = null;
+    _cache.substrateDocs = null;
+}
+/** The FULL corpus (listAllMemoryDocs()), INCLUDING node scope, scanned at
+ *  most once per session. `listFn` is injected by the caller to avoid
+ *  circular imports at module init. This is the single filesystem walk the
+ *  whole module performs — `cachedAllMemoryDocs` below derives its
+ *  node-excluded view from this result rather than re-scanning. Consumers
+ *  that need every referenceable doc (inline memory-reference inventory) call
+ *  this directly instead of `cachedAllMemoryDocs`. */
+export function cachedAllMemoryDocsInclusive(listFn) {
+    if (_cache.allMemoryDocsInclusive === null) {
+        _cache.allMemoryDocsInclusive = listFn();
+    }
+    return _cache.allMemoryDocsInclusive;
+}
+/** allMemoryDocsInclusive mapped through parseSubstrateDoc + null-filtered,
+ *  INCLUDING node scope. */
+export function cachedSubstrateDocsInclusive(listFn, parseFn) {
+    if (_cache.substrateDocsInclusive === null) {
+        _cache.substrateDocsInclusive = cachedAllMemoryDocsInclusive(listFn)
+            .map(parseFn)
+            .filter((d) => d !== null);
+    }
+    return _cache.substrateDocsInclusive;
+}
+/** All memory docs (listAllMemoryDocs()), scanned once per session.
+ *  `listFn` is injected by the caller to avoid circular imports at module init. */
+export function cachedAllMemoryDocs(listFn) {
+    if (_cache.allMemoryDocs === null) {
+        // The boot pipeline (render + on-read) EXCLUDES node-scope docs: node-local
+        // memory surfaces at boot via render.ts's nodeLocalDocs (any kind, floored
+        // into the knowledge block), NOT through the resolver corpus, so a node doc
+        // must not also enter here (it would double-surface at boot and could fire
+        // on-read). The `node` scope reaches CLI read/list/find/delete through the
+        // uncached listAllMemoryDocs() path instead. Derived from the inclusive
+        // cache by filtering, so listFn() itself still runs at most once per
+        // session even though both views are consumed.
+        _cache.allMemoryDocs = cachedAllMemoryDocsInclusive(listFn).filter((d) => d.scope !== 'node');
+    }
+    return _cache.allMemoryDocs;
+}
+/** allMemoryDocs mapped through parseSubstrateDoc + null-filtered.
+ *  Both render.ts and on-read.ts consume this. */
+export function cachedSubstrateDocs(listFn, parseFn) {
+    if (_cache.substrateDocs === null) {
+        _cache.substrateDocs = cachedAllMemoryDocs(listFn)
+            .map(parseFn)
+            .filter((d) => d !== null);
+    }
+    return _cache.substrateDocs;
+}

package/dist/core/substrate/subject-fields.d.ts

@@ -0,0 +1,45 @@
+import type { Mode, Lifecycle } from '../canvas/types.js';
+/** The gate input: a node's configuration as a structured object. Field names
+ *  and shape are the predicate vocabulary's dotted paths (`orchestration.depth`,
+ *  `hasManager`, …). There is intentionally NO `tags` field — NodeMeta has none. */
+export interface NodeConfigSubject {
+    /** The node's role, free-form (developer | explore | design | …). NodeMeta.kind. */
+    kind: string;
+    /** base (hands-on worker) | orchestrator (delegating manager). NodeMeta.mode. */
+    mode: Mode;
+    /** terminal (worker) | resident (manager). NodeMeta.lifecycle. */
+    lifecycle: Lifecycle;
+    /** Spine position: does this node have a manager? (= parent !== null). */
+    hasManager: boolean;
+    /** The node's working directory on disk. NodeMeta.cwd. */
+    cwd: string;
+    /** DERIVED: the scope scope.ts resolves for `cwd` — `project` when a
+     *  nearest-ancestor `.crouter/` exists at/above cwd, else `user`. */
+    scope: 'user' | 'project';
+    /** DERIVED orchestration metrics. */
+    orchestration: {
+        /** Spine distance (hops) from this node up to its root orchestrator. The
+         *  root itself is 0; a direct child of the root is 1; etc. */
+        depth: number;
+    };
+    /** DERIVED: `meta.profile_id` resolved to its manifest's mutable `name` (NOT
+     *  the stable directory id — gate authors write `gate: {profile: <name>}`).
+     *  null for historical null-profile rows, and null (never throwing) when the
+     *  profile has been deleted or its manifest is unreadable — this is a HOT,
+     *  every-doc-render path and must never brick boot/on-read gating. */
+    profile: string | null;
+}
+/** The scope a cwd resolves into: `project` when scope.ts finds a
+ *  nearest-ancestor `.crouter/` at/above it, else `user`. Reuses the existing
+ *  resolver (`projectScopeRoot`). NOTE: `findProjectScopeRoot` is process-cached
+ *  on first call, so for a node assembling its OWN subject (cwd === process.cwd)
+ *  this is exact; resolving an arbitrary unrelated cwd in the same process would
+ *  return the cached root — fine for per-node subject assembly. */
+export declare function scopeForCwd(cwd: string): 'user' | 'project';
+/** Resolve `profile_id` to the manifest's mutable `name` for the gate subject.
+ *  NEVER throws: a missing/deleted profile resolves to `null` silently (the
+ *  ordinary lifecycle of a node whose profile was deleted out from under it);
+ *  any OTHER failure (e.g. an unreadable/corrupt manifest slipping past
+ *  `loadProfileManifest`'s own tolerance) is logged and still resolves to
+ *  `null` rather than throwing — this runs on every gated-doc render. */
+export declare function profileNameFor(profileId: string | null | undefined): string | null;

package/dist/core/substrate/subject-fields.js

@@ -0,0 +1,38 @@
+// subject-fields.ts — the PURE half of subject assembly: the NodeConfigSubject
+// shape plus the two derived-field resolvers (`scopeForCwd`, `profileNameFor`)
+// that read scope/profile config but NEVER the canvas-db. Split out of
+// subject.ts so CLI consumers (`sys prompt-review`) can build a subject from an
+// API-fetched node without pulling subject.ts's canvas-db reach (getNode/getRow).
+// The canvas-db assembler (`assembleNodeSubject`, `spineDepth`) stays in
+// subject.ts for broker/daemon-side callers.
+import { projectScopeRoot } from '../scope.js';
+import { loadProfileManifest } from '../profiles/manifest.js';
+import { CrtrError } from '../errors.js';
+/** The scope a cwd resolves into: `project` when scope.ts finds a
+ *  nearest-ancestor `.crouter/` at/above it, else `user`. Reuses the existing
+ *  resolver (`projectScopeRoot`). NOTE: `findProjectScopeRoot` is process-cached
+ *  on first call, so for a node assembling its OWN subject (cwd === process.cwd)
+ *  this is exact; resolving an arbitrary unrelated cwd in the same process would
+ *  return the cached root — fine for per-node subject assembly. */
+export function scopeForCwd(cwd) {
+    return projectScopeRoot(cwd) !== null ? 'project' : 'user';
+}
+/** Resolve `profile_id` to the manifest's mutable `name` for the gate subject.
+ *  NEVER throws: a missing/deleted profile resolves to `null` silently (the
+ *  ordinary lifecycle of a node whose profile was deleted out from under it);
+ *  any OTHER failure (e.g. an unreadable/corrupt manifest slipping past
+ *  `loadProfileManifest`'s own tolerance) is logged and still resolves to
+ *  `null` rather than throwing — this runs on every gated-doc render. */
+export function profileNameFor(profileId) {
+    if (profileId === undefined || profileId === null || profileId === '')
+        return null;
+    try {
+        return loadProfileManifest(profileId).manifest.name;
+    }
+    catch (err) {
+        if (err instanceof CrtrError && err.code === 'not_found')
+            return null;
+        console.warn(`[subject] profile "${profileId}" failed to resolve for node subject assembly: ${err.message}`);
+        return null;
+    }
+}

package/dist/core/substrate/subject.d.ts

@@ -0,0 +1,12 @@
+import { type NodeConfigSubject } from './subject-fields.js';
+export { scopeForCwd, profileNameFor } from './subject-fields.js';
+export type { NodeConfigSubject } from './subject-fields.js';
+/** Spine distance from `nodeId` up to its root orchestrator: count the hops
+ *  walking the `parent` chain (canvas-db rows) until a row with no parent (the
+ *  root). The root is depth 0. Cycle-guarded (parents must not cycle, but never
+ *  loop forever) — mirrors `rootOfSpine` in runtime/placement.ts. */
+export declare function spineDepth(nodeId: string): number;
+/** Assemble the node-config subject for `nodeId` from its `NodeMeta` + the
+ *  derived fields. Returns `null` when the node has no canvas-db row (an
+ *  unknown id). Pure aside from the canvas-db + profile-manifest reads. */
+export declare function assembleNodeSubject(nodeId: string): NodeConfigSubject | null;

package/dist/core/substrate/subject.js

@@ -0,0 +1,47 @@
+// subject.ts — the CANVAS-DB half of subject assembly: `assembleNodeSubject`
+// (reads NodeMeta rows) and `spineDepth` (walks the parent chain). The PURE
+// derived-field resolvers and the NodeConfigSubject shape live in
+// subject-fields.ts (re-exported here); a CLI consumer that must stay off the
+// canvas-db imports those from subject-fields.ts directly. See design-substrate.md
+// §4 + plan-substrate.md §2.
+import { getNode, getRow } from '../canvas/index.js';
+import { scopeForCwd, profileNameFor } from './subject-fields.js';
+export { scopeForCwd, profileNameFor } from './subject-fields.js';
+/** Spine distance from `nodeId` up to its root orchestrator: count the hops
+ *  walking the `parent` chain (canvas-db rows) until a row with no parent (the
+ *  root). The root is depth 0. Cycle-guarded (parents must not cycle, but never
+ *  loop forever) — mirrors `rootOfSpine` in runtime/placement.ts. */
+export function spineDepth(nodeId) {
+    let cur = nodeId;
+    const seen = new Set();
+    let hops = 0;
+    for (;;) {
+        if (seen.has(cur))
+            break;
+        seen.add(cur);
+        const row = getRow(cur);
+        if (row === null || row.parent == null)
+            break;
+        cur = row.parent;
+        hops++;
+    }
+    return hops;
+}
+/** Assemble the node-config subject for `nodeId` from its `NodeMeta` + the
+ *  derived fields. Returns `null` when the node has no canvas-db row (an
+ *  unknown id). Pure aside from the canvas-db + profile-manifest reads. */
+export function assembleNodeSubject(nodeId) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return null;
+    return {
+        kind: meta.kind,
+        mode: meta.mode,
+        lifecycle: meta.lifecycle,
+        hasManager: (meta.parent ?? null) !== null,
+        cwd: meta.cwd,
+        scope: scopeForCwd(meta.cwd),
+        orchestration: { depth: spineDepth(nodeId) },
+        profile: profileNameFor(meta.profile_id),
+    };
+}

package/dist/core/timing.d.ts

@@ -0,0 +1,11 @@
+/** True when CRTR_TIMING is set — guard expensive marker payloads with this. */
+export declare function timingEnabled(): boolean;
+/** Label this process in the timing log (e.g. 'viewer', 'broker'). */
+export declare function timingProc(name: string): void;
+/**
+ * Record one phase marker. Columns:
+ *   `+`  ms since the shared cross-process origin (the whole front-door clock)
+ *   `Δ`  ms since the previous marker in THIS process
+ *   `up` ms since this process started (same sense as broker `duration_ms`)
+ */
+export declare function mark(phase: string, fields?: Record<string, unknown>): void;