@crouton-kit/crouter 0.3.17 → 0.3.19

package/dist/core/substrate/render.js

@@ -0,0 +1,256 @@
+// render.ts — the pure boot-render functions for the document substrate.
+//
+// Two boot targets, three functions:
+//   • the SYSTEM-PROMPT half — `## Skills` (renderSkillsSection) + `## Preferences`
+//     (renderPreferencesSection) — strings the D2 `before_agent_start` extension
+//     splices into the system prompt (built by a sibling AFTER this module);
+//   • the `<crtr-context>` half — `## References` (renderReferencesBlock) — the
+//     string wired into bearings.ts's session_start message, REPLACING the old
+//     `<memory>` block.
+//
+// Every doc flows through the same pipeline (design §4/§6/§9):
+//   MemoryDoc → parseSubstrateDoc → (null-filter non-substrate) →
+//   gatePasses(doc, assembleNodeSubject(nodeId)) → render at the doc's
+//   `system-prompt-visibility` rung.
+//
+// Pure + defensive: reads the resolver, canvas-db (subject assembly), and the
+// node-local memory dir; performs no writes and no side effects. A single
+// malformed doc must never throw the whole render — parseSubstrateDoc returns
+// null for a non-substrate doc and is `.filter()`ed out; per-file loads are
+// wrapped so one bad file is skipped, not fatal.
+import { relative, sep } from 'node:path';
+import { SCOPE_SKILL_PLUGIN } from '../../types.js';
+import { listAllPlugins, listAllSkills } from '../resolver.js';
+import { renderCatalogSection } from '../../commands/skill/shared.js';
+import { listAllMemoryDocs } from '../memory-resolver.js';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+import { pathExists, readText, walkFiles } from '../fs-utils.js';
+import { memoryDir } from '../runtime/memory.js';
+import { assembleNodeSubject, gatePasses, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, } from './index.js';
+import { cachedAllPlugins, cachedNodeSubject, cachedSubstrateDocs, } from './session-cache.js';
+// ---------------------------------------------------------------------------
+// The shared per-doc pipeline.
+// ---------------------------------------------------------------------------
+/** The resolver-provided substrate docs of one `kind`, eligible at boot for
+ *  `subject`: parsed (non-substrate docs null-filtered), gate-passed, and at a
+ *  system-prompt rung above `none`. Resolver = user + project + builtin scopes
+ *  (precedence-ordered); node-local is loaded separately (see nodeLocalDocs).
+ *  Uses the per-session cache so the full corpus is scanned+parsed at most once
+ *  per session across the three boot-render calls. */
+function resolverDocs(subject, kind) {
+    let docs;
+    try {
+        docs = cachedSubstrateDocs(listAllMemoryDocs, parseSubstrateDoc);
+    }
+    catch {
+        return [];
+    }
+    return docs
+        .filter((d) => d.kind === kind)
+        .filter((d) => gatePasses(d, subject))
+        .filter((d) => d.systemPromptVisibility !== 'none');
+}
+/** The node-local memory docs eligible at boot. Node-local memory lives in the
+ *  canvas home (`nodes/<id>/context/memory/`) and is OUTSIDE the scope resolver,
+ *  so it is loaded directly here, its raw frontmatter run through
+ *  parseSubstrateFrontmatter (mirroring the resolver pipeline), then gate-passed.
+ *  Old-format / non-substrate files (incl. the MEMORY.md index, which has no
+ *  `kind`) parse to null and drop out. Returned across ALL kinds — node-local is
+ *  the catch-all this-node store and rides into the references block as the
+ *  replacement for the old node-local `<memory>` stanza.
+ *
+ *  IMPORTANT: node-local docs are NOT filtered by `systemPromptVisibility` rung.
+ *  A migrated node-local reference defaults to rung `none`, which would make it
+ *  invisible — but the design explicitly says "node-local rides into references"
+ *  without qualification.  Suppressing them by rung contradicts that contract.
+ *  A `none`-rung node-local doc renders as a `### <name>` title stub (the `name`
+ *  rung fallback in renderSubSection), which is the minimum meaningful surface.
+ *  Only gate evaluation removes a node-local doc from the block. */
+function nodeLocalDocs(nodeId, subject) {
+    const dir = memoryDir(nodeId);
+    if (!pathExists(dir))
+        return [];
+    const out = [];
+    for (const file of walkFiles(dir, (n) => n.endsWith('.md'))) {
+        const name = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
+        if (!name)
+            continue;
+        try {
+            const { data, body } = parseFrontmatterGeneric(readText(file));
+            const schema = parseSubstrateFrontmatter(data);
+            if (schema === null)
+                continue;
+            // node-local is NOT a resolver scope; `scope` is a placeholder never read
+            // by gate eval (keyed off the NODE subject, not the doc) nor by the
+            // renderers (keyed off name / body / rung).
+            out.push({ ...schema, name, scope: 'user', path: file, body });
+        }
+        catch {
+            // A single malformed file is skipped, never fatal to the render.
+            continue;
+        }
+    }
+    // Gate-filter only: rung is NOT filtered (see comment above).
+    return out.filter((d) => gatePasses(d, subject));
+}
+// ---------------------------------------------------------------------------
+// Sub-section render (preview / content / name) — the per-doc `###` block used
+// by every kind EXCEPT name-rung skills (those fold into the compact catalog).
+// ---------------------------------------------------------------------------
+/** One doc rendered as its own `### <name>` sub-section, at its system-prompt
+ *  rung: `preview` → the generated routing line; `content` → the full body;
+ *  `name` → the title alone (`none` is filtered upstream, never reaches here). */
+function renderSubSection(d) {
+    const header = `### ${d.name}`;
+    switch (d.systemPromptVisibility) {
+        case 'preview':
+            return `${header}\n${previewLine(d)}`;
+        case 'content': {
+            const body = d.body.trim();
+            return body === '' ? header : `${header}\n${body}`;
+        }
+        default: // 'name'
+            return header;
+    }
+}
+// ---------------------------------------------------------------------------
+// 1. Skills section — `## Skills` (system prompt).
+// ---------------------------------------------------------------------------
+/** The compact, group-collapsed `name`-rung catalog: the UNION of name-rung
+ *  substrate `skill` docs (the migrated scope-local + builtin skills, rendered
+ *  as scope-local `_` entries) WITH plugin/marketplace skills (which stay
+ *  resolver-provided, NOT migrated — named-plugin skills at user/project scope;
+ *  the SCOPE_SKILL_PLUGIN sentinel and builtin scope are EXCLUDED because they
+ *  become substrate docs). Reuses skill/shared.ts's renderCatalogSection
+ *  group-collapse so the boot catalog matches today's `<skills count=N>` shape.
+ *  Returns '' when nothing is in the catalog. */
+function renderSkillCatalog(nameRungSkillDocs) {
+    let pluginSkills;
+    try {
+        pluginSkills = listAllSkills().filter((s) => s.enabled && s.plugin !== SCOPE_SKILL_PLUGIN && s.scope !== 'builtin');
+    }
+    catch {
+        pluginSkills = [];
+    }
+    const entries = [
+        ...pluginSkills.map((s) => ({ scope: s.scope, plugin: s.plugin, name: s.name })),
+        ...nameRungSkillDocs.map((d) => ({ scope: d.scope, plugin: SCOPE_SKILL_PLUGIN, name: d.name })),
+    ];
+    if (entries.length === 0)
+        return '';
+    // Group by scope+plugin → forest-root names (drop nested children), mirroring
+    // buildSkillCatalog's source construction.
+    const bySource = new Map();
+    for (const e of entries) {
+        const key = `${e.scope}\t${e.plugin}`;
+        const arr = bySource.get(key);
+        if (arr)
+            arr.push(e);
+        else
+            bySource.set(key, [e]);
+    }
+    const projectSources = [];
+    const userSources = [];
+    for (const [key, group] of bySource) {
+        const [scope, plugin] = key.split('\t');
+        const names = group.map((g) => g.name);
+        const roots = names
+            .filter((n) => !names.some((m) => m !== n && n.startsWith(m + '/')))
+            .sort();
+        if (roots.length === 0)
+            continue;
+        (scope === 'project' ? projectSources : userSources).push({ plugin, roots });
+    }
+    const descriptions = new Map();
+    try {
+        for (const p of cachedAllPlugins(listAllPlugins)) {
+            if (p.manifest.description)
+                descriptions.set(p.name, p.manifest.description);
+        }
+    }
+    catch {
+        // descriptions are an optional suffix; render without them on failure.
+    }
+    const body = [];
+    renderCatalogSection('Project', projectSources, descriptions, body);
+    renderCatalogSection('User', userSources, descriptions, body);
+    // renderCatalogSection leads each section with a blank separator; drop it so
+    // the catalog starts on its first real line.
+    while (body.length > 0 && body[0] === '')
+        body.shift();
+    return body.length === 0 ? '' : body.join('\n');
+}
+/** The `## Skills` system-prompt section: every eligible `kind: skill` doc,
+ *  rendered at its `system-prompt-visibility`. `name`-rung skills collapse into
+ *  one compact catalog (group-collapsed, unioned with plugin/marketplace
+ *  skills); `preview`/`content`-rung skills each get a `###` sub-section.
+ *  Returns '' when nothing is eligible. */
+export function renderSkillsSection(nodeId) {
+    const subject = cachedNodeSubject(nodeId, assembleNodeSubject);
+    if (subject === null)
+        return '';
+    const skills = resolverDocs(subject, 'skill');
+    const catalog = renderSkillCatalog(skills.filter((d) => d.systemPromptVisibility === 'name'));
+    const elevated = skills
+        .filter((d) => d.systemPromptVisibility !== 'name')
+        .map(renderSubSection);
+    const blocks = [catalog, ...elevated].filter((s) => s !== '');
+    if (blocks.length === 0)
+        return '';
+    return `## Skills\n\n${blocks.join('\n\n')}`;
+}
+// ---------------------------------------------------------------------------
+// 2. Preferences section — `## Preferences` (system prompt).
+// ---------------------------------------------------------------------------
+/** The `## Preferences` system-prompt section: every eligible `kind: preference`
+ *  doc as its own `###` sub-section, at its `system-prompt-visibility` (the
+ *  preference default rung is `preview` → the routing line). Returns '' when
+ *  nothing is eligible. */
+export function renderPreferencesSection(nodeId) {
+    const subject = cachedNodeSubject(nodeId, assembleNodeSubject);
+    if (subject === null)
+        return '';
+    const subs = resolverDocs(subject, 'preference')
+        .map(renderSubSection)
+        .filter((s) => s !== '');
+    if (subs.length === 0)
+        return '';
+    return `## Preferences\n\n${subs.join('\n\n')}`;
+}
+// ---------------------------------------------------------------------------
+// 3. References block — `## References` (inside the <crtr-context> message).
+// ---------------------------------------------------------------------------
+/** The `## References` block embedded INSIDE the `<crtr-context>` session_start
+ *  message (the bearings caller pushes the returned string into the block, or
+ *  drops it when ''). Holds every eligible `kind: reference` resolver doc at its
+ *  `system-prompt-visibility` (reference boot default is `none`, so only
+ *  author-promoted references show) PLUS the node-local memory docs (any kind),
+ *  each a `###` sub-section. Replaces the old `<memory>` block. Returns '' when
+ *  nothing is eligible.
+ *
+ *  DEFENSIVE: each doc is rendered in its own try/catch so a single malformed
+ *  doc drops only itself (with a loud stderr warning naming the offending path),
+ *  never silently swallowing the entire block (identity included).  Per the CTO
+ *  ruling, strictness lives at the COLLECTION layer (memory-resolver.ts); this
+ *  catch is error ISOLATION at the render layer, not a fallback parser. */
+export function renderReferencesBlock(nodeId) {
+    const subject = cachedNodeSubject(nodeId, assembleNodeSubject);
+    if (subject === null)
+        return '';
+    const docs = [...resolverDocs(subject, 'reference'), ...nodeLocalDocs(nodeId, subject)];
+    const subs = [];
+    for (const d of docs) {
+        try {
+            const rendered = renderSubSection(d);
+            if (rendered !== '')
+                subs.push(rendered);
+        }
+        catch (e) {
+            const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
+            process.stderr.write(`[crtr substrate] renderReferencesBlock: skipping doc "${d.path}": ${msg}\n`);
+        }
+    }
+    if (subs.length === 0)
+        return '';
+    return `## References\n\n${subs.join('\n\n')}`;
+}

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

