@north-light/crouter 0.3.227 → 0.3.229

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

@@ -1,10 +1,12 @@
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
-import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import test from 'node:test';
+import { parse as parseYaml } from 'yaml';
+import { onDiskMigrationIdentity } from '../../../migrations/registry.js';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const CLI = join(HERE, '../../../cli.ts');
 const TSX_LOADER = import.meta.resolve('tsx/esm');
@@ -20,10 +22,159 @@ kind: knowledge
 ---
 # Current format
 `;
+/** The exact bytes the superseded per-store migration 003 wrote when it created
+ *  a nested store's synthetic root index. A corpus that already carries one is
+ *  the second convergence start state, and the identity-only template is the
+ *  only nested index this cut is allowed to delete. */
+function supersededSyntheticIndex(namespace) {
+    return `---
+kind: knowledge
+namespace: ${namespace}
+when-and-why-to-read: When working in \`${namespace}\`, this knowledge should be read because it names the namespace every document in this project answers under.
+surfaces:
+  - on: workspace-open
+    at: content
+  - on: read
+    match: "./**"
+    at: content
+---
+# ${namespace}
+
+This project's memory store. Every document here answers at \`${namespace}/<local name>\`.
+`;
+}
 function write(path, content) {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, content);
 }
+/** Store keys and target ids are realpaths, so the fixture must be one too:
+ *  macOS hands `mkdtemp` a `/var/folders` path whose realpath is `/private/...`. */
+function fixtureHome(prefix) {
+    return realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+}
+/** Fixture git, with identity and signing pinned so the ambient user's global
+ *  config cannot fail a commit this test needs. */
+function git(cwd, ...args) {
+    const result = spawnSync('git', ['-c', 'user.email=test@example.com', '-c', 'user.name=Test', '-c', 'commit.gpgsign=false', ...args], { cwd, encoding: 'utf8' });
+    assert.equal(result.status, 0, `git ${args.join(' ')} in ${cwd}: ${result.stderr}`);
+}
+/** A git checkout with one commit — the minimum `git worktree add` needs. */
+function initRepo(dir) {
+    mkdirSync(dir, { recursive: true });
+    git(dir, 'init', '-b', 'main');
+    writeFileSync(join(dir, 'README.md'), '# fixture\n');
+    git(dir, 'add', 'README.md');
+    git(dir, 'commit', '-m', 'fixture');
+}
+function markerPath(home) {
+    return join(home, '.crouter', 'canvas', 'on-disk-migrations.json');
+}
+function readMarker(home) {
+    return JSON.parse(readFileSync(markerPath(home), 'utf8'));
+}
+/** Every file under `dir`, by path, so a run that must write NOTHING can be
+ *  proved byte for byte rather than by a changed counter. */
+function snapshotTree(dir) {
+    const files = new Map();
+    const walk = (current) => {
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            const path = join(current, entry.name);
+            if (entry.isDirectory())
+                walk(path);
+            else if (entry.isFile())
+                files.set(path, readFileSync(path, 'utf8'));
+        }
+    };
+    walk(dir);
+    return files;
+}
+/** The same tree keyed by home-relative path, with the home's own absolute path
+ *  replaced by a token in every file's bytes — a profile manifest stores project
+ *  paths absolutely — so two fixtures seeded in two temp homes can be compared
+ *  byte for byte. */
+function relativeTree(dir) {
+    const rebased = new Map();
+    for (const [path, content] of snapshotTree(dir))
+        rebased.set(relative(dir, path), content.split(dir).join('<home>'));
+    return rebased;
+}
+function assertTreeUnchanged(before, after) {
+    assert.deepEqual([...after.keys()].sort(), [...before.keys()].sort());
+    for (const [path, content] of before)
+        assert.equal(after.get(path), content, `${path} changed`);
+}
+/** A home the ambient node's own CRTR_* environment cannot leak into: every
+ *  crtr variable is dropped, so the fixture's canvas/profile/node state is the
+ *  only state the run can see. */
+function migrateEnv(home, profileId) {
+    const env = { ...process.env, HOME: home };
+    for (const key of Object.keys(env)) {
+        if (key.startsWith('CRTR_'))
+            delete env[key];
+    }
+    env['CRTR_PROFILE_ID'] = profileId;
+    env['CRTR_NO_AUTO_INIT'] = '1';
+    env['CRTR_NO_AUTO_UPDATE'] = '1';
+    return env;
+}
+function runMigrate(home, opts = {}) {
+    const result = spawnSync(process.execPath, [
+        '--conditions=crtr-src',
+        '--import',
+        TSX_LOADER,
+        CLI,
+        'sys',
+        'migrate',
+        '--json',
+        ...(opts.dryRun === true ? ['--dry-run'] : []),
+        ...(opts.dirs ?? []).flatMap((dir) => ['--dir', dir]),
+    ], { cwd: home, env: migrateEnv(home, opts.profileId ?? 'root-00000000'), encoding: 'utf8' });
+    return { status: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+function migrateJson(home, opts = {}) {
+    const result = runMigrate(home, opts);
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    const output = JSON.parse(result.stdout);
+    assertReportInvariants(output);
+    return output;
+}
+/** The report-schema rules every run obeys: a declaration is always the
+ *  repository root's own INDEX.md, a nested store's effective prefix is never
+ *  reported as one, and only a repository-root row can carry a front door. */
+function assertReportInvariants(output) {
+    const declarationRoots = new Set();
+    for (const row of output.repository_namespaces) {
+        assert.equal(row.declaration_path, join(row.repository_root, '.crouter', 'memory', 'INDEX.md'), 'a declaration path is always the repository root\'s own INDEX.md');
+        assert.equal(declarationRoots.has(row.repository_root), false, `two decisions for ${row.repository_root}`);
+        declarationRoots.add(row.repository_root);
+    }
+    const declaredNamespaces = new Set(output.repository_namespaces.map((row) => row.namespace));
+    for (const row of output.store_prefixes) {
+        if (row.owner_relative_path === '') {
+            assert.equal(row.owner_dir, row.repository_root);
+            continue;
+        }
+        assert.equal(row.front_door_action, 'none', `${row.store_root} is nested and cannot own a front door`);
+        assert.equal(declarationRoots.has(row.owner_dir), false, `${row.owner_dir} is nested, not a repository root`);
+        assert.equal(row.effective_prefix.endsWith(`/${row.owner_relative_path}`), true, `${row.effective_prefix} must compose the owner path`);
+        assert.equal(declaredNamespaces.has(row.effective_prefix), false, `${row.effective_prefix} is derived from a path, never a declaration`);
+    }
+}
+function repositoryRow(output, repositoryRoot) {
+    const row = output.repository_namespaces.find((candidate) => candidate.repository_root === repositoryRoot);
+    assert.ok(row, `no repository decision for ${repositoryRoot} in ${JSON.stringify(output.repository_namespaces)}`);
+    return row;
+}
+function prefixRow(output, ownerDir) {
+    const row = output.store_prefixes.find((candidate) => candidate.owner_dir === ownerDir);
+    assert.ok(row, `no store prefix for ${ownerDir} in ${JSON.stringify(output.store_prefixes)}`);
+    return row;
+}
+function migrateBlocked(home, opts = {}) {
+    const result = runMigrate(home, opts);
+    assert.notEqual(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    return JSON.parse(result.stdout);
+}
 function manifest(name, projects) {
     const first = projects[0];
     return JSON.stringify({
@@ -35,70 +186,1037 @@ function manifest(name, projects) {
         last_used_at: null,
     });
 }
-test('sys migrate converges profile manifests, then profile-aware refs and every descendant project/plugin store', () => {
-    const home = mkdtempSync(join(tmpdir(), 'crtr-sys-migrate-'));
+test('sys migrate converges manifests, documents, and the whole repository-root corpus', () => {
+    const home = fixtureHome('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 extraProject = join(home, 'extra-dir-project');
+    const deepOwner = join(appletProject, 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h');
+    const deepRoot = join(deepOwner, '.crouter');
     const pluginRoot = join(deepRoot, 'plugins', 'deep-memory');
     const embeddedPluginRoot = join(nestedOnlyProject, 'embedded', '.crouter', 'plugins', 'embedded-memory');
+    const disabledPluginRoot = join(userRoot, 'plugins', 'disabled-memory');
+    const nodeId = 'node-aaaa1111';
+    const nodeStore = join(userRoot, 'canvas', 'nodes', nodeId, 'context', 'memory');
     const userDoc = join(userRoot, 'memory', 'user-link.md');
     const rootDoc = join(rootProfile, 'memory', 'root.md');
     const appletDoc = join(appletProfile, 'memory', 'identity.md');
+    const projectIndex = join(appletProject, '.crouter', 'memory', 'INDEX.md');
     const projectDoc = join(appletProject, '.crouter', 'memory', 'project.md');
+    const projectPlain = join(appletProject, '.crouter', 'memory', 'plain.md');
+    const projectReference = join(appletProject, '.crouter', 'memory', 'notes', 'reference.md');
     const deepDoc = join(deepRoot, 'memory', 'deep.md');
+    const deepIndex = join(deepRoot, 'memory', 'INDEX.md');
     const pluginDoc = join(pluginRoot, 'memory', 'plugin.md');
     const embeddedPluginDoc = join(embeddedPluginRoot, 'memory', 'plugin.md');
+    const disabledPluginDoc = join(disabledPluginRoot, 'memory', 'guide.md');
+    const nodeDoc = join(nodeStore, 'note.md');
     try {
         // Root's string entries migrate to `preview`; every other profile's to
         // `content`. The applet manifest is mixed: its already-current entry must
         // survive untouched while the string beside it converts.
         write(join(rootProfile, 'profile.json'), manifest('root', [appletProject]));
         write(join(appletProfile, 'profile.json'), manifest('applet-inactive', [{ path: appletProject, memory: 'name' }, nestedOnlyProject]));
+        // User store: `[[user/scoped]]` names no document under either identity
+        // rule, so it is a pre-existing dangling link the cut never touches.
         write(userDoc, `${OLD_DOC}\nSee [[user/scoped]].\n`);
         write(join(userRoot, 'memory', 'scoped', 'INDEX.md'), CURRENT_DOC);
-        write(rootDoc, `${OLD_DOC}\nSee [[shared]].\n`);
+        // Root profile store: an INDEX spelling to collapse, an unqualified project
+        // name to qualify, and a name its own target stack cannot see.
+        write(rootDoc, `${OLD_DOC}\nSee [[notes/INDEX]], [[project]], and [[shared]].\n`);
+        write(join(rootProfile, 'memory', 'notes', 'INDEX.md'), CURRENT_DOC);
         write(appletDoc, `${OLD_DOC}\nSee [[shared]].\n`);
         write(join(appletProfile, 'memory', 'shared', 'INDEX.md'), CURRENT_DOC);
+        // Repository-root store: a root document that gains the repository
+        // declaration AND carries both a link and a route rewrite, so one file
+        // lands in both write phases; an explicit name to strip; a redundant
+        // explicit name to drop. The route's `match:` is a BLOCK SEQUENCE: this root
+        // owes a front door, and completing one re-renders the whole `surfaces:`
+        // list, so the translated glob must survive that round trip.
+        write(projectIndex, `---
+kind: knowledge
+surfaces:
+  - on: memory-read
+    match:
+      - topics/*
+    at: content
+---
+# Applet Project
+
+See [[project]].
+`);
         write(projectDoc, OLD_DOC);
         write(join(appletProject, '.crouter', 'memory', 'scoped', 'INDEX.md'), CURRENT_DOC);
+        write(projectPlain, `---\nkind: knowledge\nname: plain\n---\n# Redundant name\n`);
+        // A FOLDED explicit name: its value spans two lines, so rewriting it must
+        // stop at the value's last character and leave the next key standing.
+        write(projectReference, `---\nname: >-\n  applet-project/reference\nkind: knowledge\n---\n# Namespaced name\n`);
+        write(join(appletProject, '.crouter', 'memory', 'topics', 'one.md'), CURRENT_DOC);
+        write(join(appletProject, '.crouter', 'memory', 'topics', 'two.md'), CURRENT_DOC);
+        // A nested store eight directories below the repository root: it declares
+        // nothing, needs no root index, and answers under the repository namespace
+        // composed with its own path.
         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);
+        // A DISABLED plugin: no target mounts it, so its references resolve against
+        // its own store alone — and it is still migrated.
+        write(join(userRoot, 'config.json'), JSON.stringify({ plugins: { 'disabled-memory': { enabled: false } } }));
+        write(join(disabledPluginRoot, '.crouter-plugin', 'plugin.json'), JSON.stringify({ name: 'disabled-memory', version: '1.0.0' }));
+        write(join(disabledPluginRoot, 'memory', 'notes', 'INDEX.md'), CURRENT_DOC);
+        write(disabledPluginDoc, `${CURRENT_DOC}\nSee [[disabled-memory/notes/INDEX]].\n`);
+        // A node store plus the durable meta.json the corpus reads with no daemon.
+        write(join(userRoot, 'canvas', 'nodes', nodeId, 'meta.json'), JSON.stringify({ node_id: nodeId, cwd: appletProject, profile_id: 'applet-deadbeef', kind: 'developer' }));
+        write(nodeDoc, `${CURRENT_DOC}\nSee [[project]].\n`);
+        // Reached by --dir only: no manifest names it and it is under no discovered
+        // project root. Its `name:` is the FIRST frontmatter key, so the removal and
+        // the `namespace:` insert share one offset — the shape that corrupts the
+        // file if the two splices apply in the wrong order.
+        write(join(extraProject, '.crouter', 'memory', 'INDEX.md'), `---\nname: extra-dir-project\nkind: knowledge\n---\n# Extra Dir Project\n`);
+        write(join(extraProject, '.crouter', 'memory', 'topic.md'), CURRENT_DOC);
+        const invisible = migrateJson(home, { dryRun: true });
+        assert.equal(existsSync(markerPath(home)), false);
+        assert.equal(invisible.discovered_stores.some((row) => row.store.startsWith(extraProject)), false, 'the --dir project must be outside the ambient discovery frontier');
+        const output = migrateJson(home, { dirs: [extraProject] });
+        assert.deepEqual(readMarker(home), onDiskMigrationIdentity());
         assert.equal(output.profiles, 2);
-        assert.equal(output.stores, 7);
-        assert.equal(output.changed, 9);
+        assert.equal(output.stores, 11);
+        assert.equal(output.blockers.length, 0);
+        // 002 — profile manifests.
         const readProjects = (dir) => JSON.parse(readFileSync(join(dir, 'profile.json'), 'utf8')).projects;
         assert.deepEqual(readProjects(rootProfile), [{ path: appletProject, memory: 'preview' }]);
         assert.deepEqual(readProjects(appletProfile), [
             { path: appletProject, memory: 'name' },
             { path: nestedOnlyProject, memory: 'content' },
         ]);
+        // 001 — every old-format document, in every store kind, converged.
         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\]\]/);
+        // Durable node metadata, read with no daemon.
+        assert.deepEqual(output.node_metadata, { available: true, nodes: 1 });
+        const nodeTarget = output.discovered_targets.find((row) => row.kind === 'node');
+        assert.equal(nodeTarget?.node_id, nodeId);
+        assert.equal(nodeTarget?.origin, nodeId);
+        // A disabled plugin: discovered, mounted by no target, migrated anyway.
+        const disabledStore = output.discovered_stores.find((row) => row.store.startsWith(disabledPluginRoot));
+        assert.equal(disabledStore?.writable, true);
+        assert.deepEqual(disabledStore?.targets, []);
+        assert.match(readFileSync(disabledPluginDoc, 'utf8'), /\[\[disabled-memory\/notes\]\]/);
+        // The --dir project entered discovery as an explicit root, and is its own
+        // repository: home is fenced out of the non-git ancestor walk.
+        const extraStore = output.discovered_stores.find((row) => row.store.startsWith(extraProject));
+        assert.equal(extraStore?.reasons.includes('explicit-dir'), true);
+        assert.deepEqual(repositoryRow(output, extraProject), {
+            repository_root: extraProject,
+            repository_key: `path:${extraProject}`,
+            declaration_path: join(extraProject, '.crouter', 'memory', 'INDEX.md'),
+            namespace: 'extra-dir-project',
+            source: 'root-name',
+            action: 'kept',
+        });
+        // The declaration replaces the first-key `name:`, byte for byte, and the
+        // root gains the front door the repository owes.
+        assert.equal(readFileSync(join(extraProject, '.crouter', 'memory', 'INDEX.md'), 'utf8'), `---
+namespace: extra-dir-project
+kind: knowledge
+surfaces:
+  - on: workspace-open
+    at: content
+  - on: read
+    match: ./**
+    at: content
+---
+# Extra Dir Project
+`);
+        // ONE repository decision for the applet repository, derived from the root
+        // guide's H1 — the eight-deep descendant store adds no second decision.
+        assert.deepEqual(output.repository_namespaces.filter((row) => row.repository_root.startsWith(appletProject)), [
+            {
+                repository_root: appletProject,
+                repository_key: `path:${appletProject}`,
+                declaration_path: projectIndex,
+                namespace: 'applet-project',
+                source: 'root-guide-h1',
+                action: 'kept',
+            },
+        ]);
+        // One store-prefix row per project store: the repository root at `''`, the
+        // descendant at its normalized path under it. Plugin, user, profile, and
+        // node stores are not project stores and carry no row.
+        assert.deepEqual(output.store_prefixes.map((row) => [row.owner_dir, row.owner_relative_path, row.effective_prefix, row.front_door_action]).sort(), [
+            [appletProject, '', 'applet-project', 'created-root'],
+            [deepOwner, 'a/b/c/d/e/f/g/h', 'applet-project/a/b/c/d/e/f/g/h', 'none'],
+            [extraProject, '', 'extra-dir-project', 'created-root'],
+        ].sort());
+        assert.equal(prefixRow(output, deepOwner).nested_declaration_action, 'none');
+        assert.equal(prefixRow(output, deepOwner).old_rule, 'pre-003');
+        // A nested store owes no root index and is never handed a synthetic one.
+        assert.equal(existsSync(deepIndex), false);
+        // Discovery reports each store as the run FOUND it: before this cut nothing
+        // up the tree declares a namespace, so the deep store mounts nowhere.
+        const deepStoreBefore = output.discovered_stores.find((row) => row.store === join(deepRoot, 'memory'));
+        assert.equal(deepStoreBefore?.namespace, '');
+        assert.equal(deepStoreBefore?.mount_status, 'undeclared');
+        assert.equal(output.renames.some((row) => row.path === deepDoc && row.from === 'deep' && row.to === 'applet-project/a/b/c/d/e/f/g/h/deep'), true, JSON.stringify(output.renames));
+        // Identity rewrites in the repository-root store.
+        const projectIndexText = readFileSync(projectIndex, 'utf8');
+        assert.match(projectIndexText, /^---\nnamespace: applet-project\n/);
+        assert.equal(readFileSync(projectPlain, 'utf8'), `---\nkind: knowledge\n---\n# Redundant name\n`);
+        assert.equal(readFileSync(projectReference, 'utf8'), `---\nname: reference\nkind: knowledge\n---\n# Namespaced name\n`);
+        assert.equal(output.renames.some((row) => row.path === projectDoc && row.from === 'project' && row.to === 'applet-project/project'), true);
+        // Reference rewrites: qualification across stores, one INDEX collapse, and
+        // an absolute memory-read route split-proof — the route and the link ride
+        // the same file as its own identity rewrite and its own front-door
+        // completion.
+        const rootDocText = readFileSync(rootDoc, 'utf8');
+        assert.match(rootDocText, /\[\[notes\]\]/);
+        assert.match(rootDocText, /\[\[applet-project\/project\]\]/);
+        assert.match(rootDocText, /\[\[shared\]\]/);
+        assert.match(readFileSync(userDoc, 'utf8'), /\[\[user\/scoped\]\]/);
+        assert.match(readFileSync(appletDoc, 'utf8'), /\[\[shared\]\]/);
+        assert.match(readFileSync(nodeDoc, 'utf8'), /\[\[applet-project\/project\]\]/);
+        assert.equal(projectIndexText, `---
+namespace: applet-project
+kind: knowledge
+surfaces:
+  - on: memory-read
+    match: applet-project/topics/*
+    at: content
+  - on: workspace-open
+    at: content
+  - on: read
+    match: ./**
+    at: content
+---
+# Applet Project
+
+See [[applet-project/project]].
+`);
+        assert.equal(output.references.some((row) => row.kind === 'memory-read' && row.from === 'topics/*' && row.to === 'applet-project/topics/*'), true);
+        // A second run over converged state writes nothing.
+        const converged = snapshotTree(home);
+        // A no-change forced run still replaces an outdated completion marker.
+        writeFileSync(markerPath(home), JSON.stringify([{ id: 'older-migration', lane: 'convergent' }]));
+        const second = migrateJson(home, { dirs: [extraProject] });
+        assert.equal(second.changed, 0);
+        assert.deepEqual(readMarker(home), onDiskMigrationIdentity());
+        assert.deepEqual(second.applied, []);
+        assert.deepEqual(second.references, []);
+        // The old side is reconstructed from FILE TRUTH alone, and a cut corpus is
+        // final authority, not old authority: the repository root's kept declaration
+        // is what the deep store already answers under, and no document there
+        // carries an explicit name this cut would rewrite. So the deep store's row
+        // reports that same prefix as its old one and NOTHING moves — no rename, no
+        // reference rewrite, no splice, and a byte-identical tree.
+        assert.deepEqual(second.renames, []);
+        assert.equal(prefixRow(second, deepOwner).old_rule, 'per-store-declaration');
+        assert.equal(prefixRow(second, deepOwner).old_prefix, 'applet-project/a/b/c/d/e/f/g/h');
+        assert.equal(repositoryRow(second, appletProject).source, 'declared');
+        assert.equal(prefixRow(second, appletProject).front_door_action, 'kept-root');
+        // The runtime resolver composes exactly the prefix the migration reported:
+        // the deep store now mounts under the repository namespace plus its path.
+        const deepStoreAfter = second.discovered_stores.find((row) => row.store === join(deepRoot, 'memory'));
+        assert.equal(deepStoreAfter?.namespace, 'applet-project/a/b/c/d/e/f/g/h');
+        assert.equal(deepStoreAfter?.mount_status, 'ready');
+        assertTreeUnchanged(converged, snapshotTree(home));
+        const currentMarker = readFileSync(markerPath(home), 'utf8');
+        const preview = migrateJson(home, { dirs: [extraProject], dryRun: true });
+        assert.equal(preview.changed, 0);
+        assert.equal(readFileSync(markerPath(home), 'utf8'), currentMarker);
+        // Interruption-shaped state under a current marker: the explicit command
+        // must still finish the cut from file truth alone.
+        writeFileSync(projectIndex, projectIndexText.replace('namespace: applet-project\n', ''));
+        writeFileSync(projectPlain, readFileSync(projectPlain, 'utf8').replace('kind: knowledge\n', 'kind: knowledge\nname: plain\n'));
+        const resumed = migrateJson(home, { dirs: [extraProject] });
+        assert.equal(resumed.blockers.length, 0);
+        assert.deepEqual(readMarker(home), onDiskMigrationIdentity());
+        assertTreeUnchanged(converged, snapshotTree(home));
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+/** The identity state a corpus can start from: never migrated at all, or
+ *  carrying the superseded per-store 003 output plus its completion marker. */
+function seedConvergenceFixture(home, start) {
+    const userRoot = join(home, '.crouter');
+    const rootProfile = join(userRoot, 'profiles', 'root-00000000');
+    const project = join(home, 'conv-project');
+    const nestedOwner = join(project, 'pkg');
+    write(join(rootProfile, 'profile.json'), manifest('root', [{ path: project, memory: 'content' }]));
+    write(join(project, '.crouter', 'memory', 'guide.md'), CURRENT_DOC);
+    write(join(nestedOwner, '.crouter', 'memory', 'note.md'), CURRENT_DOC);
+    if (start === 'pre-003') {
+        // Nothing declares a namespace, so both documents answer under their own
+        // local names and the user store's links name them that way.
+        write(join(userRoot, 'memory', 'pointer.md'), `${CURRENT_DOC}\nSee [[guide]] and [[note]].\n`);
+        write(join(project, '.crouter', 'memory', 'INDEX.md'), `---\nkind: knowledge\n---\n# Conv Project\n`);
+        return;
+    }
+    // Exactly what the superseded migration wrote: a per-store declaration on the
+    // repository root, a synthetic identity-only index on the nested store whose
+    // namespace is its own bare directory name, the links it translated to those
+    // two per-store prefixes, and the old id in the completion marker.
+    write(join(userRoot, 'memory', 'pointer.md'), `${CURRENT_DOC}\nSee [[conv-project/guide]] and [[pkg/note]].\n`);
+    write(join(project, '.crouter', 'memory', 'INDEX.md'), `---\nnamespace: conv-project\nkind: knowledge\n---\n# Conv Project\n`);
+    write(join(nestedOwner, '.crouter', 'memory', 'INDEX.md'), supersededSyntheticIndex('pkg'));
+    write(markerPath(home), JSON.stringify([{ id: '003-workspace-qualified-memory-identity', lane: 'corpus' }]));
+}
+test('pre-003 and superseded-003 corpora converge to the same bytes and the same current marker', () => {
+    const preHome = fixtureHome('crtr-sys-migrate-conv-pre-');
+    const oldHome = fixtureHome('crtr-sys-migrate-conv-old-');
+    try {
+        seedConvergenceFixture(preHome, 'pre-003');
+        seedConvergenceFixture(oldHome, 'superseded-003');
+        const fromPre = migrateJson(preHome);
+        const fromOld = migrateJson(oldHome);
+        assert.deepEqual(fromPre.blockers, []);
+        assert.deepEqual(fromOld.blockers, []);
+        assert.deepEqual(readMarker(preHome), onDiskMigrationIdentity());
+        assert.deepEqual(readMarker(oldHome), onDiskMigrationIdentity());
+        // The superseded run's synthetic nested index is identity-only and is
+        // deleted, not emptied — so both corpora hold the same files.
+        assert.equal(existsSync(join(oldHome, 'conv-project', 'pkg', '.crouter', 'memory', 'INDEX.md')), false);
+        assertTreeUnchanged(relativeTree(preHome), relativeTree(oldHome));
+        // Both start states' links land on the one composed name: the local name the
+        // pre-003 corpus used and the bare per-store prefix the superseded one used
+        // are the SAME document, and it now answers under the repository.
+        assert.equal(readFileSync(join(preHome, '.crouter', 'memory', 'pointer.md'), 'utf8'), `${CURRENT_DOC}\nSee [[conv-project/guide]] and [[conv-project/pkg/note]].\n`);
+        // Both report the same identity facts even though they started differently,
+        // and each proves the move its own legacy state owed: the nested document
+        // answered at a bare local name pre-003 and at its own per-store declaration
+        // after the superseded run, and lands on the repository-composed name from
+        // either. The second run over that finished corpus is the convergence proof
+        // — nothing moved, so nothing is renamed or rewritten.
+        for (const [home, output, oldRule, nestedOldName] of [
+            [preHome, fromPre, 'pre-003', 'note'],
+            [oldHome, fromOld, 'per-store-declaration', 'pkg/note'],
+        ]) {
+            const project = join(home, 'conv-project');
+            assert.equal(repositoryRow(output, project).namespace, 'conv-project');
+            assert.equal(prefixRow(output, join(project, 'pkg')).effective_prefix, 'conv-project/pkg');
+            assert.equal(prefixRow(output, join(project, 'pkg')).old_rule, oldRule);
+            assert.equal(output.renames.some((row) => row.path === join(project, 'pkg', '.crouter', 'memory', 'note.md') &&
+                row.from === nestedOldName &&
+                row.to === 'conv-project/pkg/note'), true, JSON.stringify(output.renames));
+            const converged = snapshotTree(home);
+            const secondRun = migrateJson(home);
+            assert.equal(secondRun.changed, 0);
+            assert.deepEqual(secondRun.renames, []);
+            assert.deepEqual(secondRun.references, []);
+            assertTreeUnchanged(converged, snapshotTree(home));
+        }
+        assert.equal(prefixRow(fromOld, join(oldHome, 'conv-project', 'pkg')).nested_declaration_action, 'synthetic-index-removed');
+        assert.equal(prefixRow(fromPre, join(preHome, 'conv-project', 'pkg')).nested_declaration_action, 'none');
+    }
+    finally {
+        rmSync(preHome, { recursive: true, force: true });
+        rmSync(oldHome, { recursive: true, force: true });
+    }
+});
+test('a repository declaration is kept when declared, derived from the root guide, or created when no root index exists', () => {
+    const home = fixtureHome('crtr-sys-migrate-decisions-');
+    const rootProfile = join(home, '.crouter', 'profiles', 'root-00000000');
+    const kept = join(home, 'kept-project');
+    const derived = join(home, 'derived-project');
+    const created = join(home, 'created-project');
+    try {
+        write(join(rootProfile, 'profile.json'), manifest('root', [kept, derived, created].map((path) => ({ path, memory: 'content' }))));
+        write(join(kept, '.crouter', 'memory', 'INDEX.md'), `---\nnamespace: kept-ns\nkind: knowledge\n---\n# Kept\n`);
+        write(join(kept, '.crouter', 'memory', 'note.md'), CURRENT_DOC);
+        write(join(derived, '.crouter', 'memory', 'INDEX.md'), `---\nkind: knowledge\n---\n# Derived Title\n`);
+        // No root index at all: the declaration is created rather than edited.
+        write(join(created, '.crouter', 'memory', 'note.md'), CURRENT_DOC);
+        const output = migrateJson(home);
+        assert.deepEqual(output.blockers, []);
+        assert.deepEqual(output.repository_namespaces.map((row) => [row.repository_root, row.namespace, row.source, row.action]).sort(), [
+            [created, 'created-project', 'owner-basename', 'created'],
+            [derived, 'derived-title', 'root-guide-h1', 'kept'],
+            [kept, 'kept-ns', 'declared', 'kept'],
+        ].sort());
+        assert.equal(readFileSync(join(kept, '.crouter', 'memory', 'INDEX.md'), 'utf8').startsWith('---\nnamespace: kept-ns\n'), true, 'a valid declaration is never rewritten');
+        assert.equal(readFileSync(join(created, '.crouter', 'memory', 'INDEX.md'), 'utf8'), `---
+namespace: "created-project"
+kind: knowledge
+when-and-why-to-read: When working in \`created-project\`, this knowledge should be read because it names the namespace every document in this repository answers under.
+surfaces:
+  - on: workspace-open
+    at: content
+  - on: read
+    match: "./**"
+    at: content
+---
+
+# created-project
+
+This project's memory store. Every document here answers at \`created-project/<local name>\`.
+`);
+        assert.equal(migrateJson(home).changed, 0);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test('a git repository whose only stores are descendants gets its repository-root declaration created', () => {
+    const home = fixtureHome('crtr-sys-migrate-git-descendant-');
+    const rootProfile = join(home, '.crouter', 'profiles', 'root-00000000');
+    const repo = join(home, 'pkg-repo');
+    const nestedOwner = join(repo, 'pkg');
+    try {
+        write(join(rootProfile, 'profile.json'), manifest('root', [{ path: repo, memory: 'content' }]));
+        initRepo(repo);
+        write(join(nestedOwner, '.crouter', 'memory', 'note.md'), CURRENT_DOC);
+        const output = migrateJson(home);
+        assert.deepEqual(output.blockers, []);
+        assert.deepEqual(output.repository_namespaces, [
+            {
+                repository_root: repo,
+                repository_key: `git:${join(repo, '.git')}`,
+                declaration_path: join(repo, '.crouter', 'memory', 'INDEX.md'),
+                namespace: 'pkg-repo',
+                source: 'git-worktree',
+                action: 'created',
+            },
+        ]);
+        assert.deepEqual(output.store_prefixes.map((row) => [row.owner_dir, row.owner_relative_path, row.effective_prefix]), [[nestedOwner, 'pkg', 'pkg-repo/pkg']]);
+        assert.match(readFileSync(join(repo, '.crouter', 'memory', 'INDEX.md'), 'utf8'), /^---\nnamespace: "pkg-repo"\n/);
+        assert.equal(output.renames.some((row) => row.from === 'note' && row.to === 'pkg-repo/pkg/note'), true, JSON.stringify(output.renames));
+        assert.equal(migrateJson(home).changed, 0);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test('linked worktrees agree on one declaration, and a linked root missing one is filled from it', () => {
+    for (const mode of ['agree', 'fill']) {
+        const home = fixtureHome(`crtr-sys-migrate-worktree-${mode}-`);
+        const rootProfile = join(home, '.crouter', 'profiles', 'root-00000000');
+        const main = join(home, 'shared-main');
+        const linked = join(home, 'shared-linked');
+        try {
+            write(join(rootProfile, 'profile.json'), manifest('root', [main, linked].map((path) => ({ path, memory: 'content' }))));
+            initRepo(main);
+            git(main, 'worktree', 'add', linked, '-b', 'linked');
+            // Written after the worktree exists, so each checkout carries its own
+            // untracked declaration rather than a copy of the other's.
+            write(join(main, '.crouter', 'memory', 'INDEX.md'), `---\nnamespace: shared-code\nkind: knowledge\n---\n# Shared\n`);
+            write(join(main, '.crouter', 'memory', 'note.md'), CURRENT_DOC);
+            write(join(linked, '.crouter', 'memory', 'INDEX.md'), mode === 'agree'
+                ? `---\nnamespace: shared-code\nkind: knowledge\n---\n# Shared\n`
+                : `---\nkind: knowledge\n---\n# Shared\n`);
+            const output = migrateJson(home);
+            assert.deepEqual(output.blockers, []);
+            const mainRow = repositoryRow(output, main);
+            const linkedRow = repositoryRow(output, linked);
+            // One repository key, two physical roots, one namespace.
+            assert.equal(mainRow.repository_key, `git:${join(main, '.git')}`);
+            assert.equal(linkedRow.repository_key, mainRow.repository_key);
+            assert.equal(mainRow.namespace, 'shared-code');
+            assert.equal(linkedRow.namespace, 'shared-code');
+            assert.equal(mainRow.action, 'kept');
+            assert.equal(linkedRow.action, mode === 'agree' ? 'kept' : 'filled-linked-root');
+            assert.match(readFileSync(join(linked, '.crouter', 'memory', 'INDEX.md'), 'utf8'), /^---\nnamespace: shared-code\n/);
+            assert.equal(migrateJson(home).changed, 0);
+        }
+        finally {
+            rmSync(home, { recursive: true, force: true });
+        }
+    }
+});
+test('linked worktree roots declaring different namespaces block the corpus', () => {
+    const home = fixtureHome('crtr-sys-migrate-worktree-conflict-');
+    const rootProfile = join(home, '.crouter', 'profiles', 'root-00000000');
+    const main = join(home, 'shared-main');
+    const linked = join(home, 'shared-linked');
+    try {
+        write(join(rootProfile, 'profile.json'), manifest('root', [main, linked].map((path) => ({ path, memory: 'content' }))));
+        initRepo(main);
+        git(main, 'worktree', 'add', linked, '-b', 'linked');
+        write(join(main, '.crouter', 'memory', 'INDEX.md'), `---\nnamespace: main-ns\nkind: knowledge\n---\n# Shared\n`);
+        write(join(linked, '.crouter', 'memory', 'INDEX.md'), `---\nnamespace: linked-ns\nkind: knowledge\n---\n# Shared\n`);
+        const before = snapshotTree(main);
+        const payload = migrateBlocked(home);
+        const blocker = payload.received.blockers.find((row) => /declare different namespaces/.test(row.message));
+        assert.ok(blocker, JSON.stringify(payload.received.blockers));
+        assert.equal(blocker.kind, 'namespace');
+        assert.deepEqual(blocker.paths?.sort(), [
+            join(linked, '.crouter', 'memory', 'INDEX.md'),
+            join(main, '.crouter', 'memory', 'INDEX.md'),
+        ].sort());
+        assert.equal(payload.received.corpus_phase, 'not-started');
+        assertTreeUnchanged(before, snapshotTree(main));
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test('a nested declaration is removed, an exact synthetic index is deleted, and a substantive one is kept', () => {
+    const home = fixtureHome('crtr-sys-migrate-nested-declarations-');
+    const rootProfile = join(home, '.crouter', 'profiles', 'root-00000000');
+    const project = join(home, 'nest-repo');
+    const syntheticOwner = join(project, 'syn');
+    const substantiveOwner = join(project, 'sub');
+    const syntheticIndex = join(syntheticOwner, '.crouter', 'memory', 'INDEX.md');
+    const substantiveIndex = join(substantiveOwner, '.crouter', 'memory', 'INDEX.md');
+    try {
+        write(join(rootProfile, 'profile.json'), manifest('root', [{ path: project, memory: 'content' }]));
+        write(join(project, '.crouter', 'memory', 'INDEX.md'), `---\nnamespace: nest-repo\nkind: knowledge\n---\n# Nest Repo\n`);
+        write(syntheticIndex, supersededSyntheticIndex('syn'));
+        write(join(syntheticOwner, '.crouter', 'memory', 'note.md'), CURRENT_DOC);
+        write(substantiveIndex, `---\nnamespace: sub\nkind: knowledge\n---\n# Sub package\n\nReal guidance a reader loses if this file is deleted.\n`);
+        const output = migrateJson(home);
+        assert.deepEqual(output.blockers, []);
+        assert.equal(prefixRow(output, syntheticOwner).nested_declaration_action, 'synthetic-index-removed');
+        assert.equal(prefixRow(output, substantiveOwner).nested_declaration_action, 'removed');
+        assert.equal(existsSync(syntheticIndex), false, 'the identity-only template is deleted, not emptied');
+        assert.equal(readFileSync(substantiveIndex, 'utf8'), `---\nkind: knowledge\n---\n# Sub package\n\nReal guidance a reader loses if this file is deleted.\n`);
+        assert.equal(output.renames.some((row) => row.from === 'syn/note' && row.to === 'nest-repo/syn/note'), true, JSON.stringify(output.renames));
+        assert.equal(output.renames.some((row) => row.path === substantiveIndex && row.from === 'sub' && row.to === 'nest-repo/sub'), true, JSON.stringify(output.renames));
+        assert.equal(migrateJson(home).changed, 0);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test('a rootless repository takes its front door from the one legacy guide that owns it', () => {
+    const home = fixtureHome('crtr-sys-migrate-front-door-');
+    const rootProfile = join(home, '.crouter', 'profiles', 'root-00000000');
+    const project = join(home, 'fd-root');
+    const guide = join(project, '.crouter', 'memory', 'guide.md');
+    const rootIndex = join(project, '.crouter', 'memory', 'INDEX.md');
+    try {
+        write(join(rootProfile, 'profile.json'), manifest('root', [{ path: project, memory: 'content' }]));
+        write(guide, `---
+kind: knowledge
+name: project-guide
+surfaces:
+  - on: workspace-open
+    at: content
+  - on: read
+    match: "./**"
+    at: content
+---
+# FD Root guide
+
+The authored body, preserved byte for byte.
+`);
+        const output = migrateJson(home);
+        assert.deepEqual(output.blockers, []);
+        assert.equal(repositoryRow(output, project).action, 'created');
+        assert.equal(prefixRow(output, project).front_door_action, 'transferred-from:.crouter/memory/guide.md');
+        // The created root links the leaf's FINAL canonical name.
+        assert.equal(readFileSync(rootIndex, 'utf8'), `---
+namespace: "fd-root"
+kind: knowledge
+when-and-why-to-read: When working in \`fd-root\`, this knowledge should be read because it names the namespace every document in this repository answers under.
+surfaces:
+  - on: workspace-open
+    at: content
+  - on: read
+    match: "./**"
+    at: content
+---
+
+# fd-root
+
+This project's memory store. Every document here answers at \`fd-root/<local name>\`. Read [[fd-root/project-guide]] for the detailed project guide.
+`);
+        // The leaf keeps its path, local name, read route, and body — only the
+        // workspace-open entry leaves.
+        assert.equal(readFileSync(guide, 'utf8'), `---
+kind: knowledge
+name: project-guide
+surfaces:
+  - on: read
+    match: "./**"
+    at: content
+---
+# FD Root guide
+
+The authored body, preserved byte for byte.
+`);
+        const converged = snapshotTree(home);
+        const second = migrateJson(home);
+        assert.equal(second.changed, 0);
+        assert.equal(prefixRow(second, project).front_door_action, 'kept-root');
+        assertTreeUnchanged(converged, snapshotTree(home));
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test('repository-relative ordering prefixes do not block migration and derive canonical owner paths', () => {
+    const home = fixtureHome('crtr-sys-migrate-ordering-prefix-');
+    const rootProfile = join(home, '.crouter', 'profiles', 'root-00000000');
+    const repository = join(home, 'ordered-repository');
+    const nestedOwner = join(repository, '01-api');
+    const rootIndex = join(repository, '.crouter', 'memory', 'INDEX.md');
+    const nestedDoc = join(nestedOwner, '.crouter', 'memory', 'guide.md');
+    try {
+        initRepo(repository);
+        write(join(rootProfile, 'profile.json'), manifest('root', [{ path: repository, memory: 'content' }]));
+        write(rootIndex, '---\nnamespace: acme\nkind: knowledge\n---\n# Repository\n');
+        write(nestedDoc, '---\nkind: knowledge\n---\n# API guide\n');
+        const output = migrateJson(home);
+        assert.deepEqual(output.blockers, []);
+        assert.equal(prefixRow(output, nestedOwner).owner_relative_path, 'api');
+        assert.equal(prefixRow(output, nestedOwner).effective_prefix, 'acme/api');
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test('the legacy front door is found in a nested store of the same repository, and a half-done transfer finishes', () => {
+    const home = fixtureHome('crtr-sys-migrate-front-door-nested-');
+    const rootProfile = join(home, '.crouter', 'profiles', 'root-00000000');
+    const project = join(home, 'fd-nested');
+    const nestedOwner = join(project, 'pkg');
+    const rootIndex = join(project, '.crouter', 'memory', 'INDEX.md');
+    const guide = join(nestedOwner, '.crouter', 'memory', 'guide.md');
+    const legacyNamed = join(nestedOwner, '.crouter', 'memory', 'deep-note.md');
+    try {
+        write(join(rootProfile, 'profile.json'), manifest('root', [{ path: project, memory: 'content' }]));
+        write(rootIndex, `---\nnamespace: fd-nested\nkind: knowledge\n---\n# FD Nested\n`);
+        write(guide, `---
+kind: knowledge
+surfaces:
+  - on: workspace-open
+    at: content
+  - on: read
+    match: "./**"
+    at: content
+---
+# Nested guide
+`);
+        // The nested store declares nothing under a root that already does — the
+        // shape a cut corpus is also in. This fully qualified `name:` is one this
+        // cut never leaves behind, so it proves the store is still pre-003 and its
+        // documents answered at bare local names.
+        write(legacyNamed, `---\nname: fd-nested/pkg/legacy-note\nkind: knowledge\n---\n# Legacy named\n`);
+        const output = migrateJson(home);
+        assert.deepEqual(output.blockers, []);
+        assert.equal(prefixRow(output, project).front_door_action, 'transferred-from:pkg/.crouter/memory/guide.md');
+        assert.equal(prefixRow(output, nestedOwner).front_door_action, 'none');
+        assert.equal(prefixRow(output, nestedOwner).old_rule, 'pre-003');
+        assert.equal(output.renames.some((row) => row.path === guide && row.from === 'guide' && row.to === 'fd-nested/pkg/guide'), true, JSON.stringify(output.renames));
+        // Its address never moved — only the spelling of the name that carried it.
+        assert.equal(output.renames.some((row) => row.path === legacyNamed), false, JSON.stringify(output.renames));
+        assert.equal(readFileSync(legacyNamed, 'utf8'), `---\nname: legacy-note\nkind: knowledge\n---\n# Legacy named\n`);
+        // The repository root now carries the door; the nested leaf keeps its own
+        // owner-anchored read route.
+        assert.match(readFileSync(rootIndex, 'utf8'), /surfaces:\n {2}- on: workspace-open\n {4}at: content\n/);
+        assert.equal(readFileSync(guide, 'utf8'), `---
+kind: knowledge
+surfaces:
+  - on: read
+    match: "./**"
+    at: content
+---
+# Nested guide
+`);
+        // Nothing legacy is left in the nested store, so the second run reads the
+        // root declaration it already answers under as its old prefix too.
+        const second = migrateJson(home);
+        assert.equal(second.changed, 0);
+        assert.deepEqual(second.renames, []);
+        assert.equal(prefixRow(second, nestedOwner).old_rule, 'per-store-declaration');
+        assert.equal(prefixRow(second, nestedOwner).old_prefix, 'fd-nested/pkg');
+        // Interruption shape: the root already owns the pair while the leaf still
+        // carries workspace-open. State is read from the two documents alone, so
+        // the run re-detects the transfer and finishes it.
+        write(guide, `---
+kind: knowledge
+surfaces:
+  - on: workspace-open
+    at: content
+  - on: read
+    match: "./**"
+    at: content
+---
+# Nested guide
+`);
+        const resumed = migrateJson(home);
+        assert.deepEqual(resumed.blockers, []);
+        assert.equal(prefixRow(resumed, project).front_door_action, 'transferred-from:pkg/.crouter/memory/guide.md');
+        assert.doesNotMatch(readFileSync(guide, 'utf8'), /workspace-open/);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test('two legacy front doors, and a root workspace-open that is not at content, each block the corpus', () => {
+    for (const shape of ['two-leaves', 'root-predicate']) {
+        const home = fixtureHome(`crtr-sys-migrate-front-door-${shape}-`);
+        const rootProfile = join(home, '.crouter', 'profiles', 'root-00000000');
+        const project = join(home, 'fd-blocked');
+        const rootIndex = join(project, '.crouter', 'memory', 'INDEX.md');
+        const frontDoor = `surfaces:
+  - on: workspace-open
+    at: content
+  - on: read
+    match: "./**"
+    at: content`;
+        try {
+            write(join(rootProfile, 'profile.json'), manifest('root', [{ path: project, memory: 'content' }]));
+            if (shape === 'two-leaves') {
+                write(rootIndex, `---\nnamespace: fd-blocked\nkind: knowledge\n---\n# FD Blocked\n`);
+                write(join(project, '.crouter', 'memory', 'one.md'), `---\nkind: knowledge\n${frontDoor}\n---\n# One\n`);
+                write(join(project, 'pkg', '.crouter', 'memory', 'two.md'), `---\nkind: knowledge\n${frontDoor}\n---\n# Two\n`);
+            }
+            else {
+                write(rootIndex, `---\nnamespace: fd-blocked\nkind: knowledge\nsurfaces:\n  - on: workspace-open\n    at: preview\n---\n# FD Blocked\n`);
+                write(join(project, '.crouter', 'memory', 'note.md'), CURRENT_DOC);
+            }
+            const before = snapshotTree(project);
+            const payload = migrateBlocked(home);
+            const blocker = payload.received.blockers.find((row) => row.kind === 'front-door');
+            assert.ok(blocker, JSON.stringify(payload.received.blockers));
+            if (shape === 'two-leaves') {
+                assert.match(blocker.message, /more than one non-root document carrying the complete workspace front door/);
+                assert.deepEqual(blocker.paths?.sort(), [
+                    join(project, '.crouter', 'memory', 'one.md'),
+                    join(project, 'pkg', '.crouter', 'memory', 'two.md'),
+                ].sort());
+            }
+            else {
+                assert.match(blocker.message, /workspace-open route that migration cannot make authoritative/);
+                assert.deepEqual(blocker.paths, [rootIndex]);
+            }
+            assert.equal(payload.received.corpus_phase, 'not-started');
+            assert.equal(existsSync(markerPath(home)), false);
+            assertTreeUnchanged(before, snapshotTree(project));
+        }
+        finally {
+            rmSync(home, { recursive: true, force: true });
+        }
+    }
+});
+test('a leaf carrying both the legacy front door and a translated route keeps every retained authored byte', () => {
+    const home = fixtureHome('crtr-sys-migrate-front-door-compose-');
+    const rootProfile = join(home, '.crouter', 'profiles', 'root-00000000');
+    const project = join(home, 'compose-repo');
+    const workspaceDoc = join(project, '.crouter', 'memory', 'workspace.md');
+    try {
+        write(join(rootProfile, 'profile.json'), manifest('root', [{ path: project, memory: 'content' }]));
+        // Pre-003 identity: nothing declares a namespace, so `topics/*` still names
+        // the store's own documents and must be translated in the same pass that
+        // strips this document's workspace-open entry.
+        write(join(project, '.crouter', 'memory', 'INDEX.md'), `---\nkind: knowledge\n---\n# Compose Repo\n`);
+        write(join(project, '.crouter', 'memory', 'topics', 'one.md'), CURRENT_DOC);
+        write(join(project, '.crouter', 'memory', 'topics', 'two.md'), CURRENT_DOC);
+        write(join(project, '.crouter', 'memory', 'guides', 'setup.md'), CURRENT_DOC);
+        write(workspaceDoc, `---
+kind: knowledge
+name: project-guide
+surfaces:
+  - on: workspace-open
+    at: content
+  - on: read
+    match: "./**"
+    at: content
+  - on: memory-read
+    match:
+      - topics/*
+      - guides/*
+    at: content
+---
+# Compose workspace
+
+Body bytes that must survive both transforms.
+`);
+        const output = migrateJson(home);
+        assert.deepEqual(output.blockers, []);
+        assert.equal(prefixRow(output, project).front_door_action, 'transferred-from:.crouter/memory/workspace.md');
+        // The front-door removal and the consumer route rewrite compose: the
+        // workspace-open entry is gone, the route is translated, the read route and
+        // the body are untouched.
+        assert.equal(readFileSync(workspaceDoc, 'utf8'), `---
+kind: knowledge
+name: project-guide
+surfaces:
+  - on: read
+    match: "./**"
+    at: content
+  - on: memory-read
+    match:
+      ["compose-repo/topics/*", "compose-repo/guides/*"]
+    at: content
+---
+# Compose workspace
+
+Body bytes that must survive both transforms.
+`);
+        // Those bytes are YAML the runtime can read, not just text that looks right.
+        assert.deepEqual(parseYaml(readFileSync(workspaceDoc, 'utf8').split('---\n')[1] ?? '')?.surfaces, [
+            { on: 'read', match: './**', at: 'content' },
+            { on: 'memory-read', match: ['compose-repo/topics/*', 'compose-repo/guides/*'], at: 'content' },
+        ]);
+        for (const [from, to] of [['topics/*', 'compose-repo/topics/*'], ['guides/*', 'compose-repo/guides/*']]) {
+            assert.equal(output.references.some((row) => row.path === workspaceDoc && row.kind === 'memory-read' && row.from === from && row.to === to), true, JSON.stringify(output.references));
+        }
+        assert.equal(migrateJson(home).changed, 0);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test('an unreadable profile manifest blocks forced completion and remains in skipped output', () => {
+    const home = fixtureHome('crtr-sys-migrate-unreadable-profile-');
+    const userRoot = join(home, '.crouter');
+    const profileId = 'bad-deadbeef';
+    const profilePath = join(userRoot, 'profiles', profileId, 'profile.json');
+    try {
+        write(profilePath, '{not json');
+        write(markerPath(home), JSON.stringify(onDiskMigrationIdentity()));
+        const payload = migrateBlocked(home);
+        assert.equal(payload.received.blockers.length, 1);
+        assert.equal(payload.received.blockers[0]?.kind, 'parse-failure');
+        assert.equal(payload.received.blockers[0]?.path, profilePath);
+        assert.match(payload.received.blockers[0]?.message ?? '', /profile manifest is not valid JSON/);
+        assert.match(payload.received.blockers[0]?.message ?? '', /crtr sys migrate/);
+        assert.equal(payload.received.skipped.length, 1);
+        assert.equal(payload.received.skipped[0]?.store, join(userRoot, 'profiles'));
+        assert.equal(payload.received.skipped[0]?.relPath, `${profileId}/profile.json`);
+        assert.ok(payload.received.skipped[0]?.error);
+        assert.match(payload.next, /crtr sys migrate/);
+        assert.equal(existsSync(markerPath(home)), false);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test('sys migrate blocks the whole corpus when one link names different documents per target, and writes nothing', () => {
+    const home = fixtureHome('crtr-sys-migrate-divergent-');
+    const userRoot = join(home, '.crouter');
+    const rootProfile = join(userRoot, 'profiles', 'root-00000000');
+    const alpha = join(home, 'alpha-project');
+    const beta = join(home, 'beta-project');
+    try {
+        // Already current for the manifest and document lanes: the only thing this
+        // run could write is the corpus cut, so "nothing was written" is provable
+        // byte for byte.
+        write(join(rootProfile, 'profile.json'), manifest('root', [{ path: alpha, memory: 'content' }, { path: beta, memory: 'content' }]));
+        write(join(userRoot, 'memory', 'pointer.md'), `${CURRENT_DOC}\nSee [[guide]].\n`);
+        for (const [project, title] of [[alpha, 'Alpha Project'], [beta, 'Beta Project']]) {
+            write(join(project, '.crouter', 'memory', 'INDEX.md'), `---\nkind: knowledge\n---\n# ${title}\n`);
+            write(join(project, '.crouter', 'memory', 'guide.md'), CURRENT_DOC);
+        }
+        const before = snapshotTree(home);
+        const payload = migrateBlocked(home);
+        assert.match(payload.message, /corpus migration blocked by 1 finding\(s\) — nothing was written/);
+        assert.equal(payload.received.blockers.length, 1);
+        assert.equal(payload.received.blockers[0]?.kind, 'divergent-reference');
+        assert.equal(payload.received.blockers[0]?.name, 'guide');
+        assert.match(payload.received.blockers[0]?.message ?? '', /different documents depending on the target view/);
+        // The claim in the message is the claim in the payload: nothing on disk.
+        assert.equal(payload.received.corpus_phase, 'not-started');
+        assert.equal(payload.received.changed, 0);
+        assert.deepEqual(payload.received.wrote, {
+            profile_manifests: [],
+            documents: [],
+            corpus_consumers: [],
+            corpus_identities: [],
+        });
+        assert.deepEqual(payload.received.applied, []);
+        assert.equal(existsSync(markerPath(home)), false);
+        assertTreeUnchanged(before, snapshotTree(home));
+        // A blocked planner stays inspectable: the failure payload carries the same
+        // report body a converged run returns, so the plan that WOULD have been
+        // written can be read straight off the blocker.
+        assertReportInvariants(payload.received);
+        assert.equal(payload.received.dryRun, false);
+        assert.ok(payload.received.discovery_roots.length > 0, JSON.stringify(payload.received.discovery_roots));
+        assert.equal(payload.received.stores, payload.received.discovered_stores.length);
+        for (const project of [alpha, beta]) {
+            const store = join(project, '.crouter', 'memory');
+            assert.ok(payload.received.discovered_stores.some((row) => row.store === store), JSON.stringify(payload.received.discovered_stores));
+            assert.ok(payload.received.discovered_targets.some((row) => row.stores.includes(store)));
+            assert.equal(repositoryRow(payload.received, project).namespace, relative(home, project));
+            assert.equal(prefixRow(payload.received, project).effective_prefix, relative(home, project));
+            assert.ok(payload.received.renames.some((row) => row.store_root === store && row.to.startsWith(`${relative(home, project)}/`)), JSON.stringify(payload.received.renames));
+        }
+        assert.ok(Array.isArray(payload.received.references));
+        assert.equal(payload.received.node_metadata.available, true);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test('a corpus blocker never claims nothing was written when the earlier lanes already wrote', () => {
+    const home = fixtureHome('crtr-sys-migrate-earlier-writes-');
+    const userRoot = join(home, '.crouter');
+    const rootProfile = join(userRoot, 'profiles', 'root-00000000');
+    const alpha = join(home, 'alpha-project');
+    const beta = join(home, 'beta-project');
+    const userDoc = join(userRoot, 'memory', 'pointer.md');
+    try {
+        // A PRE-migration manifest and an old-format document, so the manifest and
+        // convergent lanes both write before the corpus lane plans — and then one
+        // `[[guide]]` naming a different document per target blocks that lane.
+        write(join(rootProfile, 'profile.json'), manifest('root', [alpha, beta]));
+        write(userDoc, `${OLD_DOC}\nSee [[guide]].\n`);
+        for (const [project, title] of [[alpha, 'Alpha Project'], [beta, 'Beta Project']]) {
+            write(join(project, '.crouter', 'memory', 'INDEX.md'), `---\nkind: knowledge\n---\n# ${title}\n`);
+            write(join(project, '.crouter', 'memory', 'guide.md'), CURRENT_DOC);
+        }
+        const projectsBefore = snapshotTree(alpha);
+        const payload = migrateBlocked(home);
+        assert.match(payload.message, /corpus migration blocked by 1 finding\(s\) before any corpus write/);
+        assert.match(payload.message, /the corpus is unchanged, but 2 earlier manifest\/document rewrite\(s\) are already on disk/);
+        assert.equal(payload.received.corpus_phase, 'not-started');
+        assert.equal(payload.received.changed, 2);
+        assert.deepEqual(payload.received.wrote.profile_manifests, [join(rootProfile, 'profile.json')]);
+        assert.deepEqual(payload.received.wrote.documents, [userDoc]);
+        assert.deepEqual(payload.received.wrote.corpus_consumers, []);
+        assert.deepEqual(payload.received.wrote.corpus_identities, []);
+        // Every file the payload names as written really did change, and every file
+        // only the corpus lane could have touched did not.
+        assert.doesNotMatch(readFileSync(userDoc, 'utf8'), /system-prompt-visibility/);
+        assert.match(readFileSync(userDoc, 'utf8'), /See \[\[guide\]\]\.\n/);
+        assert.deepEqual(JSON.parse(readFileSync(join(rootProfile, 'profile.json'), 'utf8')).projects, [{ path: alpha, memory: 'preview' }, { path: beta, memory: 'preview' }]);
+        assertTreeUnchanged(projectsBefore, snapshotTree(alpha));
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test('a verification failure after both write phases reports the rewrites that are on disk', () => {
+    const home = fixtureHome('crtr-sys-migrate-verification-');
+    const userRoot = join(home, '.crouter');
+    const rootProfile = join(userRoot, 'profiles', 'root-00000000');
+    const project = join(home, 'verify-project');
+    const projectIndex = join(project, '.crouter', 'memory', 'INDEX.md');
+    const strayDoc = join(project, '.crouter', 'memory', 'stray.md');
+    try {
+        write(join(rootProfile, 'profile.json'), manifest('root', [{ path: project, memory: 'content' }]));
+        write(projectIndex, `---\nkind: knowledge\n---\n# Verify Project\n`);
+        // `namespace:` on a NON-root document: not an identity field this lane
+        // rewrites, so the plan is clean and the writes land — and the post-write
+        // lint against file truth then refuses the store.
+        write(strayDoc, `---\nkind: knowledge\nnamespace: verify-project\n---\n# Stray declaration\n`);
+        const payload = migrateBlocked(home);
+        assert.match(payload.message, /corpus migration verification failed with 1 finding\(s\) after both write phases/);
+        assert.match(payload.message, /identity rewrite\(s\) are on disk and are NOT rolled back/);
+        assert.equal(payload.received.blockers[0]?.kind, 'verification');
+        assert.match(payload.received.blockers[0]?.message ?? '', /namespace-placement/);
+        assert.equal(payload.received.corpus_phase, 'written');
+        assert.deepEqual(payload.received.wrote.corpus_identities, [projectIndex]);
+        assert.equal(payload.received.changed, 1);
+        assert.equal(payload.received.applied.some((row) => row.lane === 'corpus' && row.files.includes(projectIndex)), true);
+        assert.match(payload.next, /re-run `crtr sys migrate`/);
+        assert.equal(existsSync(markerPath(home)), false);
+        // The inventory is true of the bytes: the declaration and the repository's
+        // front door really are on disk.
+        assert.equal(readFileSync(projectIndex, 'utf8'), `---
+namespace: verify-project
+kind: knowledge
+surfaces:
+  - on: workspace-open
+    at: content
+  - on: read
+    match: ./**
+    at: content
+---
+# Verify Project
+`);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test('a nested store reached only through a node target inherits the ancestor repository declaration', () => {
+    const home = fixtureHome('crtr-sys-migrate-node-nested-');
+    const userRoot = join(home, '.crouter');
+    const rootProfile = join(userRoot, 'profiles', 'root-00000000');
+    const nodeId = 'node-bbbb2222';
+    const nodeStore = join(userRoot, 'canvas', 'nodes', nodeId, 'context', 'memory');
+    const nodeProject = join(home, 'node-cwd-project');
+    const nestedOwner = join(nodeProject, 'nested');
+    try {
+        // No project in any manifest and none above the cwd: the node's durable
+        // metadata is the ONLY path to this project root.
+        write(join(rootProfile, 'profile.json'), manifest('root', []));
+        write(join(userRoot, 'canvas', 'nodes', nodeId, 'meta.json'), JSON.stringify({ node_id: nodeId, cwd: nodeProject, profile_id: 'root-00000000', kind: 'developer' }));
+        write(join(nodeStore, 'note.md'), CURRENT_DOC);
+        write(join(nodeProject, '.crouter', 'memory', 'INDEX.md'), `---\nkind: knowledge\n---\n# Node Cwd Project\n`);
+        write(join(nestedOwner, '.crouter', 'memory', 'topic.md'), CURRENT_DOC);
+        const output = migrateJson(home, { dryRun: true });
+        const storeRoots = output.discovered_stores.map((row) => row.store);
+        assert.equal(storeRoots.includes(join(nodeProject, '.crouter', 'memory')), true, JSON.stringify(storeRoots));
+        assert.equal(storeRoots.includes(join(nestedOwner, '.crouter', 'memory')), true, JSON.stringify(storeRoots));
+        // The nested owner takes the ancestor repository's namespace composed with
+        // its own path — and declares nothing of its own.
+        assert.deepEqual(output.repository_namespaces.map((row) => row.repository_root), [nodeProject], JSON.stringify(output.repository_namespaces));
+        const nested = prefixRow(output, nestedOwner);
+        assert.equal(nested.repository_root, nodeProject);
+        assert.equal(nested.owner_relative_path, 'nested');
+        assert.equal(nested.effective_prefix, 'node-cwd-project/nested');
+        assert.equal(nested.nested_declaration_action, 'none');
+        assert.equal(nested.front_door_action, 'none');
+        assert.equal(output.discovered_targets.some((row) => row.kind === 'project' && row.origin === nestedOwner), true);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test('a memory-read route translates through an INDEX collapse and a root-plus-descendant split', () => {
+    const home = fixtureHome('crtr-sys-migrate-routes-');
+    const userRoot = join(home, '.crouter');
+    const rootProfile = join(userRoot, 'profiles', 'root-00000000');
+    const project = join(home, 'route-project');
+    const carrier = join(project, '.crouter', 'memory', 'carrier.md');
+    try {
+        write(join(rootProfile, 'profile.json'), manifest('root', [{ path: project, memory: 'content' }]));
+        write(join(project, '.crouter', 'memory', 'INDEX.md'), `---\nkind: knowledge\n---\n# Route Project\n`);
+        // `topics/INDEX` collapses onto `route-project/topics`, and `topics/**`
+        // named that same directory document plus its leaf — post-cut the leaf is
+        // under `route-project/topics/**` and the directory document is not, so the
+        // one entry splits into the exact pair.
+        write(join(project, '.crouter', 'memory', 'topics', 'INDEX.md'), CURRENT_DOC);
+        write(join(project, '.crouter', 'memory', 'topics', 'one.md'), CURRENT_DOC);
+        write(carrier, `---
+kind: knowledge
+surfaces:
+  - on: memory-read
+    match: topics/INDEX
+    at: content
+  - on: memory-read
+    match: topics/**
+    at: content
+---
+# Carrier
+`);
+        const output = migrateJson(home);
+        assert.deepEqual(output.blockers, []);
+        assert.equal(readFileSync(carrier, 'utf8'), `---
+kind: knowledge
+surfaces:
+  - on: memory-read
+    match: "route-project/topics"
+    at: content
+  - on: memory-read
+    match: ["route-project/topics/**", "route-project/topics"]
+    at: content
+---
+# Carrier
+`);
+        assert.equal(output.references.some((row) => row.kind === 'memory-read' && row.from === 'topics/INDEX' && row.to === 'route-project/topics'), true, JSON.stringify(output.references));
+        assert.equal(output.references.some((row) => row.kind === 'memory-read' &&
+            row.from === 'topics/**' &&
+            row.to === 'route-project/topics/**, route-project/topics'), true, JSON.stringify(output.references));
+        // A second run over the translated routes plans nothing.
+        const second = migrateJson(home);
+        assert.equal(second.changed, 0);
+        assert.deepEqual(second.references, []);
     }
     finally {
         rmSync(home, { recursive: true, force: true });