@north-light/crouter 0.3.227 → 0.3.228

package/dist/migrations/003-repository-root-memory-identity/repository-facts.js

@@ -0,0 +1,349 @@
+import { dirname } from 'node:path';
+import { realpathOrSelf, readTextIfExists } from '../../core/fs-utils.js';
+import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
+import { composeCanonicalName, explicitLocalName, localNameFromPath, validateExplicitLocalName, validateNamespace, } from '../../core/memory/identity.js';
+import { deriveProjectNamespace, } from '../../core/memory/project-namespace.js';
+import { associateRepository, } from '../../core/memory/repository-association.js';
+const SYNTHETIC_NAMESPACE = '__CROUTER_SYNTHETIC_NAMESPACE__';
+const SYNTHETIC_NAMESPACE_SCALAR = '__CROUTER_SYNTHETIC_NAMESPACE_SCALAR__';
+/** Exact source emitted by the superseded migration 003, with only its namespace
+ * value parameterized. It is deliberately byte-shaped rather than prose-shaped:
+ * a substantive nested guide is never deleted because it merely resembles this. */
+const SYNTHETIC_INDEX_TEMPLATE = [
+    '---',
+    'kind: knowledge',
+    `namespace: ${SYNTHETIC_NAMESPACE_SCALAR}`,
+    `when-and-why-to-read: When working in \`${SYNTHETIC_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',
+    '---',
+    `# ${SYNTHETIC_NAMESPACE}`,
+    '',
+    `This project's memory store. Every document here answers at \`${SYNTHETIC_NAMESPACE}/<local name>\`.`,
+    '',
+].join('\n');
+export function planRepositories(corpus) {
+    const blockers = [];
+    const associated = [];
+    const groups = new Map();
+    const rootsInCorpusOrder = [];
+    for (const store of corpus.stores) {
+        if (!isNativeProjectStore(store))
+            continue;
+        const ownerDir = realpathOrSelf(ownerDirOf(store));
+        const result = associateRepository(ownerDir);
+        if (!result.ok) {
+            blockers.push({
+                kind: 'association',
+                message: `project memory store at ${store.key} owned by ${ownerDir} cannot be associated with a repository (${result.reason}) — repair the repository boundary and re-run`,
+                storeRoot: store.key,
+            });
+            continue;
+        }
+        const row = {
+            store,
+            ownerDir,
+            association: result.association,
+            rootDoc: store.snapshot.docs.find((doc) => localNameFromPath(doc.relPath) === '') ?? null,
+        };
+        associated.push(row);
+        const groupingKey = result.association.kind === 'git'
+            ? result.association.repositoryKey
+            : `path:${result.association.repositoryRoot}`;
+        let group = groups.get(groupingKey);
+        if (group === undefined) {
+            group = {
+                repositoryKey: result.association.repositoryKey,
+                roots: new Map(),
+            };
+            groups.set(groupingKey, group);
+        }
+        let root = group.roots.get(result.association.repositoryRoot);
+        if (root === undefined) {
+            root = {
+                association: result.association,
+                stores: [],
+                rootStore: null,
+                index: missingRootIndex(),
+                declaration: { state: 'missing' },
+            };
+            group.roots.set(result.association.repositoryRoot, root);
+            rootsInCorpusOrder.push(root);
+        }
+        root.stores.push(row);
+        if (result.association.ownerRelativePath === '' && root.rootStore === null)
+            root.rootStore = row;
+    }
+    const nestedByStore = new Map();
+    for (const row of associated) {
+        if (row.association.ownerRelativePath === '') {
+            nestedByStore.set(row.store.key, { declaration: { state: 'missing' }, action: 'none' });
+            continue;
+        }
+        const declaration = legacyNestedDeclarationFacts(row.rootDoc);
+        let action = 'none';
+        if (declaration.state === 'invalid') {
+            blockers.push(invalidDeclarationBlocker(row.store.key, row.rootDoc?.path ?? row.store.key, declaration, 'nested project memory store'));
+        }
+        else if (declaration.state === 'valid') {
+            action = row.rootDoc !== null && isSupersededSyntheticIndex(row.rootDoc.source, declaration.value)
+                ? 'synthetic-index-removed'
+                : 'removed';
+        }
+        nestedByStore.set(row.store.key, { declaration, action });
+    }
+    for (const root of rootsInCorpusOrder) {
+        root.index = readRootIndex(root);
+        root.declaration = root.index.error === null
+            ? declarationFacts(root.index.frontmatter?.['namespace'])
+            : { state: 'invalid', reason: root.index.error, raw: undefined };
+        if (root.declaration.state === 'invalid') {
+            blockers.push(invalidDeclarationBlocker(root.rootStore?.store.key ?? dirname(root.association.declarationPath), root.association.declarationPath, root.declaration, 'repository root'));
+        }
+    }
+    const selectedByRoot = new Map();
+    for (const group of groups.values())
+        selectGroup(group, selectedByRoot, blockers);
+    const repositories = [];
+    for (const root of rootsInCorpusOrder) {
+        const selected = selectedByRoot.get(root.association.repositoryRoot);
+        if (selected !== undefined)
+            repositories.push(selected.decision);
+    }
+    const prefixes = new Map();
+    for (const row of associated) {
+        const selected = selectedByRoot.get(row.association.repositoryRoot);
+        const nested = nestedByStore.get(row.store.key);
+        if (selected === undefined || nested.declaration.state === 'invalid')
+            continue;
+        const isRoot = row.association.ownerRelativePath === '';
+        const effectivePrefix = composeCanonicalName(selected.decision.namespace, row.association.ownerRelativePath);
+        const { oldPrefix, oldRule } = oldAuthority(row.store, isRoot, selected.declaration, nested.declaration, effectivePrefix);
+        prefixes.set(row.store.key, {
+            store: row.store,
+            storeKey: row.store.key,
+            storeRoot: row.store.key,
+            ownerDir: row.ownerDir,
+            repositoryKey: row.association.repositoryKey,
+            repositoryRoot: row.association.repositoryRoot,
+            ownerRelativePath: row.association.ownerRelativePath,
+            oldPrefix,
+            oldRule,
+            effectivePrefix,
+            nestedDeclarationAction: nested.action,
+            legacyDeclaration: !isRoot && nested.declaration.state === 'valid' ? nested.declaration.value : null,
+        });
+    }
+    addOwnerPathCollisionBlockers(associated, selectedByRoot, blockers);
+    return { repositories, prefixes, blockers };
+}
+/** What a store's documents answered under BEFORE this run, from file truth
+ * alone. A store's own valid declaration proves its old prefix outright.
+ *
+ * A nested store that declares nothing is in one of two states, and they are not
+ * the same authority: pre-003, where nothing up the tree declared anything and
+ * its documents answered at bare local names; or already cut, where the
+ * repository root's kept declaration is exactly what gave them their prefix. The
+ * kept root declaration plus the absence of any explicit `name:` this cut would
+ * have rewritten identifies the second — that pair is the corpus this migration
+ * leaves behind, so reading it as pre-003 would report an identity rename for
+ * every document that never moves. */
+function oldAuthority(store, isRoot, rootDeclaration, nestedDeclaration, effectivePrefix) {
+    const own = isRoot ? rootDeclaration : nestedDeclaration;
+    if (own.state === 'valid')
+        return { oldPrefix: own.value, oldRule: 'per-store-declaration' };
+    if (!isRoot && rootDeclaration.state === 'valid' && !carriesLegacyExplicitIdentity(store, effectivePrefix)) {
+        return { oldPrefix: effectivePrefix, oldRule: 'per-store-declaration' };
+    }
+    return { oldPrefix: '', oldRule: 'pre-003' };
+}
+/** An explicit `name:` this cut never leaves behind: one on a store root
+ * document, or one that is not a store-local name under the store's own prefix —
+ * a fully qualified pre-003 name is the shape that matters. Either proves the
+ * store still carries pre-003 identity even though it declares nothing. */
+function carriesLegacyExplicitIdentity(store, effectivePrefix) {
+    return store.snapshot.docs.some((doc) => {
+        const explicit = explicitLocalName(doc.frontmatter);
+        if (explicit === null)
+            return false;
+        return localNameFromPath(doc.relPath) === '' || !validateExplicitLocalName(explicit, effectivePrefix).ok;
+    });
+}
+function selectGroup(group, selectedByRoot, blockers) {
+    const roots = [...group.roots.values()];
+    if (roots.some((root) => root.declaration.state === 'invalid'))
+        return;
+    const declared = roots.filter((root) => root.declaration.state === 'valid');
+    const values = [...new Set(declared.map((root) => root.declaration.value))];
+    if (values.length > 1) {
+        const paths = declared.map((root) => root.association.declarationPath);
+        blockers.push({
+            kind: 'namespace',
+            message: `linked repository roots for ${group.repositoryKey} declare different namespaces (${values.map((value) => `\`${value}\``).join(', ')}) — make every root declaration agree and re-run`,
+            paths,
+        });
+        return;
+    }
+    if (values.length === 1) {
+        const namespace = values[0];
+        for (const root of roots) {
+            const action = root.declaration.state === 'valid' ? 'kept' : 'filled-linked-root';
+            selectedByRoot.set(root.association.repositoryRoot, {
+                declaration: root.declaration,
+                decision: repositoryDecision(group, root, namespace, 'declared', action),
+            });
+        }
+        return;
+    }
+    const derivingRoot = roots[0];
+    const derived = deriveProjectNamespace({
+        ownerDir: derivingRoot.association.repositoryRoot,
+        rootFrontmatter: derivingRoot.index.frontmatter,
+        ...(derivingRoot.index.exists ? { rootBody: derivingRoot.index.body } : {}),
+    });
+    if (!derived.ok) {
+        blockers.push({
+            kind: 'namespace',
+            message: `repository at ${derivingRoot.association.repositoryRoot} cannot derive a namespace (${derived.reason}) — declare a valid \`namespace:\` on ${derivingRoot.association.declarationPath} and re-run`,
+            storeRoot: derivingRoot.rootStore?.store.key ?? dirname(derivingRoot.association.declarationPath),
+            ...(derivingRoot.index.exists ? { path: derivingRoot.association.declarationPath } : {}),
+        });
+        return;
+    }
+    for (const root of roots) {
+        selectedByRoot.set(root.association.repositoryRoot, {
+            declaration: root.declaration,
+            decision: repositoryDecision(group, root, derived.namespace, derived.source, root.index.exists ? 'kept' : 'created'),
+        });
+    }
+}
+function repositoryDecision(group, root, namespace, source, action) {
+    return {
+        repositoryKey: group.repositoryKey,
+        repositoryRoot: root.association.repositoryRoot,
+        declarationPath: root.association.declarationPath,
+        namespace,
+        source,
+        action,
+        storeKeys: root.stores.map((row) => row.store.key),
+    };
+}
+function readRootIndex(root) {
+    const declarationRealPath = realpathOrSelf(root.association.declarationPath);
+    const declarationDoc = root.rootStore?.store.snapshot.docs.find((doc) => realpathOrSelf(doc.path) === declarationRealPath);
+    if (declarationDoc !== undefined) {
+        return {
+            exists: true,
+            frontmatter: declarationDoc.frontmatter,
+            body: declarationDoc.body,
+            error: null,
+        };
+    }
+    try {
+        const source = readTextIfExists(root.association.declarationPath);
+        if (source === null)
+            return missingRootIndex();
+        const parsed = parseFrontmatterGeneric(source);
+        return {
+            exists: true,
+            frontmatter: parsed.data,
+            body: parsed.body,
+            error: null,
+        };
+    }
+    catch (error) {
+        return {
+            exists: true,
+            frontmatter: null,
+            body: '',
+            error: `cannot read or parse ${root.association.declarationPath} (${firstLine(error)})`,
+        };
+    }
+}
+function missingRootIndex() {
+    return { exists: false, frontmatter: null, body: '', error: null };
+}
+function legacyNestedDeclarationFacts(rootDoc) {
+    if (rootDoc?.frontmatter === null
+        || rootDoc?.frontmatter === undefined
+        || !Object.prototype.hasOwnProperty.call(rootDoc.frontmatter, 'namespace')) {
+        return { state: 'missing' };
+    }
+    return authoredDeclarationFacts(rootDoc.frontmatter['namespace']);
+}
+function declarationFacts(raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return { state: 'missing' };
+    return authoredDeclarationFacts(raw);
+}
+function authoredDeclarationFacts(raw) {
+    if (typeof raw !== 'string') {
+        return {
+            state: 'invalid',
+            reason: `\`namespace:\` is non-string (${JSON.stringify(raw)})`,
+            raw,
+        };
+    }
+    const valid = validateNamespace(raw);
+    return valid.ok
+        ? { state: 'valid', value: raw }
+        : { state: 'invalid', reason: `\`namespace: ${raw}\` is invalid (${valid.reason})`, raw };
+}
+function invalidDeclarationBlocker(storeRoot, path, declaration, subject) {
+    return {
+        kind: 'namespace',
+        message: `${subject} has an invalid namespace declaration at ${path} (${declaration.reason}) — correct it and re-run; migration never replaces an unprovable identity`,
+        storeRoot,
+        path,
+        ...(typeof declaration.raw === 'string' ? { name: declaration.raw } : {}),
+    };
+}
+function addOwnerPathCollisionBlockers(associated, selectedByRoot, blockers) {
+    const collisions = new Map();
+    for (const row of associated) {
+        const key = `${row.association.repositoryRoot}\u0000${row.association.ownerRelativePath}`;
+        const bucket = collisions.get(key);
+        if (bucket === undefined)
+            collisions.set(key, [row]);
+        else
+            bucket.push(row);
+    }
+    for (const rows of collisions.values()) {
+        if (rows.length < 2)
+            continue;
+        const first = rows[0];
+        const selected = selectedByRoot.get(first.association.repositoryRoot);
+        const effectivePrefix = selected === undefined
+            ? first.association.ownerRelativePath
+            : composeCanonicalName(selected.decision.namespace, first.association.ownerRelativePath);
+        const paths = rows.map((row) => row.ownerDir);
+        blockers.push({
+            kind: 'collision',
+            message: `directories ${paths.join(', ')} in repository ${first.association.repositoryRoot} normalize to the same owner path \`${first.association.ownerRelativePath}\` and effective prefix \`${effectivePrefix}\` — rename one directory and re-run`,
+            storeRoot: first.store.key,
+            name: effectivePrefix,
+            paths,
+        });
+    }
+}
+function isSupersededSyntheticIndex(source, namespace) {
+    return source === SYNTHETIC_INDEX_TEMPLATE
+        .replaceAll(SYNTHETIC_NAMESPACE_SCALAR, renderScalar(namespace))
+        .replaceAll(SYNTHETIC_NAMESPACE, namespace);
+}
+function renderScalar(value) {
+    return /^[A-Za-z][A-Za-z0-9._\-/]*$/.test(value) ? value : JSON.stringify(value);
+}
+function ownerDirOf(store) {
+    return store.descriptor.ownerDir ?? dirname(dirname(store.descriptor.storeRoot));
+}
+function isNativeProjectStore(store) {
+    return store.descriptor.scope === 'project' && store.descriptor.plugin === undefined;
+}
+function firstLine(error) {
+    return (error instanceof Error ? error.message : String(error)).split('\n')[0] ?? String(error);
+}

