@north-light/api 0.3.580 → 0.3.588

package/dist/migrations/004-canvas-documents/apply.js

@@ -0,0 +1,113 @@
+// Writes an import plan into canvas.db: owners, documents with their revisions and
+// their bodies (content-addressed rows in `bodies`), links, the
+// authors' acted-on edges and watches, and the done-record, in one transaction.
+// Publishes nothing: the import is history, not activity.
+import { put as putBody } from '../../core/graph/bodies.js';
+import { importDocument } from '../../core/graph/documents.js';
+import { linksIn } from '../../core/graph/documents.js';
+import { recordActedOn, setLinks } from '../../core/graph/edges.js';
+import { resolveName } from '../../core/graph/names.js';
+import { ensureOwner, nodeObject, ownerForGrantee } from '../../core/graph/objects.js';
+import { ensureRepo } from '../../core/graph/repo-sync/repos.js';
+import { recordWatch } from '../../core/graph/watches.js';
+import { mapAsync } from '../../core/async-array.js';
+import { personId } from '../../core/canvas/person.js';
+/** The canvas_meta key whose presence means this home's legacy stores were imported. */
+export const IMPORT_DONE_KEY = 'canvas-import';
+export const IMPORT_ID = '004-canvas-documents';
+export async function readImportRecord(db) {
+    const row = await db.prepareUncached('SELECT value FROM canvas_meta WHERE key = ?').get(IMPORT_DONE_KEY);
+    if (row === undefined)
+        return null;
+    const report = JSON.parse(row.value).report;
+    return { ...report, resolutions: report.resolutions ?? [] };
+}
+/** Run inside the caller's write transaction; each revision's text is stored in it. Throws on any divergence from the plan. */
+export async function applyPlan(db, plan) {
+    const hashes = new Map();
+    for (const d of plan.documents)
+        for (const r of d.revisions)
+            if (!hashes.has(r.body))
+                hashes.set(r.body, await putBody(db, r.body));
+    const planned = new Map(plan.owners.map((o) => [o.key, o]));
+    const rows = new Map();
+    const ownerRow = async (o) => {
+        const known = rows.get(o.key);
+        if (known)
+            return known;
+        let row;
+        switch (o.type) {
+            case 'person':
+                row = await ownerForGrantee(db, personId());
+                break;
+            case 'app':
+                row = await ensureOwner(db, 'app', 'app', `app:${o.handle}`, o.handle);
+                break;
+            case 'profile': {
+                const app = planned.get(o.ownerKey);
+                if (!app)
+                    throw new Error(`import: profile ${o.key} names unplanned app ${o.ownerKey}`);
+                row = await ensureOwner(db, 'profile', 'profile', o.key.slice('profile:'.length), o.handle, await ownerRow(app));
+                break;
+            }
+            case 'repo':
+                row = await ensureRepo(db, { scheme: o.scheme, externalId: o.externalId, handleHint: o.handle }, o.handle);
+                break;
+            case 'node':
+                row = await nodeObject(db, o.handle);
+                break;
+        }
+        if (o.type !== 'node' && row.name !== o.handle)
+            throw new Error(`import: owner ${o.key} holds handle ${row.name}, planned ${o.handle}`);
+        rows.set(o.key, row);
+        return row;
+    };
+    const person = await ownerRow(planned.get('person') ?? { key: 'person', type: 'person', handle: 'user' });
+    const reader = { class: 'person', person };
+    const nodes = new Map();
+    const node = async (id) => {
+        let row = nodes.get(id);
+        if (!row)
+            nodes.set(id, (row = await nodeObject(db, id)));
+        return row;
+    };
+    const imported = [];
+    for (const d of plan.documents) {
+        const owner = await ownerRow(planned.get(d.ownerKey));
+        const doc = await importDocument(db, {
+            owner, name: d.name, kind: d.kind, preview: d.preview, privacy: d.privacy,
+            summary: d.summary, whyItExists: d.whyItExists, unlisted: d.unlisted, rules: d.rules,
+            lintIgnore: d.lintIgnore, extensions: d.extensions,
+            revisions: (await mapAsync(d.revisions, async (r) => ({
+                body_hash: hashes.get(r.body), author: r.authorNodeId === null ? null : await node(r.authorNodeId),
+                rationale: r.rationale, created_at: r.createdAt,
+            }))),
+        });
+        const authors = new Set(d.revisions.flatMap((r) => (r.authorNodeId === null ? [] : [r.authorNodeId])));
+        imported.push({ doc, owner, body: d.revisions[d.revisions.length - 1].body, authors });
+    }
+    // Links resolve after every document exists; a bare name prefers the linking document's owner.
+    for (const { doc, owner, body, authors } of imported) {
+        const links = [];
+        for (const name of linksIn(body)) {
+            const candidates = name.includes('/') ? [name] : [`${owner.type === 'node' ? owner.id : owner.name}/${name}`, name];
+            for (const c of candidates) {
+                const hit = await resolveName(db, reader, c);
+                if ('object' in hit) {
+                    links.push({ written_as: name, dst: hit.object });
+                    break;
+                }
+                if ('deleted' in hit) {
+                    links.push({ written_as: name, dst: hit.deleted });
+                    break;
+                }
+            }
+        }
+        await setLinks(db, doc, links);
+        for (const id of authors) {
+            await recordActedOn(db, await node(id), doc);
+            await recordWatch(db, await node(id), doc, 'write');
+        }
+    }
+    await db.prepareUncached('INSERT INTO canvas_meta (key, value) VALUES (?, ?)').run(IMPORT_DONE_KEY, JSON.stringify({ id: IMPORT_ID, report: plan.report }));
+}

