@north-light/crouter 0.3.317 → 0.3.319

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

@@ -1,1330 +0,0 @@
-import assert from 'node:assert/strict';
-import { spawnSync } from 'node:child_process';
-import { existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { dirname, join, relative } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import test from 'node:test';
-import { parse as parseYaml } from 'yaml';
-import { onDiskMigrationIdentity } from '../../../migrations/registry.js';
-import { initializeFreshScopedStore } from '../../../core/scoped-state/migrate.js';
-import { userStore } from '../../../core/scoped-state/paths.js';
-import { writeRawSettings } from '../../../core/scoped-state/settings.js';
-import { createSourceDaemonFixture, startSourceDaemon, waitForHealth, } from '../../../daemon/__tests__/helpers/source-daemon.js';
-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
-`;
-/** 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/...`. */
-const migrateCanvasHomes = new Map();
-function fixtureHome(prefix) {
-    const home = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
-    initializeFreshScopedStore({ kind: 'user', root: join(home, '.crouter') });
-    const root = mkdtempSync(join(tmpdir(), 'crtr-sys-migrate-daemon-'));
-    migrateCanvasHomes.set(home, join(root, 'canvas'));
-    return home;
-}
-function writeUserConfig(home, raw) {
-    const store = userStore(join(home, '.crouter'));
-    writeRawSettings({ store, key: 'user', kind: 'user', root: store.root }, raw);
-}
-/** 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 canvasHomeFor(home) {
-    return migrateDaemons.get(home)?.fixture.canvasHome ?? migrateCanvasHomes.get(home) ?? join(home, '.crouter', 'canvas');
-}
-function markerPath(home) {
-    return join(canvasHomeFor(home), '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_HOME'] = canvasHomeFor(home);
-    env['CRTR_PROFILE_ID'] = profileId;
-    env['CRTR_NO_DAEMON_AUTOSTART'] = '1';
-    env['CRTR_NO_AUTO_INIT'] = '1';
-    env['CRTR_NO_AUTO_UPDATE'] = '1';
-    return env;
-}
-const migrateDaemons = new Map();
-async function startMigrateDaemon(home) {
-    const canvasHome = migrateCanvasHomes.get(home);
-    assert.ok(canvasHome, `fixture has no canvas home: ${home}`);
-    const fixture = await createSourceDaemonFixture({
-        root: dirname(canvasHome),
-        home,
-        cwd: home,
-        canvasHome,
-    });
-    const process = startSourceDaemon(fixture, { CRTR_PROFILE_ID: 'root-00000000' });
-    try {
-        await waitForHealth(process, fixture.tcpPort);
-    }
-    catch (error) {
-        await process.stop();
-        fixture.dispose();
-        throw error;
-    }
-    migrateDaemons.set(home, { fixture, process });
-}
-async function stopMigrateDaemon(home) {
-    const daemon = migrateDaemons.get(home);
-    if (daemon === undefined)
-        return;
-    migrateDaemons.delete(home);
-    const exit = await daemon.process.stop();
-    daemon.fixture.dispose();
-    migrateCanvasHomes.delete(home);
-    assert.deepEqual(exit, { code: 0, signal: null }, `migration daemon must stop cleanly; stderr:\n${daemon.process.stderr()}`);
-}
-function seedNodeMemoryTarget(home, target) {
-    const canvas = pathToFileURL(join(HERE, '../../../core/canvas/canvas.ts')).href;
-    const program = `
-    import { createNode } from ${JSON.stringify(canvas)};
-    const target = JSON.parse(process.argv[1]);
-    createNode({
-      node_id: target.nodeId,
-      name: target.nodeId,
-      created: new Date().toISOString(),
-      cwd: target.cwd,
-      kind: 'developer',
-      mode: 'base',
-      lifecycle: 'terminal',
-      status: 'done',
-      profile_id: target.profileId,
-    });
-  `;
-    const result = spawnSync(process.execPath, ['--conditions=crtr-src', '--import', TSX_LOADER, '--input-type=module', '--eval', program, JSON.stringify(target)], { cwd: home, env: migrateEnv(home, target.profileId ?? 'root-00000000'), encoding: 'utf8' });
-    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
-}
-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({
-        schema_version: 1,
-        name,
-        projects,
-        home: (typeof first === 'string' ? first : first?.path) ?? null,
-        created_at: '2026-01-01T00:00:00.000Z',
-        last_used_at: null,
-    });
-}
-test('sys migrate converges manifests, documents, and the whole repository-root corpus', async () => {
-    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 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(canvasHomeFor(home), '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 {
-        await startMigrateDaemon(home);
-        seedNodeMemoryTarget(home, { nodeId, cwd: appletProject, profileId: 'applet-deadbeef' });
-        // 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);
-        // Root profile store: an INDEX spelling to collapse, an unqualified project
-        // name outside its own target stack, 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);
-        // A DISABLED plugin: no target mounts it, so its references resolve against
-        // its own store alone — and it is still migrated.
-        writeUserConfig(home, { 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 whose SQL row was seeded before its documents. No meta.json
-        // exists: corpus discovery must use the daemon-owned roster.
-        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.deepEqual(readMarker(home), onDiskMigrationIdentity(), 'the daemon completed its empty-corpus startup before fixture bytes were seeded');
-        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, 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/);
-        }
-        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, /\[\[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 {
-        await stopMigrateDaemon(home);
-        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', async () => {
-    const preHome = fixtureHome('crtr-sys-migrate-conv-pre-');
-    const oldHome = fixtureHome('crtr-sys-migrate-conv-old-');
-    try {
-        await startMigrateDaemon(preHome);
-        await startMigrateDaemon(oldHome);
-        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 {
-        await stopMigrateDaemon(preHome);
-        await stopMigrateDaemon(oldHome);
-        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', async () => {
-    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 {
-        await startMigrateDaemon(home);
-        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 {
-        await stopMigrateDaemon(home);
-        rmSync(home, { recursive: true, force: true });
-    }
-});
-test('a git repository whose only stores are descendants gets its repository-root declaration created', async () => {
-    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 {
-        await startMigrateDaemon(home);
-        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));
-        const second = migrateJson(home);
-        assert.equal(second.changed, 0, JSON.stringify(second.applied));
-    }
-    finally {
-        await stopMigrateDaemon(home);
-        rmSync(home, { recursive: true, force: true });
-    }
-});
-test('linked worktrees agree on one declaration, and a linked root missing one is filled from it', async () => {
-    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 {
-            await startMigrateDaemon(home);
-            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 {
-            await stopMigrateDaemon(home);
-            rmSync(home, { recursive: true, force: true });
-        }
-    }
-});
-test('linked worktree roots declaring different namespaces block the corpus', async () => {
-    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 {
-        await startMigrateDaemon(home);
-        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 {
-        await stopMigrateDaemon(home);
-        rmSync(home, { recursive: true, force: true });
-    }
-});
-test('a nested declaration is removed, an exact synthetic index is deleted, and a substantive one is kept', async () => {
-    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 {
-        await startMigrateDaemon(home);
-        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 {
-        await stopMigrateDaemon(home);
-        rmSync(home, { recursive: true, force: true });
-    }
-});
-test('a rootless repository takes its front door from the one legacy guide that owns it', async () => {
-    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 {
-        await startMigrateDaemon(home);
-        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 {
-        await stopMigrateDaemon(home);
-        rmSync(home, { recursive: true, force: true });
-    }
-});
-test('repository-relative ordering prefixes do not block migration and derive canonical owner paths', async () => {
-    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 {
-        await startMigrateDaemon(home);
-        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 {
-        await stopMigrateDaemon(home);
-        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', async () => {
-    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 {
-        await startMigrateDaemon(home);
-        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 {
-        await stopMigrateDaemon(home);
-        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', async () => {
-    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 {
-            await startMigrateDaemon(home);
-            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 {
-            await stopMigrateDaemon(home);
-            rmSync(home, { recursive: true, force: true });
-        }
-    }
-});
-test('a leaf carrying both the legacy front door and a translated route keeps every retained authored byte', async () => {
-    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 {
-        await startMigrateDaemon(home);
-        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 {
-        await stopMigrateDaemon(home);
-        rmSync(home, { recursive: true, force: true });
-    }
-});
-test('an unreadable profile manifest blocks forced completion and remains in skipped output', async () => {
-    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 {
-        await startMigrateDaemon(home);
-        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 {
-        await stopMigrateDaemon(home);
-        rmSync(home, { recursive: true, force: true });
-    }
-});
-test('sys migrate blocks the whole corpus when one link names different documents per target, and writes nothing', async () => {
-    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 {
-        await startMigrateDaemon(home);
-        // 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));
-    }
-    finally {
-        await stopMigrateDaemon(home);
-        rmSync(home, { recursive: true, force: true });
-    }
-});
-test('a corpus blocker never claims nothing was written when the earlier lanes already wrote', async () => {
-    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 {
-        await startMigrateDaemon(home);
-        // 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 {
-        await stopMigrateDaemon(home);
-        rmSync(home, { recursive: true, force: true });
-    }
-});
-test('a verification failure after both write phases reports the rewrites that are on disk', async () => {
-    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 {
-        await startMigrateDaemon(home);
-        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 {
-        await stopMigrateDaemon(home);
-        rmSync(home, { recursive: true, force: true });
-    }
-});
-test('a nested store reached only through a node target inherits the ancestor repository declaration', async () => {
-    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(canvasHomeFor(home), 'nodes', nodeId, 'context', 'memory');
-    const nodeProject = join(home, 'node-cwd-project');
-    const nestedOwner = join(nodeProject, 'nested');
-    try {
-        await startMigrateDaemon(home);
-        seedNodeMemoryTarget(home, { nodeId, cwd: nodeProject, profileId: 'root-00000000' });
-        // No project in any manifest and none above the cwd: the daemon's SQL row
-        // is the ONLY path to this project root.
-        write(join(rootProfile, 'profile.json'), manifest('root', []));
-        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 {
-        await stopMigrateDaemon(home);
-        rmSync(home, { recursive: true, force: true });
-    }
-});
-test('a memory-read route translates through an INDEX collapse and a root-plus-descendant split', async () => {
-    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 {
-        await startMigrateDaemon(home);
-        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 {
-        await stopMigrateDaemon(home);
-        rmSync(home, { recursive: true, force: true });
-    }
-});