package/dist/migrations/__tests__/activation-concurrency.test.d.ts

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

package/dist/migrations/__tests__/activation-concurrency.test.js

@@ -0,0 +1,145 @@
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import test from 'node:test';
+import { withExclusiveDirectoryLockAsync } from '../../core/exclusive-lock.js';
+import { activateOnDiskMigrations, runForcedOnDiskMigrations } from '../activation.js';
+function result() {
+    return {
+        blockers: [],
+        finalVerificationSucceeded: true,
+        wrote: { profileManifests: [], documents: [], corpusConsumers: [], corpusIdentities: [] },
+    };
+}
+function deferred() {
+    let resolve;
+    const promise = new Promise((done) => { resolve = done; });
+    return { promise, resolve };
+}
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function waitFor(check) {
+    const deadline = Date.now() + 2_000;
+    while (!check()) {
+        if (Date.now() >= deadline)
+            throw new Error('timed out waiting for migration race fixture');
+        await delay(5);
+    }
+}
+function childActivation(home, release) {
+    const moduleUrl = pathToFileURL(join(process.cwd(), 'src/migrations/activation.ts')).href;
+    const script = `
+    const { existsSync, writeFileSync } = await import('node:fs');
+    const { join } = await import('node:path');
+    const { activateOnDiskMigrations } = await import(${JSON.stringify(moduleUrl)});
+    await activateOnDiskMigrations({
+      timeoutMs: 5000,
+      runner: async () => {
+        writeFileSync(join(${JSON.stringify(home)}, 'entered.' + process.pid), '');
+        while (!existsSync(${JSON.stringify(release)})) await new Promise((resolve) => setTimeout(resolve, 5));
+        return { blockers: [], finalVerificationSucceeded: true, wrote: { profileManifests: [], documents: [], corpusConsumers: [], corpusIdentities: [] } };
+      },
+    });
+  `;
+    const child = spawn(process.execPath, ['--conditions=crtr-src', '--import', 'tsx/esm', '--input-type=module', '-e', script], {
+        cwd: process.cwd(),
+        env: { ...process.env, CRTR_HOME: home },
+        stdio: ['ignore', 'ignore', 'pipe'],
+    });
+    let stderr = '';
+    child.stderr?.setEncoding('utf8').on('data', (chunk) => { stderr += String(chunk); });
+    const done = new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('close', (code) => code === 0 ? resolve() : reject(new Error(`activation child exited ${code}: ${stderr}`)));
+    });
+    return done;
+}
+test('the asynchronous lock remains owned until its operation promise settles', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'crtr-async-lock-'));
+    const lock = join(home, 'exclusive.lock');
+    const gate = deferred();
+    const entered = deferred();
+    let secondEntered = false;
+    try {
+        const first = withExclusiveDirectoryLockAsync(lock, async () => {
+            entered.resolve();
+            await gate.promise;
+        }, { timeoutMs: 1_000 });
+        await entered.promise;
+        assert.equal(existsSync(lock), true);
+        const second = withExclusiveDirectoryLockAsync(lock, async () => { secondEntered = true; }, { timeoutMs: 1_000 });
+        await delay(30);
+        assert.equal(secondEntered, false);
+        assert.equal(existsSync(lock), true);
+        gate.resolve();
+        await Promise.all([first, second]);
+        assert.equal(secondEntered, true);
+        assert.equal(existsSync(lock), false);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test('activation and a forced migration serialize, and forced still runs after the marker write', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'crtr-activation-forced-'));
+    const previous = process.env['CRTR_HOME'];
+    process.env['CRTR_HOME'] = home;
+    const gate = deferred();
+    const entered = deferred();
+    let calls = 0;
+    let active = 0;
+    let maxActive = 0;
+    const runner = async () => {
+        calls += 1;
+        active += 1;
+        maxActive = Math.max(maxActive, active);
+        try {
+            if (calls === 1) {
+                entered.resolve();
+                await gate.promise;
+            }
+            return result();
+        }
+        finally {
+            active -= 1;
+        }
+    };
+    try {
+        const activation = activateOnDiskMigrations({ timeoutMs: 1_000, runner });
+        await entered.promise;
+        const forced = runForcedOnDiskMigrations({ timeoutMs: 1_000, runner });
+        await delay(30);
+        assert.equal(calls, 1);
+        gate.resolve();
+        await Promise.all([activation, forced]);
+        assert.equal(calls, 2);
+        assert.equal(maxActive, 1);
+    }
+    finally {
+        if (previous === undefined)
+            delete process.env['CRTR_HOME'];
+        else
+            process.env['CRTR_HOME'] = previous;
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+test('a waiting process rechecks the marker so only one process runs migration', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'crtr-activation-process-race-'));
+    const release = join(home, 'release');
+    mkdirSync(home, { recursive: true });
+    try {
+        const first = childActivation(home, release);
+        await waitFor(() => readdirSync(home).some((entry) => entry.startsWith('entered.')));
+        const second = childActivation(home, release);
+        await delay(50);
+        assert.equal(readdirSync(home).filter((entry) => entry.startsWith('entered.')).length, 1);
+        writeFileSync(release, '');
+        await Promise.all([first, second]);
+        assert.equal(readdirSync(home).filter((entry) => entry.startsWith('entered.')).length, 1);
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});

