@north-light/crouter 0.3.227 → 0.3.228

package/dist/core/substrate/render.js

@@ -1,4 +1,5 @@
-// render.ts — the pure boot-render functions for the document substrate.
+// render.ts — the pure render functions for the document substrate: two boot
+// targets plus the config-change delta.
 //
 // Two boot targets, one shape per kind: each kind renders as ONE wrapped block —
 // intro prose → GROUPED content → an update directive. The render is grouped
@@ -6,12 +7,13 @@
 // clean prose bodies (verbatim, no tree chrome, no name label — this is what
 // makes content-rung the persona-prose mechanism), in general→specific order;
 // then the `preview`+`name` docs render as ONE catalog tree, each at its own
-// rung (preview → a `# read when:` routing line; name → a bare entry); a doc
-// with NO boot entry leaks only into its dir's `[+N more]` count, never a
-// name — EXCEPT a node-local doc with no boot entry: renderKnowledgeForSubject
-// floors it up to `name` so it still shows its bare name rather than
-// collapsing into a hidden count. A node-local doc with boot entries remains
-// absent when none of those entries participates.
+// rung (preview → a `# read when:` routing line; name → a bare entry), a
+// directory that carries its own document rendering that entry on the
+// directory's own row; a doc with NO boot entry leaks only into its dir's
+// `[+N more]` count, never a name — EXCEPT a node-store doc with no boot entry:
+// renderKnowledgeForSubject floors it up to `name` so it still shows its bare
+// name rather than collapsing into a hidden count. A node-store doc with boot
+// entries remains absent when none of those entries participates.
 //
 //   • the SYSTEM-PROMPT half — `<memory kind="preference">`
 //     (renderPreferencesSection) — the always-present memory-usage guidance plus
@@ -20,51 +22,59 @@
 //     `\n\nGuidelines:` anchor;
 //   • the first-message half — `<memory kind="knowledge">`
 //     (renderKnowledgeBlock) — the consultable catalog (every `kind: knowledge`
-//     doc ∪ node-local) the string bearings.ts embeds in the session_start
+//     doc ∪ the node's own store) the string bearings.ts embeds in the session_start
 //     message as a SIBLING of `<crtr-bearings>` (never nested under the context
 //     dir — the catalog spans all scopes and belongs to no one directory).
 //
+// renderConfigChangeDelta runs the same winner assemblies after a configuration
+// change and appends only identities newly visible or raised above the active
+// context rank. It never rewrites the frozen system snapshot.
+//
 // The pipeline is explicitly TWO-STEP and must never run in the other order:
 //   1. SELECT WINNERS — MemoryDoc → parseSubstrateDoc → (null-filter
 //      non-substrate) → per-doc boot rung (`bootRung`, the max `at` over
 //      participating `on: boot` surfaces entries) → gatePasses → first-wins DEDUP by
 //      name over the resolver's precedence order (nearest project > user >
-//      builtin). Node-local docs follow the same gate rule, but the
-//      knowledge-block render floors only a node-local doc with no boot entry to
-//      `name` — the one rung-floor exemption, scoped to the node-local store
-//      only.
+//      builtin). Node-store docs follow the same gate rule, but the
+//      knowledge-block render floors only a node-store doc with no boot entry to
+//      `name` — the one rung-floor exemption, scoped to the node store only.
 //   2. RENDER IN DISPLAY ORDER — split winners into content vs. the rest;
 //      order content general→specific (builtin, user, project outermost→
-//      nearest, node-local last) then by tree position then filename; place
+//      nearest, node store last) then by tree position then filename; place
 //      the rest into the catalog tree (position-ordered, as before).
 //   Sorting into display order BEFORE step 1's dedup would let a
 //   later-in-display-order builtin doc's array position mask a project/user
 //   override — dedup precedence and display order are deliberately different
 //   orderings and must not be conflated.
 //