@@ -0,0 +1,76 @@
+import type { Scope } from '../../types.js';
+import type { MemoryDoc } from '../memory-resolver.js';
+export declare const KINDS: readonly ["skill", "reference", "preference"];
+export type DocKind = (typeof KINDS)[number];
+/** Is `v` one of the three 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 KIND_DEFAULT_RUNGS: Record<DocKind, {
+    systemPrompt: Rung;
+    fileRead: Rung;
+}>;
+/** 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`/`why`) and optionals all
+ *  resolved to concrete typed values. */
+export interface SubstrateSchema {
+    /** Which of the three semantic kinds. */
+    kind: DocKind;
+    /** Routing condition — "When you are in a situation like X…" (design §4). */
+    when: string;
+    /** Payoff — "…because Z." Half of the generated preview line. */
+    why: 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[];
+}
+/** A fully-resolved substrate document: the parsed schema PLUS the resolver's
+ *  path-derived identity 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 {
+    /** Path-derived identity, e.g. `taste/document-substrate` (resolver-supplied). */
+    name: string;
+    /** The scope this doc resolved from. */
+    scope: Scope;
+    /** 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 or defaulted. Tolerant of every other
+ *  imperfection (missing `when`/`why` default to '', a bad rung falls back to
+ *  the kind default), so a renderer mapping over many docs never throws. */
+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 generated `preview`-rung routing line (design §4), composed from the two
+ *  required prose fields and the kind: `"{when}, read this {kind}. {why}."`.
+ *  Both boot and on-read render render this identical line, so it lives once
+ *  here to prevent drift. Light cleanup avoids doubled punctuation. */
+export declare function previewLine(doc: Pick<SubstrateSchema, 'kind' | 'when' | 'why'>): string;

