@north-light/crouter 0.3.208 → 0.3.209

package/dist/core/substrate/surface-match.js

@@ -0,0 +1,179 @@
+// surface-match.ts — the per-event matchers for `surfaces` entries, plus the
+// owning-root helpers they anchor on. Pure: every function takes its subject
+// explicitly (the read file, the resolved doc name, the command string) and
+// touches no store discovery.
+//
+// Match semantics (design: surfaces-design.md): constraints within one entry
+// AND together — each present constraint must fit, a `match` list is satisfied
+// by any one glob — and multiple entries per event OR together. The `./`
+// prefix is the one relative spelling: it anchors a glob to the doc's own
+// container (its owning repo dir for `read`, its name-directory for
+// `memory-read`).
+import { basename, isAbsolute, matchesGlob, relative, sep } from 'node:path';
+import { CRTR_DIR_NAME } from '../../types.js';
+import { realpathOrSelf } from '../fs-utils.js';
+import { evalCondition } from '../predicate.js';
+import { rungRank } from './schema.js';
+/** The project directory owning a doc's store: the path segment stack above
+ *  the doc's `.crouter` dir. `null` when the doc's path carries no `.crouter`
+ *  segment (builtin docs). */
+export function owningRootOf(doc) {
+    const parts = doc.path.split(sep);
+    const idx = parts.lastIndexOf(CRTR_DIR_NAME);
+    if (idx <= 0)
+        return null;
+    return parts.slice(0, idx).join(sep) || sep;
+}
+/** True when the (already-realpathed) file sits beneath the doc's store's
+ *  owning directory. Callers additionally guard on `doc.scope === 'project'`:
+ *  a profile store's path computes an owning root of `~`, and user/builtin/
+ *  node docs likewise have no project-owning dir, so a `./`-anchored glob
+ *  outside a project store must never match. */
+export function underOwningRoot(doc, absFile) {
+    const root = owningRootOf(doc);
+    if (root === null)
+        return false;
+    const rel = relative(realpathOrSelf(root), absFile);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
+function safeGlob(target, glob) {
+    try {
+        return matchesGlob(target, glob);
+    }
+    catch {
+        return false;
+    }
+}
+/** One read-event glob vs the read file: plain globs match the absolute path
+ *  and the basename; a `./`-anchored glob matches the path relative to the
+ *  doc's store's owning repo dir (project-store docs only). */
+function readGlobMatches(glob, doc, absReadFile) {
+    if (glob.startsWith('./')) {
+        if (doc.scope !== 'project' || !underOwningRoot(doc, absReadFile))
+            return false;
+        const root = owningRootOf(doc);
+        if (root === null)
+            return false;
+        return safeGlob(relative(realpathOrSelf(root), absReadFile), glob.slice(2));
+    }
+    return safeGlob(absReadFile, glob) || safeGlob(basename(absReadFile), glob);
+}
+/** Does a `read` entry fit the read file? `absReadFile` must already be
+ *  realpathed. `readFrontmatter` is the read file's own parsed YAML (empty
+ *  for non-markdown files); an empty record never satisfies
+ *  `matchFrontmatter`. */
+export function matchesReadEntry(entry, doc, absReadFile, readFrontmatter) {
+    if (entry.on !== 'read')
+        return false;
+    if (entry.match !== undefined && !entry.match.some((g) => readGlobMatches(g, doc, absReadFile))) {
+        return false;
+    }
+    if (entry.matchFrontmatter !== undefined) {
+        if (Object.keys(readFrontmatter).length === 0)
+            return false;
+        if (!evalCondition(entry.matchFrontmatter, readFrontmatter))
+            return false;
+    }
+    return entry.match !== undefined || entry.matchFrontmatter !== undefined;
+}
+/** One memory-read glob vs the resolved doc's names: plain globs match any of
+ *  the caller-supplied target names (the full canonical name, plus the
+ *  mount-stripped name for plugin-mounted docs); a `./`-anchored glob matches
+ *  each target relative to the CARRIER doc's own name-directory. Names are
+ *  slash-separated, so path globbing applies segment-wise. */
+function memoryReadGlobMatches(glob, carrierName, targetNames) {
+    if (glob.startsWith('./')) {
+        const dir = carrierName.split('/').slice(0, -1).join('/');
+        const stripped = glob.slice(2);
+        return targetNames.some((name) => {
+            if (dir === '')
+                return safeGlob(name, stripped);
+            if (!name.startsWith(dir + '/'))
+                return false;
+            return safeGlob(name.slice(dir.length + 1), stripped);
+        });
+    }
+    return targetNames.some((name) => safeGlob(name, glob));
+}
+/** Does a `memory-read` entry on the doc named `carrierName` fit a resolved
+ *  read of a doc known by `targetNames`? */
+export function matchesMemoryReadEntry(entry, carrierName, targetNames) {
+    if (entry.on !== 'memory-read' || entry.match === undefined)
+        return false;
+    return entry.match.some((g) => memoryReadGlobMatches(g, carrierName, targetNames));
+}
+/** A command glob is a STRING glob over the whole command line, not a path
+ *  glob: `*` crosses every character (including `/` — command lines carry
+ *  paths), `?` matches one. Translated to a regex rather than fed to
+ *  `matchesGlob`, whose `*` stops at path separators. */
+function commandGlobMatches(glob, command) {
+    const rx = glob
+        .split('')
+        .map((ch) => (ch === '*' ? '[\\s\\S]*' : ch === '?' ? '[\\s\\S]' : ch.replace(/[.+^${}()|[\]\\]/g, '\\$&')))
+        .join('');
+    try {
+        return new RegExp(`^${rx}$`).test(command);
+    }
+    catch {
+        return false;
+    }
+}
+/** Does a `command` entry fit the executed command string? */
+export function matchesCommandEntry(entry, command) {
+    if (entry.on !== 'command' || entry.match === undefined)
+        return false;
+    return entry.match.some((g) => commandGlobMatches(g, command));
+}
+// ---------------------------------------------------------------------------
+// Per-doc rung folds — a doc's delivery rung for one event occurrence is the
+// highest `at` over its matching entries of that event, `none` when none
+// match (entries OR together; `none` is the internal "does not deliver"
+// floor, never an authored rung).
+// ---------------------------------------------------------------------------
+/** The doc's delivery rung for a read of `absReadFile` (already realpathed). */
+export function readDeliveryRung(doc, absReadFile, readFrontmatter) {
+    let r = 'none';
+    for (const e of doc.surfaces) {
+        if (!matchesReadEntry(e, doc, absReadFile, readFrontmatter))
+            continue;
+        if (rungRank(e.at) > rungRank(r))
+            r = e.at;
+    }
+    return r;
+}
+/** The doc's workspace-open rung. Presence of an entry is the match; callers
+ *  scope the corpus to project stores mounted by the subject's cwd/profile. */
+export function workspaceOpenRung(doc) {
+    let r = 'none';
+    for (const e of doc.surfaces) {
+        if (e.on !== 'workspace-open')
+            continue;
+        if (rungRank(e.at) > rungRank(r))
+            r = e.at;
+    }
+    return r;
+}
+/** The doc's delivery rung for a `crtr memory read` that resolved a doc
+ *  known by `targetNames` (canonical name, plus the mount-stripped name for
+ *  plugin-mounted docs). The doc's own `name` anchors `./` globs. */
+export function memoryReadDeliveryRung(doc, targetNames) {
+    let r = 'none';
+    for (const e of doc.surfaces) {
+        if (!matchesMemoryReadEntry(e, doc.name, targetNames))
+            continue;
+        if (rungRank(e.at) > rungRank(r))
+            r = e.at;
+    }
+    return r;
+}
+/** The doc's delivery rung for an executed command string. */
+export function commandDeliveryRung(doc, command) {
+    let r = 'none';
+    for (const e of doc.surfaces) {
+        if (!matchesCommandEntry(e, command))
+            continue;
+        if (rungRank(e.at) > rungRank(r))
+            r = e.at;
+    }
+    return r;
+}

package/dist/daemon/api/handlers/nodes.js

@@ -16,6 +16,7 @@ import { subtreeIds } from '../../../core/canvas/nav-model.js';
 import { contextDir, reportsDir } from '../../../core/canvas/paths.js';
 import { nodeArtifacts } from '../../../core/canvas/history.js';
 import { readNodeMessagesPage, readNodeSession, readNodeSnapshot, transcriptMarkdown } from '../../../core/runtime/node-read.js';
+import { assembleNodeSubject } from '../../../core/substrate/subject.js';
 import { reviveAll } from '../../../core/runtime/revive-all.js';
 import { promote, requestYield, reshapeNode } from '../../../core/runtime/promote.js';
 import { recycleNode } from '../../../core/runtime/recycle.js';
@@ -304,6 +305,13 @@ async function handleSnapshot(ctx) {
     };
     return { status: 200, body };
 }