-// Pure + defensive: reads the resolver, canvas-db (subject assembly), and the
-// node-local memory dir; performs no writes and no side effects beyond the
-// caller-supplied `seen` delivery map (write-only seeding — boot docs render
-// every session and are never skipped). A single malformed doc never throws
-// the whole render — parsing is isolated upstream (parseSubstrateDoc returns
-// null for a non-substrate doc; per-file node-local loads are wrapped), and
-// tree construction is pure string work.
-import { relative, sep } from 'node:path';
+// Pure + defensive: reads the resolver (the node's own store included) and
+// canvas-db (subject assembly); performs no writes and no side effects beyond
+// the caller-supplied exposure target. Baseline renders register their snapshot
+// source; transition renders query the active maximum and register transcript
+// deliveries. A single malformed doc never throws the whole render — the
+// resolver's loader isolates an unparseable file and parseSubstrateDoc returns
+// null for a non-substrate doc.
+//
+// STRUCTURE comes from the canonical directory tree (core/memory/tree.ts) and
+// ORDER from each descriptor's stored physical path, never from the canonical
+// name's segments: a project store's namespace has no physical counterpart and
+// an explicit `name:` detaches identity from the path. A directory that carries
+// its own document is ONE row — the document renders at its boot rung on the
+// directory's own line, with the directory's members nested beneath it.
+import { sep } from 'node:path';
 import { interpolateNodePaths } from '../canvas/paths.js';
-import { listAllMemoryDocs, resolveMemoryDoc } from '../memory-resolver.js';
+import { listAllMemoryDocs, loadMemoryTargetView, resolveMemoryDoc } from '../memory-resolver.js';
+import { buildMemoryTree } from '../memory/tree.js';
 import { subKindsAvailableTo } from '../config.js';
-import { parseFrontmatterGeneric } from '../frontmatter.js';
-import { pathExists, readText, realpathOrSelf, walkFiles } from '../fs-utils.js';
-import { memoryDir } from '../runtime/memory.js';
-import { NEUTRAL_PROJECT_MEMORY, projectScopeRoots } from '../scope.js';
+import { projectScopeRoots } from '../scope.js';
 import { gatePasses } from './gate.js';
 // De-barreled to LEAF modules on purpose: importing from './index.js' would
 // pull subject.js (canvas-db) transitively, re-tainting every CLI consumer of
 // the pure render fns. The canvas-db wrappers (renderPreferencesSection /
 // renderKnowledgeBlock) live in render-node.js instead.
-import { recordDelivery } from './injected-store.js';
-import { bootRung, minRung, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName, rungRank, } from './schema.js';
-import { cachedSubstrateDocs } from './session-cache.js';
+import { documentExposedAtOrAbove, registerDocumentExposure, } from './injected-store.js';
+import { bootRung, minRung, parseSubstrateDoc, previewLine, rungRank, } from './schema.js';
+import { cachedAllMemoryDocs, cachedSubstrateDocs } from './session-cache.js';
 /** First-wins dedup by (already-normalized) name, preserving the input's
  *  precedence order. The array's ORDER is the precedence signal — callers must
  *  pass docs already ordered highest-precedence-first; this function never
@@ -96,34 +106,54 @@ function dedupeFirstWins(docs) {
  *  surviving doc's authored boot rung is clamped to its cap before dedup, the
  *  session cache, and delivery seeding see it. */
 function selectWinners(subject, kind) {
-    let docs;
+    let corpus;
     try {
-        docs = cachedSubstrateDocs(listAllMemoryDocs, parseSubstrateDoc);
+        corpus = bootCorpus();
     }
     catch {
         return [];
     }
-    const eligible = docs
-        .filter((d) => d.kind === kind)
-        .filter((d) => d.projectMemory !== 'none')
-        .filter((d) => gatePasses(d, subject))
-        .map((d) => ({ ...d, bootRung: minRung(bootRung(d, subject), d.projectMemory) }));
+    const eligible = [];
+    for (const d of corpus.docs) {
+        if (d.kind !== kind || d.projectMemory === 'none' || !gatePasses(d, subject))
+            continue;
+        const source = corpus.sources.get(d.path);
+        if (source === undefined)
+            continue;
+        eligible.push({ ...d, source, bootRung: minRung(bootRung(d, subject), d.projectMemory) });
+    }
     return dedupeFirstWins(eligible);
 }
+const bootSources = new WeakMap();
+/** The session's boot corpus, each parsed doc joined back to its descriptor.
+ *  `cachedSubstrateDocs` is a filtered map of `cachedAllMemoryDocs`, and an
+ *  absolute path names exactly one document in a corpus (store roots are
+ *  realpath-deduped), so the path is the join key. The join is memoized per
+ *  cached array because one session renders preferences, knowledge, and any
+ *  config-change delta off the same corpus. */
+function bootCorpus() {
+    const docs = cachedSubstrateDocs(listAllMemoryDocs, parseSubstrateDoc);
+    let sources = bootSources.get(docs);
+    if (sources === undefined) {
+        sources = new Map(cachedAllMemoryDocs(listAllMemoryDocs).map((d) => [d.path, d]));
+        bootSources.set(docs, sources);
+    }
+    return { docs, sources };
+}
 // ---------------------------------------------------------------------------