package/dist/core/substrate/schema.js

@@ -0,0 +1,124 @@
+// schema.ts — the typed shape of a substrate document's frontmatter, the
+// visibility ladder, the kind→default-rungs table, and the parse/validate
+// function that turns a resolved MemoryDoc into a fully-typed SubstrateDoc with
+// defaults applied. 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) + §9 (defaults).
+// ---------------------------------------------------------------------------
+// Kinds — the three semantic kinds (design §3). `kind` is data, not a fork.
+// ---------------------------------------------------------------------------
+export const KINDS = ['skill', 'reference', 'preference'];
+/** Is `v` one of the three 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 kind→default-rungs table (design §9). When an author omits a visibility
+// field, its default is a function of `kind` — chosen so the common case is
+// correct with no thought and the migration is behavior-preserving for skills
+// and preferences. One data row per kind, NOT a code fork.
+//
+//   kind         system-prompt-visibility   file-read-visibility
+//   skill        name                       none
+//   preference   preview                    none
+//   reference    none                       preview
+// ---------------------------------------------------------------------------
+export const KIND_DEFAULT_RUNGS = {
+    skill: { systemPrompt: 'name', fileRead: 'none' },
+    preference: { systemPrompt: 'preview', fileRead: 'none' },
+    reference: { systemPrompt: 'none', fileRead: 'preview' },
+};
+// ---------------------------------------------------------------------------
+// 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 or defaulted. Tolerant of every other
+ *  imperfection (missing `when`/`why` default to '', a bad rung falls back to
+ *  the kind default), so a renderer mapping over many docs never throws. */
+export function parseSubstrateFrontmatter(fm) {
+    if (fm === null)
+        return null;
+    if (!isDocKind(fm.kind))
+        return null;
+    const kind = fm.kind;
+    const defaults = KIND_DEFAULT_RUNGS[kind];
+    return {
+        kind,
+        when: strField(fm.when),
+        why: strField(fm.why),
+        shortForm: strField(fm['short-form']),
+        systemPromptVisibility: parseRung(fm['system-prompt-visibility'], defaults.systemPrompt),
+        fileReadVisibility: parseRung(fm['file-read-visibility'], defaults.fileRead),
+        gate: parseGate(fm.gate),
+        appliesTo: parseAppliesTo(fm['applies-to']),
+    };
+}
+/** 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 generated `preview`-rung routing line (design §4), composed from the two
+ *  required prose fields and the kind: `"{when}, read this {kind}. {why}."`.
+ *  Both boot and on-read render render this identical line, so it lives once
+ *  here to prevent drift. Light cleanup avoids doubled punctuation. */
+export function previewLine(doc) {
+    const when = doc.when.trim().replace(/[.,]+$/, '');
+    const why = doc.why.trim().replace(/\.+$/, '');
+    return `${when}, read this ${doc.kind}. ${why}.`;
+}
+// ---------------------------------------------------------------------------
+// Field coercion helpers (private).
+// ---------------------------------------------------------------------------
+function strField(v) {
+    return typeof v === 'string' ? v : '';
+}
+/** Resolve a visibility field to a ladder rung, falling back to the kind
+ *  default 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,30 @@
+import type { MemoryDoc } from '../memory-resolver.js';
+import type { SubstrateDoc } from './schema.js';
+type ListAllMemoryDocsFn = () => MemoryDoc[];
+type ParseSubstrateDocFn = (doc: MemoryDoc) => SubstrateDoc | null;
+type ListAllPluginsFn = () => {
+    name: string;
+    manifest: {
+        description?: string;
+    };
+}[];
+type AssembleNodeSubjectFn = (id: string) => import('./subject.js').NodeConfigSubject | 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;
+/** 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[];
+/** listAllPlugins() result, cached per session. */
+export declare function cachedAllPlugins(listFn: ListAllPluginsFn): {
+    name: string;
+    manifest: {
+        description?: string;
+    };
+}[];
+/** assembleNodeSubject(nodeId), cached per (session × nodeId). */
+export declare function cachedNodeSubject(nodeId: string, assembleFn: AssembleNodeSubjectFn): import('./subject.js').NodeConfigSubject | null;
+export {};

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