package/dist/migrations/__tests__/activation.test.d.ts

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

package/dist/migrations/__tests__/activation.test.js

@@ -0,0 +1,149 @@
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { onDiskMigrationMarkerPath } from '../../core/canvas/paths.js';
+import { activateOnDiskMigrations, runForcedOnDiskMigrations } from '../activation.js';
+import { onDiskMigrationIdentity, STATE_MIGRATIONS } from '../registry.js';
+function result(options = {}) {
+    const writes = options.writes ?? [];
+    return {
+        blockers: options.blockers ?? [],
+        finalVerificationSucceeded: options.verified ?? true,
+        wrote: { profileManifests: writes, documents: [], corpusConsumers: [], corpusIdentities: [] },
+    };
+}
+async function inHome(run) {
+    const home = mkdtempSync(join(tmpdir(), 'crtr-migration-activation-'));
+    const previous = process.env['CRTR_HOME'];
+    process.env['CRTR_HOME'] = home;
+    try {
+        await run(home);
+    }
+    finally {
+        if (previous === undefined)
+            delete process.env['CRTR_HOME'];
+        else
+            process.env['CRTR_HOME'] = previous;
+        rmSync(home, { recursive: true, force: true });
+    }
+}
+function marker() {
+    return JSON.parse(readFileSync(onDiskMigrationMarkerPath(), 'utf8'));
+}
+test('activation skips only an exact current marker', async () => {
+    await inHome(async () => {
+        let runs = 0;
+        const runner = async () => { runs += 1; return result(); };
+        writeFileSync(onDiskMigrationMarkerPath(), JSON.stringify(onDiskMigrationIdentity()));
+        assert.equal(await activateOnDiskMigrations({ timeoutMs: 1_000, runner }), null);
+        assert.equal(runs, 0);
+        for (const invalid of [undefined, '{broken', JSON.stringify(onDiskMigrationIdentity().slice(0, -1))]) {
+            rmSync(onDiskMigrationMarkerPath(), { force: true });
+            if (invalid !== undefined)
+                writeFileSync(onDiskMigrationMarkerPath(), invalid);
+            assert.notEqual(await activateOnDiskMigrations({ timeoutMs: 1_000, runner }), null);
+        }
+        assert.equal(runs, 3);
+        assert.deepEqual(marker(), onDiskMigrationIdentity());
+    });
+});
+// The repository-root cut renamed migration 003, and the rename is the whole
+// invalidation mechanism: every home carrying the superseded identity must run
+// the corpus lane again. These ids are written literally rather than through
+// `onDiskMigrationIdentity()` so a rename that silently keeps the old marker
+// valid fails here.
+test('a superseded 003 identity reruns the corpus lane and the repository-root identity skips it', async () => {
+    await inHome(async () => {
+        let runs = 0;
+        const runner = async () => { runs += 1; return result(); };
+        writeFileSync(onDiskMigrationMarkerPath(), JSON.stringify([
+            { id: '001-surfaces-frontmatter', lane: 'convergent' },
+            { id: '002-profile-project-memory', lane: 'profile-manifest' },
+            { id: '003-workspace-qualified-memory-identity', lane: 'corpus' },
+        ]));
+        assert.notEqual(await activateOnDiskMigrations({ timeoutMs: 1_000, runner }), null, 'the superseded 003 identity must not satisfy activation');
+        assert.equal(runs, 1);
+        const repositoryRootIdentity = [
+            { id: '001-surfaces-frontmatter', lane: 'convergent' },
+            { id: '002-profile-project-memory', lane: 'profile-manifest' },
+            { id: '003-repository-root-memory-identity', lane: 'corpus' },
+        ];
+        assert.deepEqual(marker(), repositoryRootIdentity, 'the rerun records the repository-root identity in order');
+        writeFileSync(onDiskMigrationMarkerPath(), JSON.stringify(repositoryRootIdentity));
+        assert.equal(await activateOnDiskMigrations({ timeoutMs: 1_000, runner }), null);
+        assert.equal(runs, 1, 'the repository-root marker skips the run');
+    });
+});
+test('journaled database entries do not change the on-disk marker identity', () => {
+    const before = onDiskMigrationIdentity();
+    const registry = STATE_MIGRATIONS;
+    registry.push({ lane: 'journaled', description: 'test database migration', apply: () => undefined });
+    try {
+        assert.deepEqual(onDiskMigrationIdentity(), before);
+    }
+    finally {
+        registry.pop();
+    }
+});
+test('forced runs ignore current markers while dry runs leave marker bytes untouched', async () => {
+    await inHome(async () => {
+        const current = JSON.stringify(onDiskMigrationIdentity());
+        writeFileSync(onDiskMigrationMarkerPath(), current);
+        let runs = 0;
+        await runForcedOnDiskMigrations({
+            timeoutMs: 1_000,
+            runner: async () => { runs += 1; return result(); },
+        });
+        assert.equal(runs, 1);
+        assert.deepEqual(marker(), onDiskMigrationIdentity());
+        writeFileSync(onDiskMigrationMarkerPath(), '{malformed but preserved');
+        await runForcedOnDiskMigrations({
+            timeoutMs: 1_000,
+            dryRun: true,
+            runner: async () => { runs += 1; return result({ verified: false }); },
+        });
+        assert.equal(readFileSync(onDiskMigrationMarkerPath(), 'utf8'), '{malformed but preserved');
+        assert.equal(runs, 2);
+    });
+});
+test('failure leaves the marker absent and a later activation converges', async () => {
+    await inHome(async () => {
+        await assert.rejects(activateOnDiskMigrations({ timeoutMs: 1_000, runner: async () => { throw new Error('interrupted'); } }), /interrupted/);
+        assert.equal(existsSync(onDiskMigrationMarkerPath()), false);
+        await activateOnDiskMigrations({ timeoutMs: 1_000, runner: async () => result() });
+        assert.deepEqual(marker(), onDiskMigrationIdentity());
+    });
+});
+test('an unreadable profile blocker aborts startup effects with its path and repair command', async () => {
+    await inHome(async (home) => {
+        const blockedPath = join(home, 'profiles', 'bad-deadbeef', 'profile.json');
+        const writtenPath = join(home, 'profiles', 'root', 'profile.json');
+        const effects = { database: false, pidfile: false, api: false, broker: false };
+        const startup = async () => {
+            await activateOnDiskMigrations({
+                timeoutMs: 1_000,
+                runner: async () => result({
+                    verified: false,
+                    writes: [writtenPath],
+                    blockers: [{ kind: 'parse-failure', message: 'profile manifest is not valid JSON', path: blockedPath }],
+                }),
+            });
+            effects.database = true;
+            effects.pidfile = true;
+            effects.api = true;
+            effects.broker = true;
+        };
+        await assert.rejects(startup(), (error) => {
+            assert.ok(error instanceof Error);
+            assert.match(error.message, /on-disk migration blocked by 1 finding/);
+            assert.match(error.message, new RegExp(blockedPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+            assert.match(error.message, new RegExp(writtenPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+            assert.match(error.message, /Repair: crtr sys migrate/);
+            return true;
+        });
+        assert.deepEqual(effects, { database: false, pidfile: false, api: false, broker: false });
+        assert.equal(existsSync(onDiskMigrationMarkerPath()), false);
+    });
+});

package/dist/migrations/__tests__/deletion-and-root-declaration.test.d.ts

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