@north-light/crouter 0.3.210 → 0.3.212

package/dist/commands/sys/__tests__/migrate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/sys/__tests__/migrate.test.js

@@ -0,0 +1,95 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CLI = join(HERE, '../../../cli.ts');
+const TSX_LOADER = import.meta.resolve('tsx/esm');
+const OLD_DOC = `---
+kind: knowledge
+system-prompt-visibility: content
+file-read-visibility: none
+---
+# Old format
+`;
+const CURRENT_DOC = `---
+kind: knowledge
+---
+# Current format
+`;
+function write(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+}
+function manifest(name, projects) {
+    return JSON.stringify({
+        schema_version: 1,
+        name,
+        projects,
+        home: projects[0] ?? null,
+        created_at: '2026-01-01T00:00:00.000Z',
+        last_used_at: null,
+    });
+}
+test('sys migrate covers profile-aware refs and every descendant project/plugin store', () => {
+    const home = mkdtempSync(join(tmpdir(), 'crtr-sys-migrate-'));
+    const userRoot = join(home, '.crouter');
+    const rootProfile = join(userRoot, 'profiles', 'root-00000000');
+    const appletProfile = join(userRoot, 'profiles', 'applet-deadbeef');
+    const appletProject = join(home, 'inactive-applet-project');
+    const nestedOnlyProject = join(home, 'nested-only-project');
+    const deepRoot = join(appletProject, 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', '.crouter');
+    const pluginRoot = join(deepRoot, 'plugins', 'deep-memory');
+    const embeddedPluginRoot = join(nestedOnlyProject, 'embedded', '.crouter', 'plugins', 'embedded-memory');
+    const userDoc = join(userRoot, 'memory', 'user-link.md');
+    const rootDoc = join(rootProfile, 'memory', 'root.md');
+    const appletDoc = join(appletProfile, 'memory', 'identity.md');
+    const projectDoc = join(appletProject, '.crouter', 'memory', 'project.md');
+    const deepDoc = join(deepRoot, 'memory', 'deep.md');
+    const pluginDoc = join(pluginRoot, 'memory', 'plugin.md');
+    const embeddedPluginDoc = join(embeddedPluginRoot, 'memory', 'plugin.md');
+    try {
+        write(join(rootProfile, 'profile.json'), manifest('root', []));
+        write(join(appletProfile, 'profile.json'), manifest('applet-inactive', [appletProject, nestedOnlyProject]));
+        write(userDoc, `${OLD_DOC}\nSee [[user/scoped]].\n`);
+        write(join(userRoot, 'memory', 'scoped', 'INDEX.md'), CURRENT_DOC);
+        write(rootDoc, `${OLD_DOC}\nSee [[shared]].\n`);
+        write(appletDoc, `${OLD_DOC}\nSee [[shared]].\n`);
+        write(join(appletProfile, 'memory', 'shared', 'INDEX.md'), CURRENT_DOC);
+        write(projectDoc, OLD_DOC);
+        write(join(appletProject, '.crouter', 'memory', 'scoped', 'INDEX.md'), CURRENT_DOC);
+        write(deepDoc, OLD_DOC);
+        write(join(pluginRoot, '.crouter-plugin', 'plugin.json'), JSON.stringify({ name: 'deep-memory', version: '1.0.0' }));
+        write(pluginDoc, OLD_DOC);
+        write(join(embeddedPluginRoot, '.crouter-plugin', 'plugin.json'), JSON.stringify({ name: 'embedded-memory', version: '1.0.0' }));
+        write(join(nestedOnlyProject, 'embedded', '.git', 'HEAD'), 'ref: refs/heads/main\n');
+        write(embeddedPluginDoc, OLD_DOC);
+        const env = {
+            ...process.env,
+            HOME: home,
+            CRTR_PROFILE_ID: 'root-00000000',
+            CRTR_NO_AUTO_INIT: '1',
+            CRTR_NO_AUTO_UPDATE: '1',
+        };
+        delete env.CRTR_NODE_ID;
+        const result = spawnSync(process.execPath, ['--conditions=crtr-src', '--import', TSX_LOADER, CLI, 'sys', 'migrate', '--json'], { cwd: home, env, encoding: 'utf8' });
+        assert.equal(result.status, 0, result.stderr);
+        const output = JSON.parse(result.stdout);
+        assert.equal(output.stores, 7);
+        assert.equal(output.changed, 7);
+        for (const path of [userDoc, rootDoc, appletDoc, projectDoc, deepDoc, pluginDoc, embeddedPluginDoc]) {
+            const migrated = readFileSync(path, 'utf8');
+            assert.doesNotMatch(migrated, /system-prompt-visibility|file-read-visibility/);
+            assert.match(migrated, /surfaces:\n  - on: boot\n    at: content/);
+        }
+        assert.match(readFileSync(userDoc, 'utf8'), /\[\[user\/scoped\/INDEX\]\]/);
+        assert.match(readFileSync(rootDoc, 'utf8'), /\[\[shared\]\]/);
+        assert.match(readFileSync(appletDoc, 'utf8'), /\[\[shared\/INDEX\]\]/);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});

package/dist/commands/sys/migrate.js

@@ -2,55 +2,83 @@
 // every writable memory store's documents to the current document format.
 // (Journaled canvas-db migrations run in the db's own ordered chain when the
 // daemon opens it; this leaf owns only the on-disk document stores.)
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
 import { pathExists, realpathOrSelf } from '../../core/fs-utils.js';
+import { createMemoryDocSnapshot } from '../../core/memory-resolver.js';
 import { listInstalledPlugins, listInstalledPluginsInRoot } from '../../core/resolver.js';
 import { pluginMemoryDir, projectScopeRoots, scopeMemoryDir } from '../../core/scope.js';
-import { loadProfileManifest, profileMemoryDir } from '../../core/profiles/manifest.js';
-import { getDefaultProfileId } from '../../core/profiles/default-binding.js';
-import { descendantStoreRoots } from '../../core/nested-stores.js';
+import { listProfiles, profileMemoryDir } from '../../core/profiles/manifest.js';
+import { descendantStoreRootsExhaustive } from '../../core/nested-stores.js';
 import { memoryDir as nodeMemoryDir } from '../../core/runtime/memory.js';
 import { runConvergentMigrations } from '../../migrations/convergent.js';
+function targetKey(target) {
+    return `${realpathOrSelf(target.cwd)}\u0000${target.profileId ?? ''}\u0000${target.nodeId ?? ''}`;
+}
 /** Every writable memory store — the lint corpus minus builtin (package-owned,
- *  regenerated on every install, so migrating it would fight the package). */
-function migratableStoreDirs() {
-    const dirs = new Set();
-    const add = (dir) => {
-        // realpath so one store reached through two spellings (e.g. a symlinked
-        // ancestor) migrates once.
-        if (dir !== null && dir !== '' && pathExists(dir))
-            dirs.add(realpathOrSelf(dir));
-    };
-    const projectRoots = projectScopeRoots();
-    for (const root of projectRoots) {
-        add(join(root, 'memory'));
-        for (const plugin of listInstalledPluginsInRoot('project', root)) {
-            if (plugin.enabled)
-                add(pluginMemoryDir(plugin));
+ *  regenerated on every install, so migrating it would fight the package).
+ *  Physical stores dedupe once while retaining every owning target corpus. */
+function migratableStores() {
+    const stores = new Map();
+    const add = (dir, target) => {
+        if (dir === null || dir === '' || !pathExists(dir))
+            return;
+        const real = realpathOrSelf(dir);
+        let store = stores.get(real);
+        if (store === undefined) {
+            store = { dir: real, targets: [] };
+            stores.set(real, store);
         }
+        const key = targetKey(target);
+        if (!store.targets.some((candidate) => targetKey(candidate) === key))
+            store.targets.push(target);
+    };
+    const addProjectRoots = (roots, profileId) => {
+        const addRoot = (projectRoot) => {
+            const target = { cwd: dirname(projectRoot), profileId, nodeId: null };
+            add(join(projectRoot, 'memory'), target);
+            for (const plugin of listInstalledPluginsInRoot('project', projectRoot)) {
+                if (plugin.enabled)
+                    add(pluginMemoryDir(plugin), target);
+            }
+        };
+        for (const root of roots)
+            addRoot(root);
+        for (const descendant of descendantStoreRootsExhaustive(roots))
+            addRoot(descendant);
+    };
+    const selectedProfileId = process.env['CRTR_PROFILE_ID'] || null;
+    addProjectRoots(projectScopeRoots(process.cwd(), null), selectedProfileId);
+    const profiles = listProfiles();
+    const profileTargets = [];
+    for (const { profileId, manifest } of profiles) {
+        const profileTarget = {
+            cwd: manifest.home ?? manifest.projects[0] ?? process.cwd(),
+            profileId,
+            nodeId: null,
+        };
+        profileTargets.push(profileTarget);
+        add(profileMemoryDir(profileId), profileTarget);
+        const roots = [
+            ...new Set(manifest.projects.flatMap((project) => [join(project, '.crouter'), ...projectScopeRoots(project, null)])),
+        ];
+        addProjectRoots(roots, profileId);
     }
-    for (const root of descendantStoreRoots(projectRoots))
-        add(join(root, 'memory'));
-    add(scopeMemoryDir('user'));
+    const ambientTarget = { cwd: process.cwd(), profileId: selectedProfileId, nodeId: null };
+    const globalTargets = [ambientTarget, ...profileTargets];
+    const userDir = scopeMemoryDir('user');
+    for (const target of globalTargets)
+        add(userDir, target);
     for (const plugin of listInstalledPlugins('user')) {
-        if (plugin.enabled)
-            add(pluginMemoryDir(plugin));
-    }
-    const profileIdOrName = process.env['CRTR_PROFILE_ID'] || getDefaultProfileId(process.cwd());
-    if (profileIdOrName) {
-        try {
-            const { profileId } = loadProfileManifest(profileIdOrName);
-            add(profileMemoryDir(profileId));
-        }
-        catch {
-            // Unresolvable profile: no profile store to migrate.
-        }
+        if (!plugin.enabled)
+            continue;
+        for (const target of globalTargets)
+            add(pluginMemoryDir(plugin), target);
     }
     const nodeId = process.env['CRTR_NODE_ID'] ?? '';
     if (nodeId !== '')
-        add(nodeMemoryDir(nodeId));
-    return [...dirs];
+        add(nodeMemoryDir(nodeId), { cwd: process.cwd(), profileId: selectedProfileId, nodeId });
+    return [...stores.values()];
 }
 export const sysMigrateLeaf = defineLeaf({
     name: 'migrate',
@@ -71,7 +99,7 @@ export const sysMigrateLeaf = defineLeaf({
         ],
         outputKind: 'object',
         effects: [
-            'Rewrites old-format memory documents in place (atomic per-file writes) across the writable stores: project (plus nested descendant stores and installed plugin stores), user, profile, and this node\'s store. Builtin docs are package-owned and never touched.',
+            'Rewrites old-format memory documents in place (atomic per-file writes) across the writable stores: every profile and every profile-owned project (plus nested descendant stores and installed plugin stores), the current project, user, and this node\'s store. Builtin docs are package-owned and never touched.',
             'Under --dry-run: read-only, writes nothing.',
         ],
     },
@@ -79,13 +107,39 @@ export const sysMigrateLeaf = defineLeaf({
         const dryRun = input.dryRun === true;
         const applied = [];
         const skipped = [];
-        const stores = migratableStoreDirs();
+        const stores = migratableStores();
+        const snapshots = new Map();
         for (const store of stores) {
-            const result = runConvergentMigrations(store, { dryRun });
+            const resolvers = store.targets.map((target) => (name) => {
+                const key = targetKey(target);
+                let snapshot = snapshots.get(key);
+                if (snapshot === undefined) {
+                    snapshot = createMemoryDocSnapshot(target);
+                    snapshots.set(key, snapshot);
+                }
+                return snapshot.legacyDirectoryIndex(name);
+            });
+            const result = runConvergentMigrations(store.dir, {
+                dryRun,
+                context: {
+                    legacyDirectoryIndex: (name) => {
+                        let replacement = null;
+                        for (const resolve of resolvers) {
+                            const candidate = resolve(name);
+                            if (candidate === null)
+                                return null;
+                            if (replacement !== null && replacement !== candidate)
+                                return null;
+                            replacement = candidate;
+                        }
+                        return replacement;
+                    },
+                },
+            });
             for (const row of result.applied)
-                applied.push({ store, migration: row.migration, files: row.files });
+                applied.push({ store: store.dir, migration: row.migration, files: row.files });
             for (const s of result.skipped)
-                skipped.push({ store, relPath: s.relPath, error: s.error });
+                skipped.push({ store: store.dir, relPath: s.relPath, error: s.error });
         }
         const changed = applied.reduce((n, row) => n + row.files.length, 0);
         return {

package/dist/core/memory-resolver.d.ts

@@ -132,8 +132,12 @@ export interface MemoryDocSnapshot {
     /** Resolve names against that source snapshot; failures are omitted so
      * callers can retain their own per-document error behavior. */
     resolve(names: readonly string[]): Map<string, MemoryDoc>;
+    /** Frozen pre-cut resolution used only by the surfaces migration: return the
+     * explicit INDEX spelling when a bare directory/plugin ref and that spelling
+     * resolve to the same file in this target corpus. */
+    legacyDirectoryIndex(name: string): string | null;
 }
-export declare function createMemoryDocSnapshot(): MemoryDocSnapshot;
+export declare function createMemoryDocSnapshot(target?: MemoryTarget): MemoryDocSnapshot;
 /** Resolve several unqualified names over one memory-source snapshot. Failed
  * names are omitted so callers can preserve their per-document error behavior. */
 export declare function resolveMemoryDocs(names: readonly string[]): Map<string, MemoryDoc>;

package/dist/core/memory-resolver.js

@@ -1,4 +1,4 @@
-import { join, relative, sep } from 'node:path';
+import { basename, join, relative, sep } from 'node:path';
 import { readdirSync } from 'node:fs';
 import { CRTR_DIR_NAME } from '../types.js';
 import { pathExists, readText, walkFiles } from './fs-utils.js';
@@ -343,32 +343,47 @@ export function resolveHistoryLogPath(historyDir, segments) {
  *  never authored with a numeric prefix); resolution against the physical tree
  *  is prefix-blind via `resolveNormalizedPath` so a normalized name finds an
  *  `NN-`-pinned physical file/dir. */
-function findMemoryMatchInSource(name, segments, source) {
+function findMemoryMatchInSource(name, segments, source, legacyDirectoryIndex = false) {
     const isLegacySkillDoc = segments.at(-1) === 'SKILL';
     // Native memory dir first inside this source (native-before-plugin
     // precedence), then its enabled plugins.
     const dir = source.memoryDir;
     if (dir) {
-        const { filePath } = resolveNormalizedPath(dir, segments);
+        const { filePath, dirPath } = resolveNormalizedPath(dir, segments);
         if (!isLegacySkillDoc && filePath !== null)
             return loadMemoryDoc(source.scope, dir, filePath, name);
+        if (legacyDirectoryIndex && dirPath !== null) {
+            const indexPath = join(dirPath, 'INDEX.md');
+            if (pathExists(indexPath))
+                return loadMemoryDoc(source.scope, dir, indexPath, name);
+        }
     }
     // Plugin memory dir: a `<plugin>/<rest>` name resolves against that enabled
     // plugin's memory/ tree (the `<pluginName>/` mount that listAllMemoryDocs
     // enumerates — `read` must resolve what `list` shows).
     const slash = name.indexOf('/');
-    if (slash <= 0)
+    if (slash <= 0 && !legacyDirectoryIndex)
         return undefined;
-    const pluginName = name.slice(0, slash);
-    const rest = name.slice(slash + 1);
+    const pluginName = slash > 0 ? name.slice(0, slash) : name;
+    const rest = slash > 0 ? name.slice(slash + 1) : '';
     for (const p of source.plugins) {
         if (p.name !== pluginName)
             continue;
         const pdir = pluginMemoryDir(p);
-        const restSegments = rest.split('/');
-        const { filePath } = resolveNormalizedPath(pdir, restSegments);
-        if (restSegments.at(-1) !== 'SKILL' && filePath !== null)
-            return loadMemoryDoc(source.scope, pdir, filePath, name);
+        const restSegments = rest === '' ? [] : rest.split('/');
+        if (restSegments.length > 0) {
+            const { filePath } = resolveNormalizedPath(pdir, restSegments);
+            if (restSegments.at(-1) !== 'SKILL' && filePath !== null)
+                return loadMemoryDoc(source.scope, pdir, filePath, name);
+        }
+        if (legacyDirectoryIndex) {
+            const indexDir = rest === '' ? pdir : resolveNormalizedPath(pdir, restSegments).dirPath;
+            if (indexDir !== null) {
+                const indexPath = join(indexDir, 'INDEX.md');
+                if (pathExists(indexPath))
+                    return loadMemoryDoc(source.scope, pdir, indexPath, name);
+            }
+        }
     }
     return undefined;
 }
@@ -384,8 +399,7 @@ function loadMemorySources(target, scope, includeDescendants = false) {
         docs: sourceMemoryDocs(source, true),
     }));
 }
-export function createMemoryDocSnapshot() {
-    const target = ambientTarget();
+export function createMemoryDocSnapshot(target = ambientTarget()) {
     const defaultSources = loadMemorySources(target);
     const sourcesByScope = new Map([[undefined, defaultSources]]);
     const sourceFor = (scope) => {
@@ -412,9 +426,26 @@ export function createMemoryDocSnapshot() {
             }
             return resolved;
         },
+        legacyDirectoryIndex: (name) => {
+            if (name === 'INDEX' || name.endsWith('/INDEX'))
+                return null;
+            try {
+                const parsed = parseSkillQualifier(name);
+                const sources = sourceFor(parsed.scope);
+                const legacy = resolveMemoryDocFromSources(name, {}, sources, true);
+                if (basename(legacy.path) !== 'INDEX.md')
+                    return null;
+                const explicitName = `${name}/INDEX`;
+                const explicit = resolveMemoryDocFromSources(explicitName, {}, sources);
+                return explicit.path === legacy.path ? explicitName : null;
+            }
+            catch {
+                return null;
+            }
+        },
     };
 }
-function resolveMemoryDocFromSources(rawName, opts, sources) {
+function resolveMemoryDocFromSources(rawName, opts, sources, legacyDirectoryIndex = false) {
     const parsed = parseSkillQualifier(rawName);
     if (parsed.scope && opts.scope && parsed.scope !== opts.scope) {
         throw usage(`scope conflict: identifier "${rawName}" uses scope "${parsed.scope}" but --scope is "${opts.scope}"`);
@@ -433,7 +464,7 @@ function resolveMemoryDocFromSources(rawName, opts, sources) {
         const identity = docs.find((d) => d.name === name);
         if (identity && kindOk(identity))
             return identity;
-        const direct = findMemoryMatchInSource(name, segments, source);
+        const direct = findMemoryMatchInSource(name, segments, source, legacyDirectoryIndex);
         if (direct && kindOk(direct))
             return direct;
     }

package/dist/core/nested-stores.d.ts

@@ -10,3 +10,8 @@
  * duplicated dedupe logic.
  */
 export declare function descendantStoreRoots(ancestorRoots: string[]): string[];
+/** Complete descendant-store discovery for state migrations. Unlike the
+ *  interactive addressing lane, this filesystem walk has no time or depth
+ *  budget, crosses embedded repositories, admits plugin-only `.crouter` roots,
+ *  and does not cache. */
+export declare function descendantStoreRootsExhaustive(ancestorRoots: string[]): string[];

package/dist/core/nested-stores.js

@@ -113,20 +113,24 @@ function collectGitStores(owner, add, timeoutMs, trip) {
 /** Non-git owner: DFS with junk skips, a depth cap, and a stop at any embedded
  *  `.git` dir (an embedded repo is its own world — register it explicitly). */
 function collectWalkStores(owner, add, deadline, trip) {
+    collectWalkStoresFromOwner(owner, add, { deadline, maxDepth: MAX_DEPTH, trip });
+}
+function collectWalkStoresFromOwner(owner, add, opts = {}) {
     const stack = [{ dir: owner, depth: 0 }];
     while (stack.length > 0) {
-        if (Date.now() > deadline) {
-            trip();
+        if (opts.deadline !== undefined && Date.now() > opts.deadline) {
+            opts.trip?.();
             return;
         }
         const { dir, depth } = stack.pop();
         if (dir !== owner) {
-            if (pathExists(join(dir, '.git')))
+            if (opts.crossEmbeddedRepos !== true && pathExists(join(dir, '.git')))
                 continue;
-            if (pathExists(join(dir, CRTR_DIR_NAME, 'memory')))
-                add(join(dir, CRTR_DIR_NAME));
+            const storeRoot = join(dir, CRTR_DIR_NAME);
+            if (pathExists(opts.includePluginOnly === true ? storeRoot : join(storeRoot, 'memory')))
+                add(storeRoot);
         }
-        if (depth >= MAX_DEPTH)
+        if (opts.maxDepth !== undefined && depth >= opts.maxDepth)
             continue;
         let entries;
         try {
@@ -144,3 +148,24 @@ function collectWalkStores(owner, add, deadline, trip) {
         }
     }
 }
+/** Complete descendant-store discovery for state migrations. Unlike the
+ *  interactive addressing lane, this filesystem walk has no time or depth
+ *  budget, crosses embedded repositories, admits plugin-only `.crouter` roots,
+ *  and does not cache. */
+export function descendantStoreRootsExhaustive(ancestorRoots) {
+    const ancestorReal = new Set(ancestorRoots.map((root) => realpathOrSelf(root)));
+    const found = [];
+    const seen = new Set();
+    const add = (storeRoot) => {
+        const real = realpathOrSelf(storeRoot);
+        if (seen.has(real) || ancestorReal.has(real))
+            return;
+        seen.add(real);
+        found.push(storeRoot);
+    };
+    const owners = new Set(ancestorRoots.map((root) => realpathOrSelf(dirname(root))));
+    for (const owner of owners) {
+        collectWalkStoresFromOwner(owner, add, { includePluginOnly: true, crossEmbeddedRepos: true });
+    }
+    return found;
+}

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

@@ -37,7 +37,7 @@ import { gatePasses } from './gate.js';
 import { commandDeliveryRung, memoryReadDeliveryRung, owningRootOf, readDeliveryRung, workspaceOpenRung } from './surface-match.js';
 import { deliveredAtOrAbove, recordDelivery } from './injected-store.js';
 import { normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName } from './schema.js';
-import { cachedSubstrateDocs } from './session-cache.js';
+import { cachedSubstrateDocsInclusive } from './session-cache.js';
 import { realpathOrSelf } from '../fs-utils.js';
 const JUNK_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache', '.yalc']);
 function attr(s) {
@@ -137,9 +137,14 @@ function enclosingProjectDocs(absReadFile) {
     }
     return docs;
 }
+// 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 shared dedup set keeps
+// a boot-rendered doc from re-delivering below its rung here.
 function resolvedDocs() {
     try {
-        return cachedSubstrateDocs(listAllMemoryDocs, parseSubstrateDoc);
+        return cachedSubstrateDocsInclusive(listAllMemoryDocs, parseSubstrateDoc);
     }
     catch {
         return [];

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

@@ -27,12 +27,13 @@
 //                        doc (e.g. the inline memory-reference inventory) use
 //                        this pair.
 //   • allMemoryDocs    — allMemoryDocsInclusive with node-scope docs excluded
-//                        (unchanged boot/on-read behavior — see the comment on
-//                        cachedAllMemoryDocs). Shared by both render.ts and
-//                        on-read.ts.
+//                        (boot-only view — see the comment on
+//                        cachedAllMemoryDocs). Consumed by render.ts.
 //   • substrateDocs    — allMemoryDocs mapped through parseSubstrateDoc and
-//                        null-filtered.  Used by render.ts's resolverDocs and
-//                        on-read.ts's appliesToCandidates.
+//                        null-filtered.  Used by render.ts's resolver corpus.
+//                        The event corpus (on-read.ts) uses the INCLUSIVE
+//                        pair instead: node docs' surfaces entries fire on
+//                        read/memory-read/command like any other store's.
 // Node subjects are deliberately NOT cached: lifecycle, mode, kind, and other
 // gate inputs can change while a resident broker/session remains live. Rendering
 // must always gate against the current persisted node metadata.
@@ -77,14 +78,15 @@ export function cachedSubstrateDocsInclusive(listFn, parseFn) {
  *  `listFn` is injected by the caller to avoid circular imports at module init. */
 export function cachedAllMemoryDocs(listFn) {
     if (_cache.allMemoryDocs === null) {
-        // The boot pipeline (render + on-read) EXCLUDES node-scope docs: node-local
+        // The BOOT pipeline (render.ts) EXCLUDES node-scope docs: node-local
         // memory surfaces at boot via render.ts's nodeLocalDocs (any kind, floored
         // into the knowledge block), NOT through the resolver corpus, so a node doc
-        // must not also enter here (it would double-surface at boot and could fire
-        // on-read). The `node` scope reaches CLI read/list/find/delete through the
-        // uncached listAllMemoryDocs() path instead. Derived from the inclusive
-        // cache by filtering, so listFn() itself still runs at most once per
-        // session even though both views are consumed.
+        // must not also enter there (it would double-surface at boot). The event
+        // corpus (on-read.ts) uses the inclusive view — node docs' surfaces
+        // entries fire on read/memory-read/command. The `node` scope reaches CLI
+        // read/list/find/delete through the uncached listAllMemoryDocs() path.
+        // Derived from the inclusive cache by filtering, so listFn() itself still
+        // runs at most once per session even though both views are consumed.
         _cache.allMemoryDocs = cachedAllMemoryDocsInclusive(listFn).filter((d) => d.scope !== 'node');
     }
     return _cache.allMemoryDocs;

package/dist/migrations/001-surfaces-frontmatter.js

@@ -18,11 +18,9 @@
 // folded scalars). Each splice is validated by re-parsing: the result must
 // equal the original record minus the dead fields plus `surfaces`, or the
 // migration throws naming the doc.
-import { basename } from 'node:path';
 import { isMap, parse as parseYaml, parseDocument, stringify } from 'yaml';
 import { parseFrontmatterGeneric } from '../core/frontmatter.js';
 import { findDocLinks } from '../core/memory/doc-link-grammar.js';
-import { createMemoryDocSnapshot } from '../core/memory-resolver.js';
 const OLD_FIELDS = ['system-prompt-visibility', 'file-read-visibility', 'applies-to', 'read-when'];
 // ---------------------------------------------------------------------------
 // Frozen old-schema parsing (pre-cut substrate/schema.ts semantics).
@@ -136,42 +134,22 @@ function planEntries(d, bootRung) {
 }
 // ---------------------------------------------------------------------------
 // Rule 5: bare-dir `[[ref]]` → `[[dir/INDEX]]`. A ref is rewritten only when
-// it resolves through the bare-dir/bare-plugin-name → INDEX.md convenience
-// (resolved file is an INDEX.md the ref does not name) AND `<ref>/INDEX`
-// provably resolves to the same file — meaning-preserving or untouched.
-// Resolution uses the fs-only memory resolver from this process's ambient
-// target, because refs cross stores (user docs point into plugin dirs).
+// the owning target corpus proves the old bare-directory convenience and the
+// explicit INDEX spelling resolve to the same file. The decision cache belongs
+// to one migration target; profile-local names never leak across stores.
 // ---------------------------------------------------------------------------
-let corpusMemo = null;
-const refDecisionMemo = new Map();
-function resolveOne(name) {
-    corpusMemo ??= createMemoryDocSnapshot();
-    return corpusMemo.resolve([name]).get(name);
-}
-function indexRefReplacement(name) {
-    const memo = refDecisionMemo.get(name);
-    if (memo !== undefined)
-        return memo;
-    let out = null;
-    if (name !== 'INDEX' && !name.endsWith('/INDEX')) {
-        const hit = resolveOne(name);
-        if (hit !== undefined && basename(hit.path) === 'INDEX.md') {
-            const explicit = resolveOne(`${name}/INDEX`);
-            if (explicit !== undefined && explicit.path === hit.path)
-                out = `${name}/INDEX`;
-        }
-    }
-    refDecisionMemo.set(name, out);
-    return out;
-}
-function rewriteBareDirRefs(body) {
+function rewriteBareDirRefs(body, context, decisions) {
     const links = findDocLinks(body);
     if (links.length === 0)
         return body;
     let out = '';
     let pos = 0;
     for (const link of links) {
-        const repl = indexRefReplacement(link.name);
+        let repl = decisions.get(link.name);
+        if (repl === undefined) {
+            repl = context?.legacyDirectoryIndex(link.name) ?? null;
+            decisions.set(link.name, repl);
+        }
         if (repl === null)
             continue;
         out += body.slice(pos, link.start) + `[[${repl}]]`;
@@ -258,12 +236,13 @@ function rebuildSource(d, newYaml, newBody) {
 export const surfacesFrontmatterMigration = {
     lane: 'convergent',
     description: 'surfaces frontmatter: fold visibility/applies-to/read-when routing into surfaces entries; rewrite bare-directory [[refs]] to [[dir/INDEX]]',
-    apply(store) {
+    apply(store, context) {
         const docs = store.docs.map(classify).filter((d) => d !== null);
         const ceiling = buildCeiling(docs);
+        const decisions = new Map();
         const changes = [];
         for (const d of docs) {
-            const newBody = rewriteBareDirRefs(d.doc.body);
+            const newBody = rewriteBareDirRefs(d.doc.body, context, decisions);
             if (!d.hasOldFields && newBody === d.doc.body)
                 continue;
             const newYaml = d.hasOldFields

package/dist/migrations/convergent.d.ts

@@ -1,4 +1,4 @@
-import type { StateMigration, StoreSnapshot } from './types.js';
+import type { ConvergentMigrationContext, StateMigration, StoreSnapshot } from './types.js';
 /** A doc excluded from the snapshot because its frontmatter is not valid YAML.
  *  Per-doc throw isolation at the collection layer: the bad file is named and
  *  the rest of the store still migrates. */
@@ -28,4 +28,5 @@ export declare function loadStoreSnapshot(root: string): {
 export declare function runConvergentMigrations(root: string, opts?: {
     dryRun?: boolean;
     migrations?: readonly StateMigration[];
+    context?: ConvergentMigrationContext;
 }): ConvergentRunResult;

package/dist/migrations/convergent.js

@@ -57,7 +57,7 @@ export function runConvergentMigrations(root, opts = {}) {
     const applied = [];
     for (const migration of migrations) {
         const bySource = new Map(snapshot.docs.map((d) => [d.path, d.source]));
-        const changes = migration.apply(snapshot).filter((c) => bySource.get(c.path) !== c.after);
+        const changes = migration.apply(snapshot, opts.context).filter((c) => bySource.get(c.path) !== c.after);
         if (changes.length === 0)
             continue;
         for (const change of changes) {

package/dist/migrations/types.d.ts

@@ -7,12 +7,17 @@ export interface JournaledMigration {
      *  (a re-run after a partial application completes rather than corrupts). */
     apply(db: DatabaseSync, canvasHome: string): void;
 }
+export interface ConvergentMigrationContext {
+    /** Frozen pre-cut directory-INDEX resolution for this store's owning memory
+     *  corpus. Null means rewriting the bare ref would not preserve meaning. */
+    legacyDirectoryIndex(name: string): string | null;
+}
 export interface ConvergentMigration {
     lane: 'convergent';
     description: string;
     /** Pure planning: return the full new text of each doc to rewrite. The
      *  runner filters no-op changes and performs the writes. */
-    apply(store: StoreSnapshot): DocChange[];
+    apply(store: StoreSnapshot, context?: ConvergentMigrationContext): DocChange[];
 }
 export type StateMigration = JournaledMigration | ConvergentMigration;
 /** One parsed markdown doc in a store snapshot. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.210",
+  "version": "0.3.212",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.210",
+  "version": "0.3.212",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.210",
+      "version": "0.3.212",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {