@north-light/crouter 0.3.236 → 0.3.237

package/dist/core/substrate/on-read.js

@@ -33,20 +33,20 @@
 // renders at the highest rung matched by that event.
 //
 // Equal-canonical candidates (the same identity in two physical stores) do not
-// each deliver: `selectEventCandidates` collapses them to the first one
-// ELIGIBLE for that event, in source order.
-import { homedir } from 'node:os';
-import { dirname, parse, sep } from 'node:path';
-import { readText, realpathOrSelf } from '../fs-utils.js';
-import { parseFrontmatterGeneric } from '../frontmatter.js';
-import { listAllMemoryDocs, listProjectMemoryDocs, loadStoreMemoryDocs, openProjectMemoryStore } from '../memory-resolver.js';
-import { userScopeRoot } from '../scope.js';
-import { gatePasses } from './gate.js';
-import { commandDeliveryRung, memoryReadDeliveryRung, owningRootOf, preCommandDeliveryRung, readDeliveryRung, workspaceOpenRung } from './surface-match.js';
+// each deliver: the plan collapses them to the first one ELIGIBLE for that
+// event, in corpus order.
+//
+// Every selection decision — discovery, gates, the profile cap, the rung fold,
+// the first-wins collapse — belongs to planDelivery (plan.ts). This module is
+// the plan→text adapter: it owns the `<memory>` envelope, the
+// `<auto-loaded-context>` wrapper, and the exposure ledger.
+import { sep } from 'node:path';
+import { ambientMemoryTarget, listAllMemoryDocs } from '../memory-resolver.js';
+import { owningRootOf } from './surface-match.js';
 import { demoteDocumentTranscriptExposure, documentExposedAtOrAbove, emptyContextExposureState, exposureTarget, registerDocumentExposure, } from './injected-store.js';
-import { minRung, parseSubstrateDoc, previewLine } from './schema.js';
+import { planDelivery } from './plan.js';
+import { parseSubstrateDoc, previewLine } from './schema.js';
 import { cachedEventCorpusInclusive } from './session-cache.js';