-// Boot-delivery seeding — the injected-docs map grows at render time.
+// Exposure registration
 // ---------------------------------------------------------------------------
-/** Record every VISIBLY rendered winner into the caller's transcript dedup map
- *  at its displayed rung (write-only — boot renders every session and never
- *  skips). Seeding is what lets a later listing line or on-read injection skip
- *  a doc the boot catalog already discloses at that rank. */
-function seedBootDelivery(seen, docs) {
-    if (seen === undefined)
+function rendersAtBoot(doc) {
+    return isVisible(doc.bootRung) && (doc.bootRung !== 'content' || doc.body.trim() !== '');
+}
+/** Register every visibly rendered winner at its displayed rung. */
+function recordRendered(target, docs) {
+    if (target === undefined)
         return;
     for (const d of docs) {
-        if (!isVisible(d.bootRung))
+        if (!rendersAtBoot(d))
             continue;
-        recordDelivery(seen, realpathOrSelf(d.path), d.bootRung);
+        registerDocumentExposure(target, d.path, d.body, d.bootRung);
     }
 }
 // ---------------------------------------------------------------------------
@@ -133,14 +163,14 @@ function seedBootDelivery(seen, docs) {
  *  profile=2, project ranks start at 3 and climb by root nearness — the
  *  OUTERMOST ancestor `.crouter/` root ranks lowest (renders first), the
  *  NEAREST root ranks highest (renders last) — the mirror of the resolver's
- *  nearest-first dedup precedence. `isNodeLocal` docs rank last of all (the
- *  most specific, this-node-only store). This is display order ONLY — the
+ *  nearest-first dedup precedence. Node-scope docs rank last of all (the most
+ *  specific, this-node-only store). This is display order ONLY — the
  *  resolver's REPLACEMENT precedence (first-wins dedup, step 1) is the
  *  opposite direction for project/profile: project stack > profile > user >
  *  builtin, nearest project strongest; the two orderings are deliberately
  *  different (see the module comment). */
-function scopeGeneralityRank(doc, isNodeLocal) {
-    if (isNodeLocal)
+function scopeGeneralityRank(doc) {
+    if (doc.scope === 'node')
         return 1000;
     if (doc.scope === 'builtin')
         return 0;
@@ -155,18 +185,17 @@ function scopeGeneralityRank(doc, isNodeLocal) {
     const idx = nearFirstIdx === -1 ? 0 : nearFirstIdx;
     return 3 + (roots.length - 1 - idx); // outermost (largest idx) -> smallest rank
 }
-/** The doc's RAW physical path segments (numeric prefix intact), recovered
- *  from its absolute `path` using its (already-normalized) `name`'s segment
- *  COUNT — normalization strips a prefix from a segment but never merges or
- *  drops a segment, so the last N components of `path` are always the doc's
- *  physical segments. This is what lets `tree position` sort respect an
- *  author's `NN-` ordering pin even though the pin is invisible in `name`. */
+/** The doc's stored physical path segments, `NN-` ordering prefixes intact —
+ *  the descriptor's store-relative path, which is what lets `tree position`
+ *  sort respect an author's ordering pin even though the pin is invisible in
+ *  the canonical name. A directory document's `INDEX` filename names its
+ *  directory rather than a segment of its own, so it sorts AS its directory,
+ *  ahead of everything nested under it. */
 function physicalSegments(doc) {
-    const n = doc.name.split('/').length;
-    const raw = doc.path.split(sep).slice(-n);
-    if (raw.length > 0)
-        raw[raw.length - 1] = raw[raw.length - 1].replace(/\.md$/i, '');
-    return raw;
+    const segments = doc.source.physicalRelativePath.replace(/\.md$/i, '').split('/');
+    if (doc.source.representation === 'directory-index')
+        segments.pop();
+    return segments;
 }
 /** "Tree position" comparator for content-prose ordering within a store:
  *  compares two docs' RAW physical segments element-by-element (a shallower
@@ -193,10 +222,8 @@ function isAgentEditable(doc) {
  *  display order: `content` docs first, as clean prose (general→specific,
  *  then tree position, then filename — no tree chrome); every
  *  other winner (preview/name/hidden-bootless) folds into ONE catalog tree
- *  exactly as before. `nodeLocalSet` marks which winners came from the
- *  node-local store (ranked most-specific in content ordering); omit it for a
- *  pure resolver render. */
-function renderGrouped(winners, rootLabel, nodeLocalSet = new Set()) {
+ *  exactly as before. */
+function renderGrouped(winners, rootLabel) {
     const content = [];
     const rest = [];
     for (const d of winners) {
@@ -205,7 +232,7 @@ function renderGrouped(winners, rootLabel, nodeLocalSet = new Set()) {
         else
             rest.push(d);
     }
-    content.sort((a, b) => scopeGeneralityRank(a, nodeLocalSet.has(a)) - scopeGeneralityRank(b, nodeLocalSet.has(b)) ||
+    content.sort((a, b) => scopeGeneralityRank(a) - scopeGeneralityRank(b) ||
         compareTreePosition(a, b) ||
         a.name.localeCompare(b.name));
     const contentProse = content
@@ -214,82 +241,40 @@ function renderGrouped(winners, rootLabel, nodeLocalSet = new Set()) {
         .join('\n\n');
     return { contentProse, tree: buildTree(rest, rootLabel), contentDocs: content };
 }
-/** 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.
- *  Non-substrate files (those with 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 knowledge block.
+/** The node's own store (`nodes/<id>/context/memory/`), loaded through the
+ *  resolver's descriptor loader like every other store, then gate-passed.
+ *  Returned across ALL kinds — the node store is the catch-all this-node store
+ *  and rides into the knowledge block.
+ *
+ *  The store is addressed by the EXPLICIT `nodeId` rather than the host
+ *  process's, because one process renders for other nodes (crtrd claiming a
+ *  warm spare, `sys prompt-review` walking the canvas). The boot resolver
+ *  corpus deliberately excludes node scope (`cachedAllMemoryDocs`), so this is
+ *  the one path that carries node docs into a boot render and they cannot
+ *  double-surface.
  *
- *  Node-local docs follow the same GATE rule as every other store. A doc with
- *  no boot entry is retained here; renderKnowledgeForSubject floors it to
- *  `name` so it shows as a bare name instead of collapsing into `[+N more]`. */
-function nodeLocalDocs(nodeId, subject) {
-    const dir = memoryDir(nodeId);
-    if (!pathExists(dir))
+ *  Node docs follow the same GATE rule as every other store. A doc with no boot
+ *  entry is retained here; renderKnowledgeForSubject floors it to `name` so it
+ *  shows as a bare name instead of collapsing into `[+N more]`. */
+function nodeStoreDocs(nodeId, subject) {
+    let docs;
+    try {
+        // Narrowed to the node scope, so cwd and profile select no store.
+        docs = loadMemoryTargetView({ cwd: process.cwd(), profileId: null, nodeId }, { scope: 'node', quiet: true }).docs;
+    }
+    catch {
         return [];
+    }
     const out = [];
-    for (const file of walkFiles(dir, (n) => n.endsWith('.md'))) {
-        const raw = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
-        const fallbackName = normalizeDocName(raw);
-        if (!fallbackName)
-            continue;
-        try {
-            const { data, body } = parseFrontmatterGeneric(readText(file));
-            const schema = parseSubstrateFrontmatter(data);
-            if (schema === null)
-                continue;
-            // ONE substrate-identity rule (schema.ts's resolveDocName), shared with
-            // the resolver and explicit file-context loader: frontmatter `name` wins
-            // over the physical-path-derived fallback.
-            const name = resolveDocName(data, fallbackName);
-            // 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).
-            // Node-local is not a project store: no profile relationship names it,
-            // so it carries the neutral ceiling.
-            out.push({ ...schema, name, scope: 'user', path: file, body, projectMemory: NEUTRAL_PROJECT_MEMORY });
-        }
-        catch {
-            // A single malformed file is skipped, never fatal to the render.
+    for (const source of docs) {
+        const parsed = parseSubstrateDoc(source);
+        if (parsed === null || !gatePasses(parsed, subject))
             continue;
-        }
-    }
-    return out.filter((d) => gatePasses(d, subject));
-}
-function newDir(path) {
-    const segs = path.split('/');
-    return {
-        segment: path === '' ? '' : segs[segs.length - 1],
-        path,
-        children: new Map(),
-        leaves: [],
-        hiddenHere: 0,
-        renders: false,
-        ownCount: 0,
-    };
-}
-/** Walk/create the dir node at `path`, building intermediates. */
-function ensureDir(root, path) {
-    if (path === '')
-        return root;
-    let cur = root;
-    let acc = '';
-    for (const s of path.split('/')) {
-        acc = acc === '' ? s : `${acc}/${s}`;
-        let child = cur.children.get(s);
-        if (!child) {
-            child = newDir(acc);
-            cur.children.set(s, child);
-        }
-        cur = child;
+        const rung = bootRung(parsed, subject);
+        const floored = isVisible(rung) || parsed.surfaces.some((e) => e.on === 'boot') ? rung : 'name';
+        out.push({ ...parsed, source, bootRung: floored });
     }
-    return cur;
-}
-function parentDirOf(name) {
-    const i = name.lastIndexOf('/');
-    return i === -1 ? '' : name.slice(0, i);
+    return out;
 }
 function leafSegment(name) {
     const i = name.lastIndexOf('/');
@@ -298,74 +283,89 @@ function leafSegment(name) {
 function isVisible(rung) {
     return rungRank(rung) >= rungRank('name');
 }
+/** Project one canonical tree node into a render row. `byPath` maps a
+ *  descriptor back to the winner carrying its boot rung. */
+function planDir(node, byPath) {
+    const children = node.childDirectories.map((child) => planDir(child, byPath));
+    const leaves = [];
+    let hiddenHere = 0;
+    for (const member of node.childDocuments) {
+        const doc = byPath.get(member.document.path);
+        if (doc === undefined)
+            continue;
+        if (isVisible(doc.bootRung))
+            leaves.push({ name: member.name, order: member.order, doc });
+        else
+            hiddenHere += 1;
+    }
+    const ownDoc = node.document === null ? null : byPath.get(node.document.path) ?? null;
+    let own = null;
+    if (ownDoc !== null) {
+        if (isVisible(ownDoc.bootRung))
+            own = ownDoc;
+        else
+            hiddenHere += 1;
+    }
+    return {
+        name: node.name,
+        segment: leafSegment(node.name),
+        order: node.order,
+        own,
+        children,
+        leaves,
+        hiddenHere,
+        renders: false,
+        ownCount: 0,
+    };
+}
 /** Bottom-up pass: decide which dirs render and where hidden counts land. A dir
- *  renders when it has ≥1 visible leaf, ≥1 rendering child dir, or it is
- *  top-level (a direct child of the root always renders so its subtree count
- *  is visible — the root itself always renders). Bootless docs in a
- *  NON-rendering dir bubble up to the nearest rendering ancestor's `[+N more]`;
- *  a rendering dir keeps its own subtree count. Returns the count to bubble up. */
+ *  renders when it discloses something visible (its own document or ≥1 visible
+ *  leaf), when ≥1 child dir renders, or when it is top-level (a direct child of
+ *  the root always renders so its subtree count is visible — the root itself
+ *  always renders). Bootless docs in a NON-rendering dir bubble up to the
+ *  nearest rendering ancestor's `[+N more]`; a rendering dir keeps its own
+ *  subtree count. Returns the count to bubble up. */
 function resolveDir(dir, isTopLevel) {
     let totalHidden = dir.hiddenHere;
-    for (const child of dir.children.values()) {
-        totalHidden += resolveDir(child, dir.path === '');
+    for (const child of dir.children) {
+        totalHidden += resolveDir(child, dir.name === '');
     }
-    const hasVisibleLeaf = dir.leaves.length > 0;
-    const anyChildRenders = [...dir.children.values()].some((c) => c.renders);
-    dir.renders = hasVisibleLeaf || anyChildRenders || isTopLevel || dir.path === '';
+    const hasVisibleLeaf = dir.own !== null || dir.leaves.length > 0;
+    const anyChildRenders = dir.children.some((c) => c.renders);
+    dir.renders = hasVisibleLeaf || anyChildRenders || isTopLevel || dir.name === '';
     dir.ownCount = dir.renders ? totalHidden : 0;
     return dir.renders ? 0 : totalHidden;
 }
-function itemSortKey(item) {
+function itemOrder(item) {
     if (item.kind === 'dir')
-        return item.node.segment;
-    if (item.kind === 'leaf')
-        return leafSegment(item.doc.name);
-    return '';
+        return item.node.order;
+    return item.kind === 'leaf' ? item.entry.order : '';
 }
-/** DISPLAY-ORDER PIN ONLY: a leaf whose last name segment is `INDEX` sorts
- *  first among its directory's items. `INDEX` carries no mechanism anywhere in
- *  the substrate anymore — these are ordinary docs — but the ex-router docs
- *  keeping that name are each their dir's orientation entry, and localeCompare
- *  would drop them mid-list. */
-function isIndexPinned(item) {
-    return item.kind === 'leaf' && leafSegment(item.doc.name) === 'INDEX';
+function itemName(item) {
+    if (item.kind === 'dir')
+        return item.node.name;
+    return item.kind === 'leaf' ? item.entry.name : '';
 }
-/** Render one canonical logical doc entry at its boot rung. */
-function renderDocEntry(doc, label, entryPrefix, childPrefix, lines) {
-    switch (doc.bootRung) {
-        case 'preview': {
-            const pl = previewLine(doc);
-            lines.push(pl === '' ? `${entryPrefix}${label}` : `${entryPrefix}${label}  # read when: ${pl}`);
-            break;
-        }
-        case 'content': {
-            lines.push(`${entryPrefix}${label}`);
-            const body = doc.body.trim();
-            if (body !== '') {
-                for (const raw of body.split('\n')) {
-                    lines.push(`${childPrefix}  ${raw}`.replace(/\s+$/, ''));
-                }
-            }
-            break;
-        }
-        default: // 'name'
-            lines.push(`${entryPrefix}${label}`);
-    }
+/** Render one row's label at its document's boot rung: `preview` appends the
+ *  read-when routing line, `name` leaves the bare label. A `content` winner
+ *  never reaches the tree — renderGrouped renders its body as prose instead. */
+function renderDocEntry(doc, label, entryPrefix, lines) {
+    const preview = doc.bootRung === 'preview' ? previewLine(doc) : '';
+    lines.push(preview === '' ? `${entryPrefix}${label}` : `${entryPrefix}${label}  # read when: ${preview}`);
 }
 /** Render the children of a rendering dir, with `childPrefix` carrying the tree
- *  guides for this depth. Order: an `INDEX`-named leaf first (display pin),
- *  then child dirs and leaves intermixed alphabetically, then the `[+N more]`
- *  count last. */
+ *  guides for this depth. Order: child dirs and leaves intermixed by stored
+ *  physical position, then the `[+N more]` count last. A dir that carries its
+ *  own document renders that document's entry on the dir's own line. */
 function renderChildren(dir, childPrefix, lines) {
     const ordered = [];
-    for (const child of dir.children.values()) {
+    for (const child of dir.children) {
         if (child.renders)
             ordered.push({ kind: 'dir', node: child });
     }
-    for (const leaf of dir.leaves)
-        ordered.push({ kind: 'leaf', doc: leaf });
-    ordered.sort((a, b) => Number(isIndexPinned(b)) - Number(isIndexPinned(a)) ||
-        itemSortKey(a).localeCompare(itemSortKey(b)));
+    for (const entry of dir.leaves)
+        ordered.push({ kind: 'leaf', entry });
+    ordered.sort((a, b) => itemOrder(a).localeCompare(itemOrder(b)) || itemName(a).localeCompare(itemName(b)));
     if (dir.ownCount > 0)
         ordered.push({ kind: 'more', count: dir.ownCount });
     ordered.forEach((item, i) => {
@@ -376,12 +376,17 @@ function renderChildren(dir, childPrefix, lines) {
             case 'more':
                 lines.push(`${entryPrefix}[+${item.count} more]`);
                 break;
-            case 'dir':
-                lines.push(`${entryPrefix}${item.node.segment}/`);
+            case 'dir': {
+                const label = `${item.node.segment}/`;
+                if (item.node.own === null)
+                    lines.push(`${entryPrefix}${label}`);
+                else
+                    renderDocEntry(item.node.own, label, entryPrefix, lines);
                 renderChildren(item.node, nextPrefix, lines);
                 break;
+            }
             case 'leaf':
-                renderDocEntry(item.doc, leafSegment(item.doc.name), entryPrefix, nextPrefix, lines);
+                renderDocEntry(item.entry.doc, leafSegment(item.entry.name), entryPrefix, lines);
                 break;
         }
     });
@@ -390,26 +395,18 @@ function renderChildren(dir, childPrefix, lines) {
  *  headed by `rootLabel`. Returns '' when there are no docs at all (the
  *  empty-tree contract).
  *
- *  Callers (renderGrouped) pass docs that are ALREADY first-wins deduped by
- *  Step 1 (selectWinners); the `seen` set below is a defensive no-op guard
- *  against a residual duplicate name (e.g. the resolver-winners ∪ node-local
- *  merge), never the primary dedup mechanism — sorting into display order
- *  happens upstream of this call, never before dedup. */
+ *  Callers (renderGrouped) pass docs already first-wins deduped by step 1
+ *  (selectWinners); merging them into the canonical tree keeps that first-wins
+ *  outcome structurally, because a node's `document` is the first candidate at
+ *  its identity in source order. */
 function buildTree(docs, rootLabel) {
     if (docs.length === 0)
         return '';
-    const root = newDir('');
-    const seen = new Set();
-    for (const d of docs) {
-        if (seen.has(d.name))
-            continue; // first-wins cross-scope dedup
-        seen.add(d.name);
-        const parent = ensureDir(root, parentDirOf(d.name));
-        if (isVisible(d.bootRung))
-            parent.leaves.push(d);
-        else
-            parent.hiddenHere += 1;
-    }
+    const byPath = new Map();
+    for (const d of docs)
+        if (!byPath.has(d.path))
+            byPath.set(d.path, d);
+    const root = planDir(buildMemoryTree(docs.map((d) => d.source)).root, byPath);
     resolveDir(root, false);
     const lines = [rootLabel];
     renderChildren(root, '', lines);
@@ -476,7 +473,7 @@ function subKindDocCitation(subKind) {
  *  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. */
-function buildSubPersonaMenu(kind) {
+export function buildSubPersonaMenu(kind) {
     const subKinds = subKindsAvailableTo(kind);
     if (subKinds.length === 0)
         return '';
@@ -512,14 +509,14 @@ function buildSubPersonaMenu(kind) {
  *  across nodes is preserved. ALWAYS returns a non-empty splice — the guidance
  *  frame is unconditional, so it is never empty even when no preference is
  *  eligible. */
-function buildPreferencesBlock(subject, seen) {
+function buildPreferencesBlock(subject, target) {
     let contentDocs = [];
     let tree = '';
     let protocol = '';
     let memBody = MEMORY_USAGE_GUIDANCE;
     if (subject !== null) {
         const winners = selectWinners(subject, 'preference');
-        seedBootDelivery(seen, winners);
+        recordRendered(target, winners);
         const grouped = renderGrouped(winners, 'preferences');
         contentDocs = grouped.contentDocs;
         tree = grouped.tree;
@@ -548,12 +545,22 @@ function buildPreferencesBlock(subject, seen) {
     const memoryBlock = `<memory kind="preference">\n${memBody}\n</memory>`;
     return { block: protocol === '' ? memoryBlock : `${protocol}\n\n${memoryBlock}`, contentDocs, tree };
 }
-export function renderPreferencesForSubject(subject, seen) {
-    return buildPreferencesBlock(subject, seen);
+export function renderPreferencesForSubject(subject, target) {
+    return buildPreferencesBlock(subject, target);
 }
 // ---------------------------------------------------------------------------
 // 2. Knowledge — `<memory kind="knowledge">` (the first-message bearings).
 // ---------------------------------------------------------------------------
+/** STEP 1 for the knowledge block, shared by the boot render and the
+ *  config-change delta: the resolver's knowledge winners ∪ the node's own store
+ *  (any kind), first-wins deduped resolver-first so a same-named node doc
+ *  loses. Node docs carry the one rung floor — a node doc with NO boot entry is
+ *  bumped to `name` so it surfaces as a bare name instead of collapsing into a
+ *  `[+N more]` count; a node doc whose boot entries all fail their gates stays
+ *  absent. */
+function knowledgeWinners(subject, nodeId) {
+    return dedupeFirstWins([...selectWinners(subject, 'knowledge'), ...nodeStoreDocs(nodeId, subject)]);
+}
 /** The `<memory kind="knowledge">` block embedded in the session_start bearings
  *  message (bearings.ts pushes it as a SIBLING of `<crtr-bearings>`, or drops it
  *  when ''). The consultable catalog: every eligible `kind: knowledge` resolver
@@ -567,17 +574,10 @@ export function renderPreferencesForSubject(subject, seen) {
  *  docs never reach the `content` rung). Procedural guidance and factual
  *  references both live here as `knowledge`. Returns '' when nothing is
  *  eligible. */
-export function renderKnowledgeForSubject(subject, nodeId, seen) {
-    const nodeLocal = nodeLocalDocs(nodeId, subject).map((d) => {
-        const r = bootRung(d, subject);
-        return { ...d, bootRung: isVisible(r) || d.surfaces.some((e) => e.on === 'boot') ? r : 'name' };
-    });
-    const nodeLocalSet = new Set(nodeLocal);
-    // Resolver winners first: first-wins dedup keeps the resolver's copy over a
-    // same-named node-local doc, matching the original precedence.
-    const winners = dedupeFirstWins([...selectWinners(subject, 'knowledge'), ...nodeLocal]);
-    seedBootDelivery(seen, winners);
-    const { contentProse, tree } = renderGrouped(winners, 'knowledge', nodeLocalSet);
+export function renderKnowledgeForSubject(subject, nodeId, target) {
+    const winners = knowledgeWinners(subject, nodeId);
+    recordRendered(target, winners);
+    const { contentProse, tree } = renderGrouped(winners, 'knowledge');
     if (contentProse === '' && tree === '')
         return '';
     let out = KNOWLEDGE_INTRO;
@@ -589,3 +589,71 @@ export function renderKnowledgeForSubject(subject, nodeId, seen) {
     // Surfaced INTO this node: swap literal `$CRTR_CONTEXT_DIR` for the real path.
     return interpolateNodePaths(`<memory kind="knowledge">\n${out}\n</memory>`, nodeId);
 }
+// ---------------------------------------------------------------------------
+// 3. The config-change delta — the memory a node's NEW configuration exposes.
+// ---------------------------------------------------------------------------
+const DELTA_PROTOCOL_INTRO = 'Your node configuration changed. This operating protocol is in force for you now:';
+const DELTA_PREFERENCES_INTRO = 'Your new configuration puts these preferences in force — standing directives and corrections ' +
+    'from the user. To read one, run `crtr memory read <name>`. ' +
+    READ_LEGEND.replace('%s', 'preference');
+const DELTA_KNOWLEDGE_INTRO = 'Your new configuration exposes these knowledge documents — consult them exactly like the rest ' +
+    'of your catalog (`crtr memory read <name>`). ' +
+    READ_LEGEND.replace('%s', 'document');
+/** Winners not yet loaded at their boot rung. Bootless winners remain absent. */
+function undelivered(target, docs) {
+    return docs.filter((d) => rendersAtBoot(d) && !documentExposedAtOrAbove(target.state, d.path, d.body, d.bootRung));
+}
+/** What a node's configuration change newly exposes, rendered as up to three
+ *  blocks in one string: the shipped protocol prose, a `<memory kind="preference">`
+ *  block, and a `<memory kind="knowledge">` block — each dropped when empty, ''
+ *  when the change exposes nothing.
+ *
+ *  Both kinds use the current subject's ordinary winner assembly, then compare
+ *  against the active exposure maximum. A lower rung or removal yields nothing
+ *  because content already loaded into this context cannot be withdrawn.
+ *  Rendered deltas register as transcript exposure through `target`. */
+export function renderConfigChangeDelta(subject, nodeId, target) {
+    const prefs = undelivered(target, selectWinners(subject, 'preference'));
+    const knowledgeDelta = undelivered(target, knowledgeWinners(subject, nodeId));
+    recordRendered(target, [...prefs, ...knowledgeDelta]);
+    const { contentDocs, tree } = renderGrouped(prefs, 'preferences');
+    // Same split as the boot preference render: shipped bodies are protocol prose
+    // (the rules of the node's world), agent-editable bodies are memory the node
+    // can revise, and every non-content preference winner rides the one catalog.
+    const shipped = contentDocs
+        .filter((d) => !isAgentEditable(d))
+        .map((d) => d.body.trim())
+        .filter((b) => b !== '');
+    const editable = contentDocs
+        .filter((d) => isAgentEditable(d))
+        .map((d) => {
+        const b = d.body.trim();
+        return b === '' ? '' : `<preference name="${d.name}">\n${b}\n</preference>`;
+    })
+        .filter((b) => b !== '');
+    const blocks = [];
+    if (shipped.length > 0)
+        blocks.push(`${DELTA_PROTOCOL_INTRO}\n\n${shipped.join('\n\n')}`);
+    if (editable.length > 0 || tree !== '') {
+        let body = DELTA_PREFERENCES_INTRO;
+        if (editable.length > 0)
+            body += `\n\n${editable.join('\n\n')}`;
+        if (tree !== '')
+            body += `\n\n${tree}`;
+        body += `\n\n${PREFERENCES_OUTRO}`;
+        blocks.push(`<memory kind="preference">\n${body}\n</memory>`);
+    }
+    const knowledge = renderGrouped(knowledgeDelta, 'knowledge');
+    if (knowledge.contentProse !== '' || knowledge.tree !== '') {
+        let body = DELTA_KNOWLEDGE_INTRO;
+        if (knowledge.contentProse !== '')
+            body += `\n\n${knowledge.contentProse}`;
+        if (knowledge.tree !== '')
+            body += `\n\n${knowledge.tree}`;
+        body += `\n\n${KNOWLEDGE_OUTRO}`;
+        blocks.push(`<memory kind="knowledge">\n${body}\n</memory>`);
+    }
+    if (blocks.length === 0)
+        return '';
+    return interpolateNodePaths(blocks.join('\n\n'), nodeId);
+}