+async function handleSubject(ctx) {
+    const id = ctx.params['id'];
+    const subject = assembleNodeSubject(id);
+    if (subject === null)
+        throw notFound(`unknown node: ${id}`, { received: id });
+    return { status: 200, body: subject };
+}
 function parseMessagesQuery(ctx) {
     for (const [field] of ctx.query) {
         if (field !== 'cursor' && field !== 'limit')
@@ -634,6 +642,7 @@ export const nodeRoutes = [
     { method: 'POST', pattern: '/v1/nodes/revive-all', handler: () => handleReviveAll() },
     { method: 'GET', pattern: '/v1/nodes/:id', handler: handleDetail },
     { method: 'GET', pattern: '/v1/nodes/:id/snapshot', handler: handleSnapshot },
+    { method: 'GET', pattern: '/v1/nodes/:id/subject', handler: handleSubject },
     { method: 'GET', pattern: '/v1/nodes/:id/messages', handler: handleMessages },
     { method: 'GET', pattern: '/v1/nodes/:id/session', handler: handleSession },
     { method: 'GET', pattern: '/v1/nodes/:id/transcript', handler: handleTranscript },

package/dist/migrations/001-surfaces-frontmatter.d.ts

@@ -0,0 +1,2 @@
+import type { ConvergentMigration } from './types.js';
+export declare const surfacesFrontmatterMigration: ConvergentMigration;

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

@@ -0,0 +1,276 @@
+// 001 — the surfaces cut's frontmatter codemod. Folds the four old routing
+// fields (`system-prompt-visibility`, `file-read-visibility`, `applies-to`,
+// `read-when`) into explicit `surfaces` entries, bakes INDEX boot ceilings into
+// each doc's boot rung (per store), and points bare-directory `[[refs]]` at
+// their `[[dir/INDEX]]` docs (a bare-dir ref used to deliver the INDEX body;
+// after the cut it returns the directory listing).
+//
+// Only docs with a valid substrate `kind` are touched. The old-schema parsing
+// and ceiling walk are FROZEN COPIES of the pre-cut substrate code: the live
+// versions are deleted with the cut, and this migration must keep reading the
+// old format for as long as it ships.
+//
+// Serialization is a textual splice: the dead keys' exact line spans are cut
+// from the raw frontmatter and a rendered `surfaces:` block is appended, so
+// every other byte survives verbatim and a migrated doc's diff shows only the
+// dead fields dying, `surfaces` appearing, and rule-5 ref rewrites — never
+// unrelated reformatting (re-serializing through the Document API would unfold
+// folded scalars). Each splice is validated by re-parsing: the result must
+// equal the original record minus the dead fields plus `surfaces`, or the
+// migration throws naming the doc.
+import { basename } from 'node:path';
+import { isMap, parse as parseYaml, parseDocument, stringify } from 'yaml';
+import { parseFrontmatterGeneric } from '../core/frontmatter.js';
+import { findDocLinks } from '../core/memory/doc-link-grammar.js';
+import { createMemoryDocSnapshot } from '../core/memory-resolver.js';
+const OLD_FIELDS = ['system-prompt-visibility', 'file-read-visibility', 'applies-to', 'read-when'];
+// ---------------------------------------------------------------------------
+// Frozen old-schema parsing (pre-cut substrate/schema.ts semantics).
+// ---------------------------------------------------------------------------
+const RUNGS = ['none', 'name', 'preview', 'content'];
+function rungRank(r) {
+    return RUNGS.indexOf(r);
+}
+/** Absent/invalid rung falls to the old parser's neutral floor `none`. */
+function parseRung(v) {
+    return typeof v === 'string' && RUNGS.includes(v) ? v : 'none';
+}
+function parseAppliesTo(v) {
+    if (typeof v === 'string')
+        return v.trim() === '' ? [] : [v];
+    if (Array.isArray(v))
+        return v.filter((g) => typeof g === 'string' && g.trim() !== '');
+    return [];
+}
+function parsePredicate(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
+}
+/** Strip the optional `NN-` ordering prefix from every segment (identity
+ *  normalization — frozen copy of normalizeDocName). */
+function normalizeName(name) {
+    return name
+        .split('/')
+        .map((s) => s.replace(/^\d{2}-/, ''))
+        .join('/');
+}
+function classify(doc) {
+    const fm = doc.frontmatter;
+    if (fm === null)
+        return null;
+    if (fm['kind'] !== 'knowledge' && fm['kind'] !== 'preference')
+        return null;
+    const fallback = normalizeName(doc.relPath.replace(/\.md$/, ''));
+    const rawName = fm['name'];
+    const name = typeof rawName === 'string' && rawName.trim() !== '' ? normalizeName(rawName.trim()) : fallback;
+    return {
+        doc,
+        name,
+        spv: parseRung(fm['system-prompt-visibility']),
+        fv: parseRung(fm['file-read-visibility']),
+        appliesTo: parseAppliesTo(fm['applies-to']),
+        readWhen: parsePredicate(fm['read-when']),
+        hasOldFields: OLD_FIELDS.some((k) => k in fm),
+    };
+}
+// ---------------------------------------------------------------------------
+// Frozen boot-ceiling walk (pre-cut substrate/ceiling.ts), per store: a
+// directory INDEX's rung caps every descendant's boot rung; the migration
+// bakes the effective (post-ceiling) rung into each doc so the rendered boot
+// tree is preserved once the ceiling machinery is deleted.
+// ---------------------------------------------------------------------------
+function buildCeiling(docs) {
+    const m = new Map();
+    for (const d of docs) {
+        if (d.name !== 'INDEX' && !d.name.endsWith('/INDEX'))
+            continue;
+        const dir = d.name === 'INDEX' ? '' : d.name.slice(0, d.name.length - '/INDEX'.length);
+        if (!m.has(dir))
+            m.set(dir, d.spv);
+    }
+    return m;
+}
+function effectiveBootRung(d, ceiling) {
+    let rung = d.spv;
+    const parts = d.name.split('/');
+    parts.pop();
+    for (let i = parts.length; i > 0; i--) {
+        const idx = ceiling.get(parts.slice(0, i).join('/'));
+        if (idx !== undefined && rungRank(idx) < rungRank(rung))
+            rung = idx;
+    }
+    return rung;
+}
+/** Old read globs also matched the path RELATIVE to the doc's store's owning
+ *  repo dir. A glob containing `/` that starts with neither `/`, `**`, nor
+ *  `./` could ONLY match through that relative target (absolute paths start
+ *  with `/`, basenames carry no `/`), so it becomes `./`-anchored — the new
+ *  schema's one relative spelling. Every other shape keeps its meaning as-is. */
+function anchorReadGlob(g) {
+    const t = g.trim();
+    if (!t.includes('/'))
+        return t;
+    if (t.startsWith('/') || t.startsWith('**') || t.startsWith('./'))
+        return t;
+    return `./${t}`;
+}
+function planEntries(d, bootRung) {
+    const entries = [];
+    if (d.spv !== 'none' && bootRung !== 'none')
+        entries.push({ on: 'boot', at: bootRung });
+    if (d.fv !== 'none') {
+        // The old `.` token meant both "deliver on workspace open" and "deliver on
+        // any read inside the owning repo" — spelled as two explicit entries.
+        if (d.appliesTo.some((g) => g.trim() === '.')) {
+            entries.push({ on: 'workspace-open', at: d.fv });
+            entries.push({ on: 'read', match: './**', at: d.fv });
+        }
+        const globs = d.appliesTo.filter((g) => g.trim() !== '.').map(anchorReadGlob);
+        if (globs.length > 0)
+            entries.push({ on: 'read', match: globs.length === 1 ? globs[0] : globs, at: d.fv });
+        // Old read matching was pathMatch OR frontmatterMatch, so a separate entry
+        // is behavior-preserving.
+        if (d.readWhen !== undefined)
+            entries.push({ on: 'read', 'match-frontmatter': d.readWhen, at: d.fv });
+    }
+    return entries;
+}
+// ---------------------------------------------------------------------------
+// Rule 5: bare-dir `[[ref]]` → `[[dir/INDEX]]`. A ref is rewritten only when
+// it resolves through the bare-dir/bare-plugin-name → INDEX.md convenience
+// (resolved file is an INDEX.md the ref does not name) AND `<ref>/INDEX`
+// provably resolves to the same file — meaning-preserving or untouched.
+// Resolution uses the fs-only memory resolver from this process's ambient
+// target, because refs cross stores (user docs point into plugin dirs).
+// ---------------------------------------------------------------------------
+let corpusMemo = null;
+const refDecisionMemo = new Map();
+function resolveOne(name) {
+    corpusMemo ??= createMemoryDocSnapshot();
+    return corpusMemo.resolve([name]).get(name);
+}
+function indexRefReplacement(name) {
+    const memo = refDecisionMemo.get(name);
+    if (memo !== undefined)
+        return memo;
+    let out = null;
+    if (name !== 'INDEX' && !name.endsWith('/INDEX')) {
+        const hit = resolveOne(name);
+        if (hit !== undefined && basename(hit.path) === 'INDEX.md') {
+            const explicit = resolveOne(`${name}/INDEX`);
+            if (explicit !== undefined && explicit.path === hit.path)
+                out = `${name}/INDEX`;
+        }
+    }
+    refDecisionMemo.set(name, out);
+    return out;
+}
+function rewriteBareDirRefs(body) {
+    const links = findDocLinks(body);
+    if (links.length === 0)
+        return body;
+    let out = '';
+    let pos = 0;
+    for (const link of links) {
+        const repl = indexRefReplacement(link.name);
+        if (repl === null)
+            continue;
+        out += body.slice(pos, link.start) + `[[${repl}]]`;
+        pos = link.end;
+    }
+    return out + body.slice(pos);
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (a !== null && b !== null && typeof a === 'object' && typeof b === 'object') {
+        const ak = Object.keys(a);
+        const bk = Object.keys(b);
+        if (ak.length !== bk.length)
+            return false;
+        return ak.every((k) => deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+function migratedYaml(rawYaml, entries, docPath) {
+    const ydoc = parseDocument(rawYaml);
+    if (ydoc.errors.length > 0 || !isMap(ydoc.contents)) {
+        throw new Error(`surfaces migration: unparseable frontmatter in ${docPath}`);
+    }
+    // Whole-line spans of the dead top-level keys (multi-line values included:
+    // the value's node-end bounds its last continuation line).
+    const spans = [];
+    for (const item of ydoc.contents.items) {
+        if (!OLD_FIELDS.includes(String(item.key)))
+            continue;
+        const keyRange = item.key.range;
+        const valueRange = item.value?.range;
+        if (keyRange === undefined)
+            throw new Error(`surfaces migration: rangeless key in ${docPath}`);
+        const start = rawYaml.lastIndexOf('\n', keyRange[0] - 1) + 1;
+        let end = valueRange?.[2] ?? keyRange[2];
+        // Consume through end-of-line unless a block value already owns its newline.
+        if (!(end > 0 && rawYaml[end - 1] === '\n')) {
+            while (end < rawYaml.length && (rawYaml[end] === ' ' || rawYaml[end] === '\t' || rawYaml[end] === '\r'))
+                end++;
+            if (rawYaml[end] === '\n')
+                end++;
+        }
+        spans.push([start, end]);
+    }
+    spans.sort((a, b) => b[0] - a[0]);
+    let out = rawYaml;
+    for (const [s, e] of spans)
+        out = out.slice(0, s) + out.slice(e);
+    if (entries.length > 0) {
+        // lineWidth 0: render each entry's scalars on one line, never folded.
+        const block = stringify({ surfaces: entries }, { lineWidth: 0 });
+        out = out === '' ? block : (out.endsWith('\n') ? out : out + '\n') + block;
+    }
+    out = out.replace(/\r?\n$/, '');
+    const expected = { ...parseYaml(rawYaml) };
+    for (const k of OLD_FIELDS)
+        delete expected[k];
+    if (entries.length > 0)
+        expected['surfaces'] = entries;
+    const actual = parseYaml(out === '' ? '{}' : out);
+    if (!deepEqual(actual ?? {}, expected)) {
+        throw new Error(`surfaces migration: spliced frontmatter does not round-trip in ${docPath}`);
+    }
+    return out;
+}
+function rebuildSource(d, newYaml, newBody) {
+    const { doc } = d;
+    const bodyStart = doc.source.length - doc.body.length;
+    const fmBlock = doc.source.slice(0, bodyStart);
+    if (newYaml === null)
+        return fmBlock + newBody;
+    const { raw } = parseFrontmatterGeneric(doc.source);
+    const at = fmBlock.indexOf(raw);
+    if (raw === '' || at < 0)
+        throw new Error(`surfaces migration: cannot locate frontmatter block in ${doc.path}`);
+    return fmBlock.slice(0, at) + newYaml + fmBlock.slice(at + raw.length) + newBody;
+}
+export const surfacesFrontmatterMigration = {
+    lane: 'convergent',
+    description: 'surfaces frontmatter: fold visibility/applies-to/read-when routing into surfaces entries; rewrite bare-directory [[refs]] to [[dir/INDEX]]',
+    apply(store) {
+        const docs = store.docs.map(classify).filter((d) => d !== null);
+        const ceiling = buildCeiling(docs);
+        const changes = [];
+        for (const d of docs) {
+            const newBody = rewriteBareDirRefs(d.doc.body);
+            if (!d.hasOldFields && newBody === d.doc.body)
+                continue;
+            const newYaml = d.hasOldFields
+                ? migratedYaml(parseFrontmatterGeneric(d.doc.source).raw, planEntries(d, effectiveBootRung(d, ceiling)), d.doc.path)
+                : null;
+            changes.push({ path: d.doc.path, after: rebuildSource(d, newYaml, newBody) });
+        }
+        return changes;
+    },
+};

package/dist/migrations/convergent.d.ts

@@ -0,0 +1,31 @@
+import type { StateMigration, StoreSnapshot } from './types.js';
+/** A doc excluded from the snapshot because its frontmatter is not valid YAML.
+ *  Per-doc throw isolation at the collection layer: the bad file is named and
+ *  the rest of the store still migrates. */
+export interface SkippedDoc {
+    relPath: string;
+    error: string;
+}
+export interface ConvergentRunResult {
+    root: string;
+    /** One row per migration that planned real changes, in registry order. */
+    applied: {
+        migration: string;
+        files: string[];
+    }[];
+    skipped: SkippedDoc[];
+}
+/** Snapshot every parseable `.md` under `root` (hidden dirs — `.history`
+ *  sidecars and the like — skipped, mirroring substrate doc enumeration). */
+export declare function loadStoreSnapshot(root: string): {
+    snapshot: StoreSnapshot;
+    skipped: SkippedDoc[];
+};
+/** Run every registered convergent migration over the store at `root`, in
+ *  registry order. No-op changes (identical text) are filtered; each real
+ *  change is written atomically unless `dryRun`. Journaled migrations in the
+ *  list are the db chain's business and are skipped here. */
+export declare function runConvergentMigrations(root: string, opts?: {
+    dryRun?: boolean;
+    migrations?: readonly StateMigration[];
+}): ConvergentRunResult;

package/dist/migrations/convergent.js

@@ -0,0 +1,71 @@
+// The convergent-lane runner: snapshot one memory store, let each registered
+// convergent migration plan full-text rewrites, write them atomically.
+// Convergence, not journaling — every run re-scans the store and rewrites
+// whatever still matches an old shape, so a doc that arrives later (sync,
+// restore, hand-edit) is caught by the next run.
+import { relative, sep } from 'node:path';
+import { atomicWriteText, readText, walkFiles } from '../core/fs-utils.js';
+import { parseFrontmatterGeneric } from '../core/frontmatter.js';
+import { STATE_MIGRATIONS } from './registry.js';
+function parseDoc(root, file) {
+    const relPath = relative(root, file).split(sep).join('/');
+    const source = readText(file);
+    try {
+        const { data, body } = parseFrontmatterGeneric(source);
+        return { doc: { path: file, relPath, source, frontmatter: data, body } };
+    }
+    catch (e) {
+        return { error: (e instanceof Error ? e.message : String(e)).split('\n')[0] };
+    }
+}
+/** Snapshot every parseable `.md` under `root` (hidden dirs — `.history`
+ *  sidecars and the like — skipped, mirroring substrate doc enumeration). */
+export function loadStoreSnapshot(root) {
+    const docs = [];
+    const skipped = [];
+    for (const file of walkFiles(root, (n) => n.endsWith('.md'), (d) => d.startsWith('.'))) {
+        const parsed = parseDoc(root, file);
+        if ('doc' in parsed)
+            docs.push(parsed.doc);
+        else
+            skipped.push({ relPath: relative(root, file).split(sep).join('/'), error: parsed.error });
+    }
+    return { snapshot: { root, docs }, skipped };
+}
+/** Fold one applied change back into the in-memory snapshot so the NEXT
+ *  migration plans against post-change state (dry runs included — that is what
+ *  makes a dry-run diff equal the real run's writes). A migration that emits
+ *  invalid YAML is a defect and throws here, before anything else compounds
+ *  on its output. */
+function refreshDoc(snapshot, change) {
+    const relPath = relative(snapshot.root, change.path).split(sep).join('/');
+    const { data, body } = parseFrontmatterGeneric(change.after);
+    const doc = { path: change.path, relPath, source: change.after, frontmatter: data, body };
+    const i = snapshot.docs.findIndex((d) => d.path === change.path);
+    if (i >= 0)
+        snapshot.docs[i] = doc;
+    else
+        snapshot.docs.push(doc);
+}
+/** Run every registered convergent migration over the store at `root`, in
+ *  registry order. No-op changes (identical text) are filtered; each real
+ *  change is written atomically unless `dryRun`. Journaled migrations in the
+ *  list are the db chain's business and are skipped here. */
+export function runConvergentMigrations(root, opts = {}) {
+    const migrations = (opts.migrations ?? STATE_MIGRATIONS).filter((m) => m.lane === 'convergent');
+    const { snapshot, skipped } = loadStoreSnapshot(root);
+    const applied = [];
+    for (const migration of migrations) {
+        const bySource = new Map(snapshot.docs.map((d) => [d.path, d.source]));
+        const changes = migration.apply(snapshot).filter((c) => bySource.get(c.path) !== c.after);
+        if (changes.length === 0)
+            continue;
+        for (const change of changes) {
+            if (opts.dryRun !== true)
+                atomicWriteText(change.path, change.after);
+            refreshDoc(snapshot, change);
+        }
+        applied.push({ migration: migration.description, files: changes.map((c) => c.path) });
+    }
+    return { root, applied, skipped };
+}

package/dist/migrations/registry.d.ts

@@ -0,0 +1,2 @@
+import type { StateMigration } from './types.js';
+export declare const STATE_MIGRATIONS: readonly StateMigration[];

package/dist/migrations/registry.js

@@ -0,0 +1,19 @@
+// The ordered state-migration registry — ONE list for both lanes, so a cut
+// that spans canvas-db and document stores ships as adjacent entries.
+//
+// Authoring contract (each migration is one file, `NNN-<desc>.ts`, appended
+// here in order):
+//   • Idempotent. A convergent migration re-runs on every `crtr sys migrate`,
+//     so applying it to an already-migrated store must plan zero changes. A
+//     journaled migration runs once per database via user_version, but its
+//     body must still tolerate a crash-resume re-run of any filesystem work.
+//   • Journaled filesystem steps are crash-resumable: fs writes happen outside
+//     the db transaction, so a step interrupted mid-fs-work must complete
+//     (never corrupt) when the chain re-runs it.
+//   • Migration files import ONLY fs/frontmatter utilities (the fs-only
+//     memory resolver included) and these types — never canvas-db or canvas
+//     accessors. `DatabaseSync` arrives as a parameter; import it type-only.
+//     This keeps the registry legal in every CLI leaf's import graph (the
+//     build's V-1 gate).
+import { surfacesFrontmatterMigration } from './001-surfaces-frontmatter.js';
+export const STATE_MIGRATIONS = [surfacesFrontmatterMigration];

package/dist/migrations/types.d.ts

@@ -0,0 +1,40 @@
+import type { DatabaseSync } from 'node:sqlite';
+export interface JournaledMigration {
+    lane: 'journaled';
+    description: string;
+    /** Runs inside the canvas-db migration transaction. Filesystem work under
+     *  `canvasHome` is OUTSIDE that transaction — it must be crash-resumable
+     *  (a re-run after a partial application completes rather than corrupts). */
+    apply(db: DatabaseSync, canvasHome: string): void;
+}
+export interface ConvergentMigration {
+    lane: 'convergent';
+    description: string;
+    /** Pure planning: return the full new text of each doc to rewrite. The
+     *  runner filters no-op changes and performs the writes. */
+    apply(store: StoreSnapshot): DocChange[];
+}
+export type StateMigration = JournaledMigration | ConvergentMigration;
+/** One parsed markdown doc in a store snapshot. */
+export interface StoreDoc {
+    /** Absolute file path. */
+    path: string;
+    /** Path relative to the store root, `/`-separated. */
+    relPath: string;
+    /** Full file text as read from disk. */
+    source: string;
+    /** Parsed frontmatter record (null when the file has no frontmatter block). */
+    frontmatter: Record<string, unknown> | null;
+    body: string;
+}
+/** Every parseable `.md` doc under one memory-store root. */
+export interface StoreSnapshot {
+    root: string;
+    docs: StoreDoc[];
+}
+/** One planned rewrite: the full new file text for `path`. */
+export interface DocChange {
+    path: string;
+    /** Complete replacement text for the file. */
+    after: string;
+}

package/dist/migrations/types.js

@@ -0,0 +1,11 @@
+// State-migration shapes. Two lanes, split by which store owns the state:
+//
+//   journaled  — canvas-db state. Runs inside the db's ordered migration chain
+//                (core/canvas/db.ts appends these to MIGRATIONS), so each step
+//                gets the chain's BEGIN IMMEDIATE/COMMIT + user_version gating
+//                and runs exactly once per database.
+//   convergent — on-disk memory documents. No journal exists over a user's
+//                stores (files appear, sync in, get hand-edited), so these
+//                CONVERGE instead: every run re-scans and rewrites whatever
+//                still matches the old shape. `crtr sys migrate` is the runner.
+export {};