@@ -0,0 +1,77 @@
+// 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:
+//   • allMemoryDocs    — the full listAllMemoryDocs() corpus (parsed MemoryDocs,
+//                        already YAML-parsed by the resolver).  Shared by both
+//                        render.ts and on-read.ts so each session call site only
+//                        pays the filesystem walk+parse ONCE.
+//   • substrateDocs    — allMemoryDocs mapped through parseSubstrateDoc and
+//                        null-filtered.  Used by render.ts's resolverDocs and
+//                        on-read.ts's appliesToCandidates.
+//   • allPlugins       — listAllPlugins() result.  renderSkillCatalog was calling
+//                        listAllPlugins() twice per turn (once via listAllSkills,
+//                        once directly for descriptions).
+//   • nodeSubjects     — assembleNodeSubject() result keyed by nodeId.  The three
+//                        boot-render functions each call it; caching avoids the
+//                        meta.json read + sqlite spine-walk happening 2-3x per turn.
+const _cache = {
+    allMemoryDocs: null,
+    substrateDocs: null,
+    allPlugins: null,
+    nodeSubjects: new Map(),
+};
+/** 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.allMemoryDocs = null;
+    _cache.substrateDocs = null;
+    _cache.allPlugins = null;
+    _cache.nodeSubjects.clear();
+}
+/** 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) {
+        _cache.allMemoryDocs = listFn();
+    }
+    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;
+}
+/** listAllPlugins() result, cached per session. */
+export function cachedAllPlugins(listFn) {
+    if (_cache.allPlugins === null) {
+        _cache.allPlugins = listFn();
+    }
+    return _cache.allPlugins;
+}
+/** assembleNodeSubject(nodeId), cached per (session × nodeId). */
+export function cachedNodeSubject(nodeId, assembleFn) {
+    if (!_cache.nodeSubjects.has(nodeId)) {
+        _cache.nodeSubjects.set(nodeId, assembleFn(nodeId));
+    }
+    return _cache.nodeSubjects.get(nodeId) ?? null;
+}

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

@@ -0,0 +1,41 @@
+import { type Mode, type Lifecycle } from '../canvas/index.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;
+    };
+}
+/** 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';
+/** 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 two
+ *  derived fields. Returns `null` when the node has no canvas-db row (an
+ *  unknown id). Pure aside from the canvas-db reads. */
+export declare function assembleNodeSubject(nodeId: string): NodeConfigSubject | null;

package/dist/core/substrate/subject.js

@@ -0,0 +1,54 @@
+// subject.ts — the node-config SUBJECT a document's `gate` predicate is
+// evaluated against. Assembled per node from its canvas-db `NodeMeta` plus two
+// DERIVED fields: `scope` (the scope.ts resolution for the node's cwd) and
+// `orchestration.depth` (the node's spine distance to its root orchestrator).
+// See design-substrate.md §4 + plan-substrate.md §2. Reads canvas-db; otherwise
+// a thin, pure assembler.
+import { getNode, getRow } from '../canvas/index.js';
+import { projectScopeRoot } from '../scope.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';
+}
+/** 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 two
+ *  derived fields. Returns `null` when the node has no canvas-db row (an
+ *  unknown id). Pure aside from the canvas-db 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) },
+    };
+}