package/dist/migrations/004-canvas-documents/fields.d.ts

@@ -0,0 +1,24 @@
+import { type Privacy, type RuleSpec } from '../../core/graph/types.js';
+export type DocumentKind = 'knowledge' | 'preference' | 'report';
+export interface DocumentFields {
+    kind: DocumentKind;
+    privacy: Privacy;
+    preview: string;
+    summary: string | null;
+    whyItExists: string | null;
+    unlisted: boolean;
+    lintIgnore: unknown;
+    extensions: unknown;
+    rules: RuleSpec[];
+    /** Frontmatter keys with no document field; listed in the report. */
+    dropped: string[];
+}
+/** First non-empty body line, with a leading markdown heading or list marker removed. */
+export declare function firstLine(body: string): string;
+/** `missingPrivacy` is what a document without a valid `privacy` key gets. */
+export declare function documentFields(fm: Record<string, unknown> | null, body: string, opts: {
+    kind?: DocumentKind;
+    missingPrivacy: Privacy;
+}): DocumentFields;
+/** AND `extra` into every rule's `if` (private repo documents re-owned to the person). */
+export declare function andIntoRules(rules: RuleSpec[], extra: Record<string, unknown>): RuleSpec[];

package/dist/migrations/004-canvas-documents/fields.js