-const JUNK_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache', '.yalc']);
 function attr(s) {
     return s
         .replace(/&/g, '&amp;')
@@ -54,48 +54,11 @@ function attr(s) {
         .replace(/</g, '&lt;')
         .replace(/>/g, '&gt;');
 }
-function isJunkAncestor(dir) {
-    return dir.split(sep).some((segment) => JUNK_DIRS.has(segment));
-}
-/** Project docs from every workspace store enclosing the read file, nearest
- * first. This is a discovery walk only: each returned doc must still match an
- * explicit trigger. A store that declares no namespace does not mount here
- * either — an unmounted store has no canonical identities to deliver under.
- * The stores carry the neutral ceiling: the read event is uncapped by design,
- * reached only by an explicit file read. */
-function enclosingProjectDocs(absReadFile) {
-    const out = [];
-    const seen = new Set();
-    const home = realpathOrSelf(homedir());
-    const userRoot = realpathOrSelf(userScopeRoot());
-    const fsRoot = parse(absReadFile).root;
-    let dir = dirname(absReadFile);
-    while (true) {
-        if (dir !== home && dir !== userRoot && !isJunkAncestor(dir)) {
-            const store = openProjectMemoryStore(dir);
-            if (store.mountStatus === 'ready' && !seen.has(store.storeRoot)) {
-                seen.add(store.storeRoot);
-                for (const source of loadStoreMemoryDocs(store, true)) {
-                    const doc = parseSubstrateDoc(source);
-                    if (doc !== null)
-                        out.push({ doc, source });
-                }
-            }
-        }
-        if (dir === home || dir === fsRoot)
-            break;
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return out;
-}
 // The event corpus INCLUDES node-scope docs: surfaces entries are explicit
 // authored routing, so a node-local doc's read/memory-read/command entry
-// fires like any other store's. Only boot excludes node scope (render.ts's
-// nodeLocalDocs owns node-local boot rendering); the active exposure state
-// prevents a lower-rung repeat here.
+// fires like any other store's. Only boot excludes node scope (render.ts owns
+// node-local boot rendering); the active exposure state prevents a lower-rung
+// repeat here.
 function resolvedDocs() {
     try {
         return cachedEventCorpusInclusive(listAllMemoryDocs, parseSubstrateDoc);
@@ -104,16 +67,6 @@ function resolvedDocs() {
         return [];
     }
 }
-function readFileFrontmatter(absReadFile) {
-    if (!/\.(md|mdx|markdown)$/i.test(absReadFile))
-        return {};
-    try {
-        return parseFrontmatterGeneric(readText(absReadFile)).data ?? {};
-    }
-    catch {
-        return {};
-    }
-}
 // Two shapes: element-with-body means the content is here; self-closing means
 // it is not — a preview carries its routing line as `readWhen` metadata so the
 // one-liner can never be mistaken for the document's content. No disk path:
@@ -135,37 +88,14 @@ function renderDocEnvelope(doc, rung) {
     }
     return `<memory ${attrs} />`;
 }
-/** The eligible candidate per canonical identity, in the caller's SOURCE order.
- * Kind and mount are settled by the loader and the profile cap by the caller's
- * rung fold, so what remains is the document gate over candidates the event
- * already gave a delivering rung. A nearer candidate that is gated off or does
- * not deliver never suppresses a farther one — the filter runs before the
- * first-wins collapse, not after it.
- *
- * A `null` subject skips gated documents and still delivers ungated ones. */
-function selectEventCandidates(subject, candidates) {
-    const selected = [];
-    const seen = new Set();
-    for (const candidate of candidates) {
-        const { doc, rung } = candidate;
-        if (rung === 'none' || seen.has(doc.name))
-            continue;
-        try {
-            if (subject === null ? doc.gate !== undefined : !gatePasses(doc, subject))
-                continue;
-        }
-        catch {
-            continue;
-        }
-        seen.add(doc.name);
-        selected.push(candidate);
-    }
-    return selected;
+/** One winner per doc, in plan (precedence) order. */
+function planWinners(plan) {
+    return plan.docs.filter((r) => r.winner).map((r) => ({ doc: r.doc, rung: r.finalRung }));
 }
-/** Render the selected candidates not already loaded at their matched rung. */
-export function renderCandidateBlocks(subject, candidates, target) {
+/** Render the plan's winners that are not already loaded at their matched rung. */
+function renderWinnerBlocks(winners, target) {
     const rendered = [];
-    for (const { doc, rung } of selectEventCandidates(subject, candidates)) {
+    for (const { doc, rung } of winners) {
         if (documentExposedAtOrAbove(target.state, doc.path, doc.body, rung))
             continue;
         const block = renderDocEnvelope(doc, rung);
@@ -179,23 +109,19 @@ export function renderCandidateBlocks(subject, candidates, target) {
 function transientTranscriptTarget() {
     return exposureTarget(emptyContextExposureState(), 'transcript');
 }
-function renderCandidates(subject, candidates, target) {
-    const rendered = renderCandidateBlocks(subject, candidates, target);
-    return rendered.length === 0
-        ? ''
-        : `<auto-loaded-context>\n${rendered.join('\n')}\n</auto-loaded-context>`;
+function wrapAutoLoaded(blocks) {
+    return blocks.length === 0 ? '' : `<auto-loaded-context>\n${blocks.join('\n')}\n</auto-loaded-context>`;
+}
+/** The corpus-carrying plan for one event. Every renderer here passes the
+ *  session-cached corpus so a hook never re-walks the filesystem. */
+function eventPlan(subject, event, payload) {
+    return planDelivery(subject, ambientMemoryTarget(), event, payload, resolvedDocs());
 }
 /** Surface docs whose `read` entries match a successfully read file, using
  * the caller-supplied daemon snapshot subject. */
 export function renderOnReadDocsForSubject(subject, readFilePath, target = transientTranscriptTarget()) {
-    const absReadFile = realpathOrSelf(readFilePath);
-    const readFrontmatter = readFileFrontmatter(absReadFile);
-    // Enclosing stores lead: a store discovered from the read file is the nearest
-    // source of an identity the mounted corpus may also carry.
-    const candidates = [...enclosingProjectDocs(absReadFile), ...resolvedDocs()]
-        .filter(({ doc }) => realpathOrSelf(doc.path) !== absReadFile)
-        .map(({ doc }) => ({ doc, rung: readDeliveryRung(doc, subject, absReadFile, readFrontmatter) }));
-    return renderCandidates(subject, candidates, target);
+    const plan = eventPlan(subject, 'read', { absoluteFile: readFilePath });
+    return wrapAutoLoaded(renderWinnerBlocks(planWinners(plan), target));
 }
 /** Workspace boot docs using the snapshot's cwd/profile instead of a canvas
  * lookup. The shared exposure target prevents a later read from repeating a
@@ -206,25 +132,24 @@ export function renderOnReadDocsForSubject(subject, readFilePath, target = trans
  * registration. A later explicit `crtr memory read` can still raise a document
  * that workspace-open disclosed at a lower rung. */
 export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, target = transientTranscriptTarget()) {
-    let docs;
+    const workspaceTarget = { cwd, profileId, nodeId: null };
+    let winners;
     try {
-        docs = listProjectMemoryDocs(cwd, profileId)
-            .map(parseSubstrateDoc)
-            .filter((doc) => doc !== null);
+        winners = planWinners(planDelivery(subject, workspaceTarget, 'workspace-open'));
     }
     catch {
         return '';
     }
-    // Selection runs on the corpus's SOURCE order, so the nearest store wins an
-    // equal-canonical tie; the sort below is display order only — outermost
-    // workspace first, so context arrives general before specific.
-    const ordered = selectEventCandidates(subject, docs.map((doc) => ({ doc, rung: minRung(workspaceOpenRung(doc, subject), doc.projectMemory) }))).sort((a, b) => {
+    // Selection ran on the corpus's PRECEDENCE order, so the nearest store won an
+    // equal-canonical tie; this sort is display order only — outermost workspace
+    // first, so context arrives general before specific.
+    winners.sort((a, b) => {
         const aRoot = owningRootOf(a.doc) ?? '';
         const bRoot = owningRootOf(b.doc) ?? '';
         const depth = aRoot.split(sep).filter(Boolean).length - bRoot.split(sep).filter(Boolean).length;
         return depth || aRoot.localeCompare(bRoot) || a.doc.path.localeCompare(b.doc.path);
     });
-    return renderCandidates(subject, ordered, target);
+    return wrapAutoLoaded(renderWinnerBlocks(winners, target));
 }
 /** Inner `<memory>` blocks for the memory-read event: docs whose
  * `memory-read` entries match the doc a `crtr memory read` just resolved
@@ -233,20 +158,17 @@ export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, targe
  * unwrapped blocks — the read leaf composes one `<auto-loaded-context>`
  * envelope from these plus the directory listings. */
 export function memoryReadDocBlocks(subject, excludeRealpath, name, target) {
-    const candidates = resolvedDocs()
-        .filter(({ doc }) => realpathOrSelf(doc.path) !== excludeRealpath)
-        .map(({ doc, source }) => ({
-        doc,
-        rung: memoryReadDeliveryRung(doc, source.routingAnchor, subject, name),
-    }));
-    return renderCandidateBlocks(subject, candidates, target);
+    const plan = eventPlan(subject, 'memory-read', {
+        resolvedCanonicalName: name,
+        resolvedDocPath: excludeRealpath,
+    });
+    return renderWinnerBlocks(planWinners(plan), target);
 }
 /** Surface docs whose `command` entries match an executed bash command.
  * The corpus is the resolved cwd/profile set; a command has no file from which
  * to discover enclosing project stores. */
 export function renderOnCommandDocsForSubject(subject, command, target = transientTranscriptTarget()) {
-    const candidates = resolvedDocs().map(({ doc }) => ({ doc, rung: commandDeliveryRung(doc, subject, command) }));
-    return renderCandidates(subject, candidates, target);
+    return wrapAutoLoaded(renderWinnerBlocks(planWinners(eventPlan(subject, 'command', { command })), target));
 }
 /** Surface docs whose `pre-command` entries match a bash command that has NOT
  * run yet. The exact twin of the post-execution renderer above, and its empty
@@ -254,8 +176,7 @@ export function renderOnCommandDocsForSubject(subject, command, target = transie
  * its matching rung or above, which is the release — the caller lets the
  * command through. */
 export function renderPreCommandDocsForSubject(subject, command, target = transientTranscriptTarget()) {
-    const candidates = resolvedDocs().map(({ doc }) => ({ doc, rung: preCommandDeliveryRung(doc, subject, command) }));
-    return renderCandidates(subject, candidates, target);
+    return wrapAutoLoaded(renderWinnerBlocks(planWinners(eventPlan(subject, 'pre-command', { command })), target));
 }
 function carriesPreCommandEntry(doc) {
     return doc.surfaces.some((entry) => entry.on === 'pre-command');

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

@@ -0,0 +1,94 @@
+import { type MemoryDoc, type MemoryScope, type MemoryTarget } from '../memory-resolver.js';
+import { type DocKind, type Rung, type SubstrateDoc, type SurfaceEntry, type SurfaceEvent } from './schema.js';
+import type { EventCorpusDoc } from './session-cache.js';
+import type { NodeConfigSubject } from './subject-fields.js';
+/** What the event exposes to match against. Every field is optional: an event
+ *  invoked without its payload matches nothing rather than throwing. */
+export interface DeliveryPayload {
+    /** `read`: the file that was read. Realpathed by the planner. */
+    absoluteFile?: string;
+    /** `read`: the read file's own frontmatter. Parsed from the file when omitted. */
+    readFrontmatter?: Record<string, unknown>;
+    /** `memory-read`: the exact canonical name the read resolved to. */
+    resolvedCanonicalName?: string;
+    /** `memory-read`: realpath of the resolved document, which never delivers to
+     *  itself. */
+    resolvedDocPath?: string;
+    /** `command` / `pre-command`: the command string. */
+    command?: string;
+}
+/** A gate verdict with the reason a failure carries. */
+export type GateOutcome = {
+    pass: true;
+} | {
+    pass: false;
+    reason: string;
+};
+/** One authored surface entry of this event and how it fared. `matched` folds
+ *  the entry's constraints AND its own gate; `gate` isolates the gate so a
+ *  reader can tell "did not fit" from "excluded by this node's config". */
+export interface EntryDecision {
+    entry: SurfaceEntry;
+    matched: boolean;
+    gate: GateOutcome;
+}
+/** One document's delivery decision for one event. */
+export interface DeliveryRecord {
+    /** Canonical name — the identity dedup resolves. */
+    name: string;
+    kind: DocKind;
+    scope: MemoryScope;
+    /** Absolute path to the document file. */
+    storePath: string;
+    /** From the node's own store, which is floored rather than capped at boot. */
+    nodeLocal: boolean;
+    /** Every entry the document authored for this event. */
+    authoredEntries: EntryDecision[];
+    /** The highest-rung entry that matched, or null when none did. */
+    matchedEntry: SurfaceEntry | null;
+    /** The matched entry's rung — what the author asked for, before the cap. */
+    authoredRung: Rung;
+    /** The profile relationship's cap on this document's store, or null when the
+     *  event is uncapped or the document is node-local. */
+    projectMemoryCap: Rung | null;
+    /** `minRung(authoredRung, projectMemoryCap)`. */
+    cappedRung: Rung;
+    docGate: GateOutcome;
+    /** The matched entry's gate, or the verdict that excluded every authored
+     *  entry; null when the document authored no entry for this event. */
+    entryGate: GateOutcome | null;
+    /** What this document delivers at after gates, cap, and the boot node-local
+     *  floor. `none` = delivers nothing. */
+    finalRung: Rung;
+    /** This document is the one its canonical name resolves to for this event. */
+    winner: boolean;
+    /** The document that took this one's name, when it lost the dedup. */
+    shadowedBy: {
+        name: string;
+        scope: MemoryScope;
+        path: string;
+    } | null;
+    /** The parsed document — the renderers' input. */
+    doc: SubstrateDoc;
+    /** The resolver descriptor behind it: physical path, representation, and the
+     *  routing anchor a `./` memory-read glob matches against. */
+    source: MemoryDoc;
+}
+/** Every document considered for one event, in corpus (precedence) order. */
+export interface DeliveryPlan {
+    event: SurfaceEvent;
+    subject: NodeConfigSubject | null;
+    target: MemoryTarget;
+    docs: DeliveryRecord[];
+}
+/** Which boot block a record belongs to. The node's own store is the catch-all
+ *  this-node store and rides into the knowledge block whatever its kind, so a
+ *  record's kind alone does not answer this. */
+export declare function bootPartitionOf(record: Pick<DeliveryRecord, 'kind' | 'nodeLocal'>): DocKind;
+/** Plan one event's delivery.
+ *
+ *  `corpus` is the already-loaded document set. The live renderers pass their
+ *  session cache (the corpus is scanned and parsed once per session); an
+ *  inspection caller omits it and the planner loads the event's corpus from
+ *  `target`. Either way the planner writes nothing. */
+export declare function planDelivery(subject: NodeConfigSubject | null, target: MemoryTarget, event: SurfaceEvent, payload?: DeliveryPayload, corpus?: readonly EventCorpusDoc[]): DeliveryPlan;

package/dist/core/substrate/plan.js

@@ -0,0 +1,266 @@
+// plan.ts — the pure delivery planner: for one (subject, target, event,
+// payload) tuple it computes the structured per-document delivery decision the
+// renderers turn into text and the inspection commands print as a table. It
+// renders nothing and touches no exposure state.
+//
+// The pipeline has two halves and this module is the UPSTREAM one:
+//
+//   planDelivery (subject,event -> decisions) -> exposure ledger dedup ->
+//   render -> registerDocumentExposure
+//
+// The ledger (injected-store.ts) records what a live context has ALREADY been
+// given; the planner computes what a state WOULD be given. Renderers own the
+// downstream half, so a plan can be computed for a hypothetical subject without
+// disturbing any node's real ledger.
+//
+// Two decisions are event-specific and deliberately so:
+//
+//   • THE PROFILE CAP reaches boot and workspace-open only. Every other event
+//     is reached by an explicit act (a read, a command) and delivers at the
+//     authored rung.
+//   • DEDUP PARTICIPATION differs. At boot every ELIGIBLE document participates
+//     — including one with no boot entry, because the boot catalog counts it
+//     into its directory's `[+N more]` — and the dedup runs per boot partition,
+//     since the boot render emits an independent block per partition. At every
+//     other event only a document that actually DELIVERS participates, so a
+//     nearer document that does not match never suppresses a farther one that
+//     does.
+import { homedir } from 'node:os';
+import { dirname, parse, sep } from 'node:path';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+import { readText, realpathOrSelf } from '../fs-utils.js';
+import { listProjectMemoryDocs, loadMemoryTargetView, loadStoreMemoryDocs, openProjectMemoryStore, } from '../memory-resolver.js';
+import { userScopeRoot } from '../scope.js';
+import { gatePasses, surfaceEntryGatePasses } from './gate.js';
+import { minRung, parseSubstrateDoc, rungAtLeast, } from './schema.js';
+import { matchingSurfaceEntry, surfaceEntryParticipates } from './surface-match.js';
+/** Which boot block a record belongs to. The node's own store is the catch-all
+ *  this-node store and rides into the knowledge block whatever its kind, so a
+ *  record's kind alone does not answer this. */
+export function bootPartitionOf(record) {
+    return record.nodeLocal ? 'knowledge' : record.kind;
+}
+/** Plan one event's delivery.
+ *
+ *  `corpus` is the already-loaded document set. The live renderers pass their
+ *  session cache (the corpus is scanned and parsed once per session); an
+ *  inspection caller omits it and the planner loads the event's corpus from
+ *  `target`. Either way the planner writes nothing. */
+export function planDelivery(subject, target, event, payload = {}, corpus) {
+    const resolved = resolvePayload(event, payload);
+    const considered = considerFor(event, corpus ?? loadEventCorpus(target, event), resolved);
+    const docs = considered.map(({ doc, source }) => decide(doc, source, subject, event, resolved));
+    resolveWinners(event, docs);
+    return { event, subject, target, docs };
+}
+function resolvePayload(event, payload) {
+    if (event !== 'read' || payload.absoluteFile === undefined) {
+        return { ...payload, readFrontmatter: payload.readFrontmatter ?? {} };
+    }
+    const absoluteFile = realpathOrSelf(payload.absoluteFile);
+    return {
+        ...payload,
+        absoluteFile,
+        readFrontmatter: payload.readFrontmatter ?? readFileFrontmatter(absoluteFile),
+    };
+}
+function readFileFrontmatter(absReadFile) {
+    if (!/\.(md|mdx|markdown)$/i.test(absReadFile))
+        return {};
+    try {
+        return parseFrontmatterGeneric(readText(absReadFile)).data ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+// The considered set — the corpus plus the event's own discovery and
+// self-exclusion rules.
+function considerFor(event, corpus, payload) {
+    if (event === 'read') {
+        const abs = payload.absoluteFile;
+        if (abs === undefined)
+            return [...corpus];
+        // Enclosing stores lead: a store discovered from the read file is the
+        // nearest source of an identity the mounted corpus may also carry.
+        return [...enclosingProjectDocs(abs), ...corpus].filter(({ doc }) => realpathOrSelf(doc.path) !== abs);
+    }
+    if (event === 'memory-read' && payload.resolvedDocPath !== undefined) {
+        const exclude = payload.resolvedDocPath;
+        return corpus.filter(({ doc }) => realpathOrSelf(doc.path) !== exclude);
+    }
+    return [...corpus];
+}
+const JUNK_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache', '.yalc']);
+function isJunkAncestor(dir) {
+    return dir.split(sep).some((segment) => JUNK_DIRS.has(segment));
+}
+/** Project docs from every workspace store enclosing the read file, nearest
+ *  first. This is a discovery walk only: each returned doc must still match an
+ *  explicit trigger. A store that declares no namespace does not mount here
+ *  either — an unmounted store has no canonical identities to deliver under.
+ *  The stores carry the neutral ceiling: the read event is uncapped by design,
+ *  reached only by an explicit file read. */
+function enclosingProjectDocs(absReadFile) {
+    const out = [];
+    const seen = new Set();
+    const home = realpathOrSelf(homedir());
+    const userRoot = realpathOrSelf(userScopeRoot());
+    const fsRoot = parse(absReadFile).root;
+    let dir = dirname(absReadFile);
+    while (true) {
+        if (dir !== home && dir !== userRoot && !isJunkAncestor(dir)) {
+            const store = openProjectMemoryStore(dir);
+            if (store.mountStatus === 'ready' && !seen.has(store.storeRoot)) {
+                seen.add(store.storeRoot);
+                for (const source of loadStoreMemoryDocs(store, true)) {
+                    const doc = parseSubstrateDoc(source);
+                    if (doc !== null)
+                        out.push({ doc, source });
+                }
+            }
+        }
+        if (dir === home || dir === fsRoot)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return out;
+}
+/** The event's corpus for a target, for callers that hold no session cache.
+ *  Boot orders node-local docs LAST so a resolver document keeps its identity
+ *  against a same-named node-local one; workspace-open sees project stores
+ *  only; every other event sees the whole mounted corpus. */
+function loadEventCorpus(target, event) {
+    const sources = event === 'workspace-open'
+        ? listProjectMemoryDocs(target.cwd, target.profileId)
+        : loadMemoryTargetView(target, { quiet: true }).docs;
+    const parsed = [];
+    for (const source of sources) {
+        const doc = parseSubstrateDoc(source);
+        if (doc !== null)
+            parsed.push({ doc, source });
+    }
+    if (event !== 'boot')
+        return parsed;
+    return [
+        ...parsed.filter((e) => e.doc.scope !== 'node'),
+        ...parsed.filter((e) => e.doc.scope === 'node'),
+    ];
+}
+// The per-document decision.
+function decide(doc, source, subject, event, payload) {
+    const match = {
+        absoluteFile: payload.absoluteFile,
+        readFrontmatter: payload.readFrontmatter,
+        resolvedCanonicalName: payload.resolvedCanonicalName,
+        routingAnchor: source.routingAnchor,
+        command: payload.command,
+    };
+    const docGate = documentGateOutcome(doc, subject);
+    const authoredEntries = doc.surfaces
+        .filter((entry) => entry.on === event)
+        .map((entry) => ({
+        entry,
+        matched: surfaceEntryParticipates(entry, doc, subject, event, match),
+        gate: entryGateOutcome(entry, subject),
+    }));
+    const matchedEntry = matchingSurfaceEntry(doc, subject, event, match);
+    const authoredRung = matchedEntry?.at ?? 'none';
+    const nodeLocal = doc.scope === 'node';
+    const capped = event === 'boot' || event === 'workspace-open';
+    const projectMemoryCap = capped && !nodeLocal ? doc.projectMemory : null;
+    const cappedRung = projectMemoryCap === null ? authoredRung : minRung(authoredRung, projectMemoryCap);
+    let finalRung = docGate.pass ? cappedRung : 'none';
+    // The one rung FLOOR, scoped to the node store at boot: a node-local doc with
+    // no boot entry still shows its bare name rather than collapsing into its
+    // directory's hidden count. A node-local doc whose boot entries all fail
+    // stays absent.
+    if (event === 'boot' &&
+        nodeLocal &&
+        docGate.pass &&
+        !rungAtLeast(finalRung, 'name') &&
+        !doc.surfaces.some((entry) => entry.on === 'boot')) {
+        finalRung = 'name';
+    }
+    return {
+        name: doc.name,
+        kind: doc.kind,
+        scope: doc.scope,
+        storePath: doc.path,
+        nodeLocal,
+        authoredEntries,
+        matchedEntry,
+        authoredRung,
+        projectMemoryCap,
+        cappedRung,
+        docGate,
+        entryGate: recordEntryGate(authoredEntries, matchedEntry),
+        finalRung,
+        winner: false,
+        shadowedBy: null,
+        doc,
+        source,
+    };
+}
+/** A missing subject cannot satisfy a gate, so a gated document is skipped and
+ *  an ungated one still delivers. A predicate that throws excludes only its own
+ *  document — never the whole render. */
+function documentGateOutcome(doc, subject) {
+    if (doc.gate === undefined)
+        return { pass: true };
+    if (subject === null)
+        return { pass: false, reason: 'gated document with no node config to match' };
+    try {
+        return gatePasses(doc, subject)
+            ? { pass: true }
+            : { pass: false, reason: 'document gate does not match this node config' };
+    }
+    catch (err) {
+        return { pass: false, reason: `document gate failed to evaluate: ${String(err)}` };
+    }
+}
+function entryGateOutcome(entry, subject) {
+    if (entry.gate === undefined)
+        return { pass: true };
+    return surfaceEntryGatePasses(entry, subject)
+        ? { pass: true }
+        : { pass: false, reason: 'entry gate does not match this node config' };
+}
+function recordEntryGate(entries, matched) {
+    if (entries.length === 0)
+        return null;
+    if (matched !== null)
+        return { pass: true };
+    const gatedOut = entries.find((e) => !e.gate.pass);
+    return gatedOut === undefined ? { pass: true } : gatedOut.gate;
+}
+// Winner resolution — first-win by canonical name over the corpus's precedence
+// order, within the event's participating set.
+function participates(record, event) {
+    if (!record.docGate.pass)
+        return false;
+    // Boot counts an eligible document even when it delivers nothing, because the
+    // catalog tree still counts it. A `none` cap removes the document from the
+    // corpus entirely, so it cannot shadow a wider-scope document either.
+    if (event === 'boot')
+        return record.projectMemoryCap !== 'none';
+    return rungAtLeast(record.finalRung, 'name');
+}
+function resolveWinners(event, docs) {
+    const winners = new Map();
+    for (const record of docs) {
+        if (!participates(record, event))
+            continue;
+        const key = event === 'boot' ? `${bootPartitionOf(record)}:${record.name}` : record.name;
+        const held = winners.get(key);
+        if (held === undefined) {
+            winners.set(key, record);
+            record.winner = true;
+            continue;
+        }
+        record.shadowedBy = { name: held.name, scope: held.scope, path: held.storePath };
+    }
+}

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

@@ -4,7 +4,7 @@ import type { NodeConfigSubject } from './subject-fields.js';
 /** The computed "sub-personas you may spawn" menu for a subject's kind — the
  *  live restoration of the old `personas/resolve.ts` static menu, now derived
  *  at render time from the merged kind registry (`subKindsAvailableTo`) so it
- *  can never drift from `sys prompt-review --list`'s `subPersonas` metadata.
+ *  can never drift from `sys context prompt-review --list`'s `subPersonas` metadata.
  *  Returns '' when the kind has zero available sub-kinds (no dangling empty
  *  header). Emitted for BOTH base and orchestrator modes per the CTO's ruling —
  *  mode is irrelevant to which sub-kinds are spawnable. */
@@ -20,11 +20,10 @@ export declare function renderPreferencesForSubject(subject: NodeConfigSubject |
  *  doc PLUS the node-local memory docs (any kind) — resolver docs win
  *  first-wins dedup over a same-named node-local doc. GROUPED by rung exactly
  *  like the preference block: content prose first (general→specific,
- *  node-local last), then the preview/name catalog tree. Node-local docs are
- *  floored HERE — a bootless node-local doc's rung is bumped to `name` before
- *  grouping, so it still surfaces as a bare-name tree entry rather than
- *  collapsing into a `[+N more]` count (its body still never renders: floored
- *  docs never reach the `content` rung). Procedural guidance and factual
+ *  node-local last), then the preview/name catalog tree. A bootless node-local
+ *  doc arrives floored to `name`, so it surfaces as a bare-name tree entry
+ *  rather than collapsing into a `[+N more]` count (its body still never
+ *  renders: floored docs never reach the `content` rung). Procedural guidance and factual
  *  references both live here as `knowledge`. Returns '' when nothing is
  *  eligible. */
 export declare function renderKnowledgeForSubject(subject: NodeConfigSubject, nodeId: string, target?: ExposureTarget): string;