@@ -0,0 +1,52 @@
+// Legacy frontmatter → document fields and rule rows (spec §1 field table).
+// Rules come from D1's `rulesFromFrontmatter`, the only frontmatter converter.
+import { rulesFromFrontmatter } from '../../core/graph/rules.js';
+import { readLegacyPrivacy } from '../../core/graph/types.js';
+/** Keys the import converts or consumes; every other key is dropped. */
+const HANDLED = new Set([
+    'kind', 'privacy', 'unlisted', 'lint-ignore', 'extensions', 'when-and-why-to-read', 'short-form', 'rationale',
+    'surfaces', 'gate', 'slash', 'origin', 'last-updated', 'name', 'namespace',
+]);
+const PRIVACIES = ['public', 'private'];
+const str = (v) => (typeof v === 'string' && v.trim() !== '' ? v.trim() : null);
+/** First non-empty body line, with a leading markdown heading or list marker removed. */
+export function firstLine(body) {
+    for (const line of body.split('\n')) {
+        const t = line.trim().replace(/^#+\s*/, '').replace(/^[-*]\s+/, '').trim();
+        if (t !== '' && t !== '---')
+            return t;
+    }
+    return '';
+}
+/** `missingPrivacy` is what a document without a valid `privacy` key gets. */
+export function documentFields(fm, body, opts) {
+    const f = fm ?? {};
+    const dropped = Object.keys(f).filter((k) => !HANDLED.has(k));
+    let kind = opts.kind ?? 'knowledge';
+    if (opts.kind === undefined && f['kind'] !== undefined) {
+        if (f['kind'] === 'knowledge' || f['kind'] === 'preference')
+            kind = f['kind'];
+        else
+            dropped.push('kind');
+    }
+    const given = readLegacyPrivacy(f['privacy']);
+    const privacy = typeof given === 'string' && PRIVACIES.includes(given)
+        ? given
+        : opts.missingPrivacy;
+    return {
+        kind,
+        privacy,
+        preview: str(f['when-and-why-to-read'])?.replace(/\s+/g, ' ') ?? firstLine(body),
+        summary: str(f['short-form']),
+        whyItExists: str(f['rationale']),
+        unlisted: f['unlisted'] === true,
+        lintIgnore: f['lint-ignore'] ?? null,
+        extensions: f['extensions'] ?? null,
+        rules: rulesFromFrontmatter(f),
+        dropped,
+    };
+}
+/** AND `extra` into every rule's `if` (private repo documents re-owned to the person). */
+export function andIntoRules(rules, extra) {
+    return rules.map((r) => ({ ...r, if: r.if === undefined ? extra : { all: [r.if, extra] } }));
+}

package/dist/migrations/004-canvas-documents/index.d.ts

@@ -0,0 +1,16 @@
+import { type ImportBlocker, type ImportReport } from './plan.js';
+export type { ImportBlocker, ImportReport } from './plan.js';
+export interface CanvasImportResult {
+    report: ImportReport;
+    blockers: ImportBlocker[];
+    dryRun: boolean;
+    /** True while this home still has to be imported (always false after a write run succeeds). */
+    pending: boolean;
+}
+/** Whether this home's import has already been recorded. */
+export declare function canvasImportDone(): Promise<boolean>;
+/** Plan and (unless `dryRun` or blocked) apply the import. On an imported home a dry run
+ *  returns the recorded report; a write run does nothing and returns empty counts. */
+export declare function runCanvasImport(opts: {
+    dryRun: boolean;
+}): Promise<CanvasImportResult>;

package/dist/migrations/004-canvas-documents/index.js

@@ -0,0 +1,88 @@
+// 004-canvas-documents — the one cut: every pre-canvas memory store, node
+// context folder and report file becomes canvas documents. The daemon runs it
+// at startup and resolves every clash itself, reporting each resolution; only
+// a runtime that skipped the previous release's store migrations blocks it,
+// holding startup in `blocked` until `crtr sys migrate` finds a clean plan.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { openDb, withCanvasWrite } from '../../core/canvas/db.js';
+import { nodeAgentDir, nodeRecordDir, onDiskMigrationMarkerPath } from '../../core/canvas/paths.js';
+import { identifyCheckout } from '../../core/graph/repo-sync/identity.js';
+import { profileSpace, userRoot } from '../../core/layout.js';
+import { deleteLegacyProjectCaps, listLegacyProjectCaps, readLegacyUserSnapshot } from '../../core/scoped-state/legacy-profiles.js';
+import { personIdAsync } from '../../core/canvas/person.js';
+import { userStore } from '../../core/scoped-state/paths.js';
+import { userScopeRoot } from '../../core/scope.js';
+import { LEGACY_LOCAL_PERSON } from '../../core/canvas/legacy-person.js';
+import { applyPlan, readImportRecord } from './apply.js';
+import { readLegacyCorpus, readMarkerIds } from './legacy/discover.js';
+import { planImport } from './plan.js';
+const emptyReport = () => ({ stores: [], counts: {}, rewrites: [], droppedFields: [], skipped: [], resolutions: [] });
+async function legacyRoots() {
+    const scope = userScopeRoot();
+    const stored = readLegacyUserSnapshot(scope)?.profiles ?? [];
+    const caps = listLegacyProjectCaps(scope);
+    const manifestStore = userStore(scope).path;
+    const profiles = stored.map(({ profileId, manifest }) => {
+        const app = manifest.grantee ?? 'app:terminal';
+        const mine = new Map(caps.filter((c) => c.profileId === profileId).map((c) => [c.path, c.memory]));
+        return {
+            id: profileId, name: manifest.name, app, memory: profileSpace(app, profileId).dir,
+            projects: manifest.projects.map((p) => p.path),
+            raw: { projects: manifest.projects.map((p) => (mine.has(p.path) ? { path: p.path, memory: mine.get(p.path) } : { path: p.path })) },
+            manifestPath: `${manifestStore}#${profileId}`,
+        };
+    });
+    const rows = await (await openDb()).prepareUncached('SELECT node_id, cwd, grantee FROM node_rows ORDER BY created').all();
+    const nodes = rows.map((r) => {
+        // An app node's folder is in its app space; any other node's is its record folder.
+        // Stage L placed a legacy-local-person row's folders in the terminal app, as migration v49 assigns it.
+        const app = r.grantee === LEGACY_LOCAL_PERSON ? 'app:terminal' : r.grantee;
+        const agent = app?.startsWith('app:') ? nodeAgentDir(r.node_id, app) : null;
+        const dir = agent !== null && (existsSync(join(agent, 'context')) || existsSync(join(agent, 'reports'))) ? agent : nodeRecordDir(r.node_id);
+        return { id: r.node_id, dir };
+    });
+    return {
+        // The layout migration moved the old user store to user/memory.
+        roots: { userMemory: join(userRoot(), 'memory'), profiles, nodeCwds: [...new Set(rows.map((r) => r.cwd))], nodes },
+        stored,
+    };
+}
+async function plan() {
+    const { roots, stored } = await legacyRoots();
+    const corpus = readLegacyCorpus(roots);
+    const existingOwners = await (await openDb()).prepareUncached(`SELECT o.type, o.name AS handle, i.external_id AS externalId FROM objects o
+    LEFT JOIN identities i ON i.object = o.id WHERE o.type IN ('person','app','repo','profile')`).all();
+    return planImport(corpus, {
+        roots,
+        markerIds: readMarkerIds(onDiskMigrationMarkerPath()),
+        repoIdentity: identifyCheckout,
+        existingOwners,
+        storedProfiles: stored.map((p) => ({ id: p.profileId, deliveryLimits: { ...(p.manifest.delivery_limits ?? {}) } })),
+    });
+}
+/** Whether this home's import has already been recorded. */
+export async function canvasImportDone() {
+    return await readImportRecord(await openDb()) !== null;
+}
+/** Plan and (unless `dryRun` or blocked) apply the import. On an imported home a dry run
+ *  returns the recorded report; a write run does nothing and returns empty counts. */
+export async function runCanvasImport(opts) {
+    const recorded = await readImportRecord(await openDb());
+    if (recorded !== null)
+        return { report: opts.dryRun ? recorded : emptyReport(), blockers: [], dryRun: opts.dryRun, pending: false };
+    const p = await plan();
+    if (opts.dryRun || p.blockers.length > 0)
+        return { report: p.report, blockers: p.blockers, dryRun: opts.dryRun, pending: true };
+    // Scoped-state caps convert first: a crash after it leaves the canvas import still pending,
+    // and a re-plan reads the converted limits instead of the (deleted) cap rows.
+    const person = await personIdAsync();
+    await withCanvasWrite(async (db) => {
+        for (const l of p.profileLimits)
+            if ((await db.prepare('UPDATE profiles SET delivery_limits_json = ? WHERE id = ? AND person = ?').run(JSON.stringify(l.deliveryLimits), l.profileId, person)).changes !== 1)
+                throw new Error(`no stored profile ${l.profileId}`);
+    });
+    deleteLegacyProjectCaps(userScopeRoot());
+    await withCanvasWrite(async (db) => await applyPlan(db, p));
+    return { report: p.report, blockers: [], dryRun: false, pending: false };
+}

package/dist/migrations/004-canvas-documents/legacy/discover.d.ts

@@ -0,0 +1,16 @@
+import type { LegacyCorpus, LegacyProfile, LegacyRoots } from './types.js';
+export type { LegacyCorpus, LegacyDoc, LegacyOwnerRef, LegacyProfile, LegacyRoots, LegacyStoreRoot, LegacyHistoryRecord } from './types.js';
+/** Every stored profile manifest, read as raw JSON (the current manifest reader
+ *  is not used). `memoryFor(app, id)` resolves the profile's store path. */
+export declare function readLegacyProfiles(profilesRoot: string, memoryFor: (app: string, id: string) => string): {
+    profiles: LegacyProfile[];
+    skipped: Array<{
+        path: string;
+        reason: string;
+    }>;
+};
+/** Ids listed in `<canvas home>/on-disk-migrations.json`, or null when the marker is absent. */
+export declare function readMarkerIds(markerPath: string): string[] | null;
+export declare function readLegacyCorpus(roots: LegacyRoots): LegacyCorpus;
+/** Cheap probe: is there any legacy document to import? */
+export declare function hasLegacyContent(roots: LegacyRoots): boolean;

package/dist/migrations/004-canvas-documents/legacy/discover.js

@@ -0,0 +1,251 @@
+// Frozen legacy reader: finds every pre-canvas store, node context folder and
+// report file on the discovery frontier and reads them as data for the import
+// plan. fs-only; never opens canvas.db, never writes.
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { walkFiles } from '../../../core/fs-utils.js';
+import { historyLogPath, HISTORY_DIR, readHistory } from './history.js';
+import { walkNestedStores } from './nested.js';
+import { contextDocName, parseFile, rawFile, storeDocName } from './parse.js';
+const PROFILE_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*-[0-9a-f]{8}$/;
+function real(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+const isDir = (p) => {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+/** A `.crouter` folder that is a crouter home (the old user scope beside its canvas,
+ *  runtime, or profiles), not a project scope: legacy crouter never treated it as a
+ *  project, and taking its parent (a home directory) as a project root would walk
+ *  the whole home folder. */
+const isCrouterHome = (dotCrouter) => ['canvas', 'canvas.db', 'runtime', 'profiles'].some((n) => existsSync(join(dotCrouter, n)));
+const markdownIn = (root) => walkFiles(root, (n) => n.toLowerCase().endsWith('.md'), (n) => n.startsWith('.')).sort();
+/** Every stored profile manifest, read as raw JSON (the current manifest reader
+ *  is not used). `memoryFor(app, id)` resolves the profile's store path. */
+export function readLegacyProfiles(profilesRoot, memoryFor) {
+    const profiles = [];
+    const skipped = [];
+    if (!isDir(profilesRoot))
+        return { profiles, skipped };
+    for (const id of readdirSync(profilesRoot).sort()) {
+        const manifestPath = join(profilesRoot, id, 'profile.json');
+        if (!PROFILE_ID.test(id) || !existsSync(manifestPath))
+            continue;
+        let raw;
+        try {
+            const parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+                throw new Error('not a JSON object');
+            raw = parsed;
+        }
+        catch (e) {
+            skipped.push({ path: manifestPath, reason: `invalid-manifest: ${e.message}` });
+            continue;
+        }
+        const app = typeof raw['grantee'] === 'string' ? raw['grantee'] : 'app:terminal';
+        const projects = Array.isArray(raw['projects'])
+            ? raw['projects'].flatMap((p) => (typeof p === 'string' ? [p] : p !== null && typeof p === 'object' && typeof p.path === 'string' ? [p.path] : []))
+            : [];
+        profiles.push({ id, name: typeof raw['name'] === 'string' ? raw['name'] : id, app, memory: memoryFor(app, id), projects, raw, manifestPath });
+    }
+    return { profiles, skipped };
+}
+/** Ids listed in `<canvas home>/on-disk-migrations.json`, or null when the marker is absent. */
+export function readMarkerIds(markerPath) {
+    if (!existsSync(markerPath))
+        return null;
+    const parsed = JSON.parse(readFileSync(markerPath, 'utf8'));
+    if (!Array.isArray(parsed))
+        throw new Error(`${markerPath}: not a JSON array`);
+    return parsed.map((e) => (typeof e === 'string' ? e : String(e.id)));
+}
+/** The git common dir of a checkout (`.git` dir, or a linked worktree's `gitdir` → `commondir`), or null. */
+function gitCommonDir(root) {
+    const dotGit = join(root, '.git');
+    if (isDir(dotGit))
+        return real(dotGit);
+    if (!existsSync(dotGit))
+        return null;
+    const m = /^gitdir:\s*(.+)$/m.exec(readFileSync(dotGit, 'utf8'));
+    if (!m)
+        return null;
+    const gitdir = isAbsolute(m[1].trim()) ? m[1].trim() : resolve(root, m[1].trim());
+    const commondirFile = join(gitdir, 'commondir');
+    if (!existsSync(commondirFile))
+        return real(gitdir);
+    const c = readFileSync(commondirFile, 'utf8').trim();
+    return real(isAbsolute(c) ? c : resolve(gitdir, c));
+}
+export function readLegacyCorpus(roots) {
+    const corpus = { docs: [], storeRoots: [], skipped: [], orphanHistory: 0, orphanNodeDirs: 0, nonMarkdown: 0, injectedDocs: 0 };
+    const personalStores = new Set([roots.userMemory, ...roots.profiles.map((p) => p.memory)].map(real));
+    const readStore = (storeRoot, owner, prefix) => {
+        const files = markdownIn(storeRoot);
+        const live = new Set(files.map((f) => historyLogPath(storeRoot, f)));
+        corpus.orphanHistory += walkFiles(join(storeRoot, HISTORY_DIR), (n) => n.endsWith('.jsonl')).filter((f) => !live.has(f)).length;
+        let count = 0;
+        for (const path of files) {
+            const name = prefix + storeDocName(relative(storeRoot, path));
+            let parsed;
+            try {
+                parsed = parseFile(path);
+            }
+            catch (e) {
+                corpus.docs.push({ path, owner, name, source: 'store', ...rawFile(path), history: [], invalid: { kind: 'invalid-source', reason: `invalid frontmatter: ${e.message}` } });
+                count += 1;
+                continue;
+            }
+            let history;
+            try {
+                history = readHistory(historyLogPath(storeRoot, path));
+            }
+            catch (e) {
+                corpus.docs.push({ path, owner, name, source: 'store', ...parsed, history: [], invalid: { kind: 'invalid-history', reason: `unreadable history log: ${e.message}` } });
+                count += 1;
+                continue;
+            }
+            corpus.docs.push({ path, owner, name, source: 'store', ...parsed, history });
+            count += 1;
+        }
+        corpus.storeRoots.push({ root: storeRoot, owner, docs: count });
+    };
+    if (isDir(roots.userMemory))
+        readStore(roots.userMemory, { type: 'person' }, '');
+    for (const p of roots.profiles)
+        if (isDir(p.memory))
+            readStore(p.memory, { type: 'profile', id: p.id }, '');
+    // Repositories: walk each frontier path up to its project root.
+    const projectRoot = (start) => {
+        let firstStore = null;
+        for (let dir = real(start);; dir = dirname(dir)) {
+            if (existsSync(join(dir, '.git')))
+                return dir;
+            const store = join(dir, '.crouter', 'memory');
+            if (firstStore === null && isDir(store) && !personalStores.has(real(store)) && !isCrouterHome(join(dir, '.crouter')))
+                firstStore = dir;
+            if (dirname(dir) === dir)
+                return firstStore;
+        }
+    };
+    const queue = [];
+    for (const start of [...roots.profiles.flatMap((p) => p.projects), ...roots.nodeCwds]) {
+        if (!isDir(start))
+            continue;
+        const root = projectRoot(start);
+        if (root !== null)
+            queue.push(root);
+    }
+    const byCommon = new Map();
+    const seen = new Set();
+    const repos = [];
+    while (queue.length > 0) {
+        const root = queue.shift();
+        if (seen.has(root))
+            continue;
+        seen.add(root);
+        const commonDir = gitCommonDir(root);
+        repos.push({ root, commonDir });
+        if (commonDir !== null) {
+            byCommon.set(commonDir, [...(byCommon.get(commonDir) ?? []), root]);
+            // Linked worktrees import from the main worktree, so bring it in.
+            const main = dirname(commonDir);
+            if (basename(commonDir) === '.git' && isDir(join(main, '.git')))
+                queue.push(main);
+        }
+        queue.push(...walkNestedStores(root).embeddedRepos);
+    }
+    for (const { root, commonDir } of repos.sort((a, b) => a.root.localeCompare(b.root))) {
+        const group = commonDir === null ? [root] : byCommon.get(commonDir);
+        const chosen = group.find((r) => isDir(join(r, '.git'))) ?? [...group].sort()[0];
+        const rootStore = join(root, '.crouter', 'memory');
+        const hasRootStore = isDir(rootStore) && !personalStores.has(real(rootStore));
+        const nested = walkNestedStores(root).nested.filter((rel) => !personalStores.has(real(join(root, rel, '.crouter', 'memory'))));
+        let namespace = null;
+        if (hasRootStore && existsSync(join(rootStore, 'INDEX.md'))) {
+            try {
+                const ns = parseFile(join(rootStore, 'INDEX.md')).frontmatter?.['namespace'];
+                if (typeof ns === 'string' && ns !== '')
+                    namespace = ns;
+            }
+            catch {
+                // imported by readStore below as a whole-file body
+            }
+        }
+        const owner = { type: 'repo', root, commonDir, namespace };
+        if (root !== chosen) {
+            if (hasRootStore)
+                corpus.storeRoots.push({ root: rootStore, owner, docs: 0, skipped: 'duplicate-worktree' });
+            for (const rel of nested)
+                corpus.storeRoots.push({ root: join(root, rel, '.crouter', 'memory'), owner, docs: 0, skipped: 'duplicate-worktree' });
+            continue;
+        }
+        if (hasRootStore)
+            readStore(rootStore, owner, '');
+        for (const rel of nested)
+            readStore(join(root, rel, '.crouter', 'memory'), owner, rel.split(/[\\/]/).join('/') + '/');
+    }
+    // Node folders.
+    const nodeIds = new Set(roots.nodes.map((n) => n.id));
+    for (const parent of new Set(roots.nodes.map((n) => dirname(n.dir)))) {
+        for (const e of readdirSync(parent, { withFileTypes: true }))
+            if (e.isDirectory() && !nodeIds.has(e.name))
+                corpus.orphanNodeDirs += 1;
+    }
+    for (const { id, dir } of roots.nodes) {
+        const owner = { type: 'node', id };
+        if (existsSync(join(dir, 'injected-docs.json')))
+            corpus.injectedDocs += 1;
+        const context = join(dir, 'context');
+        if (isDir(join(context, 'memory')))
+            readStore(join(context, 'memory'), owner, '');
+        const readPlain = (path, name, source) => {
+            try {
+                corpus.docs.push({ path, owner, name, source, ...parseFile(path), history: [] });
+            }
+            catch (e) {
+                corpus.docs.push({ path, owner, name, source, ...rawFile(path), history: [], invalid: { kind: 'invalid-source', reason: `invalid frontmatter: ${e.message}` } });
+            }
+        };
+        for (const path of walkFiles(context, () => true, (n) => n.startsWith('.')).sort()) {
+            const rel = relative(context, path);
+            const top = rel.split(/[\\/]/)[0];
+            if (top === 'memory' || top === 'jobs')
+                continue;
+            if (!path.toLowerCase().endsWith('.md'))
+                corpus.nonMarkdown += 1;
+            else
+                readPlain(path, contextDocName(rel), 'context');
+        }
+        const reports = join(dir, 'reports');
+        if (isDir(reports)) {
+            for (const e of readdirSync(reports, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+                if (!e.isFile())
+                    continue;
+                if (!e.name.toLowerCase().endsWith('.md'))
+                    corpus.nonMarkdown += 1;
+                else
+                    readPlain(join(reports, e.name), `reports/${e.name.replace(/\.md$/i, '')}`, 'report');
+            }
+        }
+    }
+    return corpus;
+}
+/** Cheap probe: is there any legacy document to import? */
+export function hasLegacyContent(roots) {
+    const anyMd = (dir) => isDir(dir) && markdownIn(dir).length > 0;
+    if (anyMd(roots.userMemory) || roots.profiles.some((p) => anyMd(p.memory)))
+        return true;
+    if (roots.nodes.some((n) => anyMd(join(n.dir, 'context')) || anyMd(join(n.dir, 'reports'))))
+        return true;
+    return readLegacyCorpus({ ...roots, nodes: [] }).docs.length > 0;
+}

package/dist/migrations/004-canvas-documents/legacy/history.d.ts

@@ -0,0 +1,5 @@
+import type { LegacyHistoryRecord } from './types.js';
+export declare const HISTORY_DIR = ".history";
+export declare function historyLogPath(storeRoot: string, docPath: string): string;
+/** Records of the current life, or throws naming the bad line. */
+export declare function readHistory(logPath: string): LegacyHistoryRecord[];

package/dist/migrations/004-canvas-documents/legacy/history.js

@@ -0,0 +1,37 @@
+// Frozen reader of `<store>/memory/.history/<physical path>.jsonl`. The log
+// mirrors the document's physical path and travels with it on a move, so the
+// current file's log holds its whole history; a prior deleted life of the same
+// path precedes the last `delete` record and is not this document's history.
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+export const HISTORY_DIR = '.history';
+export function historyLogPath(storeRoot, docPath) {
+    return join(storeRoot, HISTORY_DIR, relative(storeRoot, docPath).replace(/\.md$/i, '') + '.jsonl');
+}
+/** Records of the current life, or throws naming the bad line. */
+export function readHistory(logPath) {
+    if (!existsSync(logPath))
+        return [];
+    const records = [];
+    const lines = readFileSync(logPath, 'utf8').split('\n');
+    lines.forEach((line, i) => {
+        if (line.trim() === '')
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (e) {
+            throw new Error(`line ${i + 1}: ${e.message}`);
+        }
+        const r = parsed;
+        if (r === null || typeof r !== 'object' || typeof r.op !== 'string' || typeof r.at !== 'string' || typeof r.after !== 'string') {
+            throw new Error(`line ${i + 1}: not a history record`);
+        }
+        if (r.op === 'delete')
+            records.length = 0;
+        else
+            records.push(r);
+    });
+    return records;
+}

package/dist/migrations/004-canvas-documents/legacy/nested.d.ts

@@ -0,0 +1,7 @@
+export interface NestedWalk {
+    /** `<rel>` of each `<root>/<rel>/.crouter/memory`, rel non-empty. */
+    nested: string[];
+    /** Folders below the root holding their own `.git`. */
+    embeddedRepos: string[];
+}
+export declare function walkNestedStores(root: string): NestedWalk;

package/dist/migrations/004-canvas-documents/legacy/nested.js

@@ -0,0 +1,37 @@
+// Exhaustive walk for `.crouter/memory` stores below a project root, frozen from
+// the retired runtime nested-store walk with the migration's rules: no time or
+// depth budget; skip `.git`, `node_modules` and every other dot-dir; stop at an
+// embedded repository (it is its own repo and is returned separately so the
+// caller imports it under its own owner).
+import { existsSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+export function walkNestedStores(root) {
+    const out = { nested: [], embeddedRepos: [] };
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir !== root) {
+            if (existsSync(join(dir, '.git'))) {
+                out.embeddedRepos.push(dir);
+                continue;
+            }
+            if (existsSync(join(dir, '.crouter', 'memory')))
+                out.nested.push(relative(root, dir));
+        }
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (!e.isDirectory() || e.name.startsWith('.') || e.name === 'node_modules')
+                continue;
+            stack.push(join(dir, e.name));
+        }
+    }
+    out.nested.sort();
+    out.embeddedRepos.sort();
+    return out;
+}