@north-light/crouter 0.3.226 → 0.3.228

package/dist/core/substrate/schema.d.ts

@@ -14,19 +14,7 @@ export declare function rungAtLeast(r: Rung, min: Rung): boolean;
 /** The lower of two rungs — the clamp automatic delivery applies to an
  *  authored rung against its project relationship's cap. */
 export declare function minRung(a: Rung, b: Rung): Rung;
-/** Strip an optional `NN-` ordering prefix from ONE path segment (file or
- *  directory display name). `00-runtime-base/00-authoring` -> `runtime-base/authoring`; `spine` (no
- *  prefix) is unchanged. */
-export declare function normalizeNameSegment(segment: string): string;
-/** Normalize a full slash-separated path-derived doc name by stripping the
- *  optional numeric prefix from EVERY segment: `01-spine/00-has-manager` ->
- *  `spine/has-manager`. This is the identity a doc displays, dedups, and
- *  resolves under — distinct from its physical path, which keeps the prefix. */
-export declare function normalizeDocName(name: string): string;
-/** Resolve a doc's identity from its raw frontmatter record: an explicit
- *  `name` field wins (trimmed + normalized), else `fallbackName` (the
- *  normalized path-derived name). */
-export declare function resolveDocName(fm: Record<string, unknown> | null | undefined, fallbackName: string): string;
+export { normalizeNameSegment, normalizeDocName, resolveLocalName as resolveDocName } from '../memory/identity.js';
 export declare const SURFACE_EVENTS: readonly ["boot", "workspace-open", "read", "memory-read", "command"];
 export type SurfaceEvent = (typeof SURFACE_EVENTS)[number];
 /** The rungs an entry may deliver at. There is no `none` — silence is the

package/dist/core/substrate/schema.js

@@ -42,47 +42,12 @@ export function minRung(a, b) {
     return rungRank(a) <= rungRank(b) ? a : b;
 }
 // ---------------------------------------------------------------------------
-// Display-name normalization — the optional `NN-` ordering pin. A doc's
-// physical path may carry a two-digit numeric prefix on a file or directory
-// segment (`00-runtime-base/`, `01-spine/`) purely to pin structural order
-// against natural sort (design: builtin prompt corpus, used sparingly). The
-// prefix is NEVER part of the doc's identity: every identity-facing surface —
-// MemoryDoc.name, direct lookup, leaf fallback, `crtr memory read`/`list`,
-// prompt render, on-read display — derives from the NORMALIZED segments, so
-// `00-runtime-base/00-authoring` displays/dedups/resolves as `runtime-base/authoring`. When a doc
-// sets an explicit frontmatter `name`, that normalized name wins instead of
-// the path-derived fallback. Only the physical path keeps the prefix.
+// Identity — owned entirely by core/memory/identity.ts (ordering-prefix
+// normalization, INDEX collapse, explicit-name-then-path local identity,
+// namespace composition). Re-exported here so document parsing and identity
+// derivation stay one rule with one implementation.
 // ---------------------------------------------------------------------------
-const NUMERIC_PREFIX_RE = /^\d{2}-/;
-/** Strip an optional `NN-` ordering prefix from ONE path segment (file or
- *  directory display name). `00-runtime-base/00-authoring` -> `runtime-base/authoring`; `spine` (no
- *  prefix) is unchanged. */
-export function normalizeNameSegment(segment) {
-    return segment.replace(NUMERIC_PREFIX_RE, '');
-}
-/** Normalize a full slash-separated path-derived doc name by stripping the
- *  optional numeric prefix from EVERY segment: `01-spine/00-has-manager` ->
- *  `spine/has-manager`. This is the identity a doc displays, dedups, and
- *  resolves under — distinct from its physical path, which keeps the prefix. */
-export function normalizeDocName(name) {
-    return name.split('/').map(normalizeNameSegment).join('/');
-}
-// ---------------------------------------------------------------------------
-// Substrate identity — the ONE explicit-name-then-path-fallback rule. A doc's
-// resolver identity is its explicit frontmatter `name` when present (normalized),
-// otherwise the caller-supplied path-derived fallback. Every loader that turns a
-// physical .md file into a named doc (the resolver's `listMemoryDocsInDir` and
-// the explicit file-context loader) calls this ONE helper, so a doc's identity
-// never depends on which path loaded it.
-// ---------------------------------------------------------------------------
-/** Resolve a doc's identity from its raw frontmatter record: an explicit
- *  `name` field wins (trimmed + normalized), else `fallbackName` (the
- *  normalized path-derived name). */
-export function resolveDocName(fm, fallbackName) {
-    const raw = fm?.['name'];
-    const explicit = typeof raw === 'string' && raw.trim() !== '' ? normalizeDocName(raw.trim()) : '';
-    return explicit !== '' ? explicit : fallbackName;
-}
+export { normalizeNameSegment, normalizeDocName, resolveLocalName as resolveDocName } from '../memory/identity.js';
 // ---------------------------------------------------------------------------
 // Surfaces — explicit event routing (design: surfaces-design.md). A doc
 // declares WHEN it delivers as (event, match, rung) entries; matches are

package/dist/core/substrate/session-cache.d.ts

@@ -2,6 +2,14 @@ import type { MemoryDoc } from '../memory-resolver.js';
 import type { SubstrateDoc } from './schema.js';
 type ListAllMemoryDocsFn = () => MemoryDoc[];
 type ParseSubstrateDocFn = (doc: MemoryDoc) => SubstrateDoc | null;
+/** A parsed substrate document with the resolver descriptor it came from. The
+ *  parsed doc carries canonical identity but not the physical form behind it,
+ *  so the descriptor is what supplies the routing anchor a `./` memory-read
+ *  glob matches against. */
+export interface EventCorpusDoc {
+    doc: SubstrateDoc;
+    source: MemoryDoc;
+}
 /** Called by canvas-doc-substrate.ts on every `session_start`.
  *  Resets all cached values so the next access triggers a fresh scan.  */
 export declare function clearSessionCache(): void;
@@ -13,13 +21,15 @@ export declare function clearSessionCache(): void;
  *  that need every referenceable doc (inline memory-reference inventory) call
  *  this directly instead of `cachedAllMemoryDocs`. */
 export declare function cachedAllMemoryDocsInclusive(listFn: ListAllMemoryDocsFn): MemoryDoc[];
-/** allMemoryDocsInclusive mapped through parseSubstrateDoc + null-filtered,
- *  INCLUDING node scope. */
+/** allMemoryDocsInclusive parsed and paired with its descriptors, INCLUDING
+ *  node scope — the event corpus, and the module's only parse pass. */
+export declare function cachedEventCorpusInclusive(listFn: ListAllMemoryDocsFn, parseFn: ParseSubstrateDocFn): EventCorpusDoc[];
+/** The parsed docs of the inclusive event corpus, without their descriptors. */
 export declare function cachedSubstrateDocsInclusive(listFn: ListAllMemoryDocsFn, parseFn: ParseSubstrateDocFn): SubstrateDoc[];
 /** All memory docs (listAllMemoryDocs()), scanned once per session.
  *  `listFn` is injected by the caller to avoid circular imports at module init. */
 export declare function cachedAllMemoryDocs(listFn: ListAllMemoryDocsFn): MemoryDoc[];
-/** allMemoryDocs mapped through parseSubstrateDoc + null-filtered.
- *  Both render.ts and on-read.ts consume this. */
+/** The node-excluded parsed view — render.ts's boot corpus. Projected out of
+ *  the inclusive parse rather than parsed again. */
 export declare function cachedSubstrateDocs(listFn: ListAllMemoryDocsFn, parseFn: ParseSubstrateDocFn): SubstrateDoc[];
 export {};

package/dist/core/substrate/session-cache.js

@@ -18,27 +18,33 @@
 // Cached entries:
 //   • allMemoryDocsInclusive — the full listAllMemoryDocs() corpus, UNFILTERED
 //                        (includes node scope). This is the ONE underlying
-//                        filesystem scan+parse the whole module performs per
-//                        session; every other entry below derives from it by
+//                        filesystem scan the whole module performs per session;
+//                        every other entry below derives from it by
 //                        filtering/mapping, never by calling listFn() again.
-//   • substrateDocsInclusive — allMemoryDocsInclusive mapped through
-//                        parseSubstrateDoc and null-filtered, still including
-//                        node scope. Consumers that need every referenceable
-//                        doc (e.g. the inline memory-reference inventory) use
-//                        this pair.
+//   • eventCorpusInclusive — allMemoryDocsInclusive parsed once, each surviving
+//                        SubstrateDoc paired with the resolver descriptor it
+//                        parsed from. The ONE parse pass; both substrate views
+//                        below project out of it. on-read.ts consumes the pairs
+//                        because `./` memory-read globs anchor on the
+//                        descriptor's canonical routing anchor.
+//   • substrateDocsInclusive — the parsed docs alone, still including node
+//                        scope. Consumers that need every referenceable doc
+//                        (e.g. the inline memory-reference inventory) use this
+//                        pair with allMemoryDocsInclusive.
 //   • allMemoryDocs    — allMemoryDocsInclusive with node-scope docs excluded
 //                        (boot-only view — see the comment on
 //                        cachedAllMemoryDocs). Consumed by render.ts.
-//   • substrateDocs    — allMemoryDocs mapped through parseSubstrateDoc and
-//                        null-filtered.  Used by render.ts's resolver corpus.
-//                        The event corpus (on-read.ts) uses the INCLUSIVE
-//                        pair instead: node docs' surfaces entries fire on
-//                        read/memory-read/command like any other store's.
+//   • substrateDocs    — the same node-excluded view, parsed.  Used by
+//                        render.ts's resolver corpus. The event corpus
+//                        (on-read.ts) uses the INCLUSIVE pairs instead: node
+//                        docs' surfaces entries fire on read/memory-read/
+//                        command like any other store's.
 // Node subjects are deliberately NOT cached: lifecycle, mode, kind, and other
 // gate inputs can change while a resident broker/session remains live. Rendering
 // must always gate against the current persisted node metadata.
 const _cache = {
     allMemoryDocsInclusive: null,
+    eventCorpusInclusive: null,
     substrateDocsInclusive: null,
     allMemoryDocs: null,
     substrateDocs: null,
@@ -47,6 +53,7 @@ const _cache = {
  *  Resets all cached values so the next access triggers a fresh scan.  */
 export function clearSessionCache() {
     _cache.allMemoryDocsInclusive = null;
+    _cache.eventCorpusInclusive = null;
     _cache.substrateDocsInclusive = null;
     _cache.allMemoryDocs = null;
     _cache.substrateDocs = null;
@@ -64,13 +71,24 @@ export function cachedAllMemoryDocsInclusive(listFn) {
     }
     return _cache.allMemoryDocsInclusive;
 }
-/** allMemoryDocsInclusive mapped through parseSubstrateDoc + null-filtered,
- *  INCLUDING node scope. */
+/** allMemoryDocsInclusive parsed and paired with its descriptors, INCLUDING
+ *  node scope — the event corpus, and the module's only parse pass. */
+export function cachedEventCorpusInclusive(listFn, parseFn) {
+    if (_cache.eventCorpusInclusive === null) {
+        const out = [];
+        for (const source of cachedAllMemoryDocsInclusive(listFn)) {
+            const doc = parseFn(source);
+            if (doc !== null)
+                out.push({ doc, source });
+        }
+        _cache.eventCorpusInclusive = out;
+    }
+    return _cache.eventCorpusInclusive;
+}
+/** The parsed docs of the inclusive event corpus, without their descriptors. */
 export function cachedSubstrateDocsInclusive(listFn, parseFn) {
     if (_cache.substrateDocsInclusive === null) {
-        _cache.substrateDocsInclusive = cachedAllMemoryDocsInclusive(listFn)
-            .map(parseFn)
-            .filter((d) => d !== null);
+        _cache.substrateDocsInclusive = cachedEventCorpusInclusive(listFn, parseFn).map((e) => e.doc);
     }
     return _cache.substrateDocsInclusive;
 }
@@ -91,13 +109,13 @@ export function cachedAllMemoryDocs(listFn) {
     }
     return _cache.allMemoryDocs;
 }
-/** allMemoryDocs mapped through parseSubstrateDoc + null-filtered.
- *  Both render.ts and on-read.ts consume this. */
+/** The node-excluded parsed view — render.ts's boot corpus. Projected out of
+ *  the inclusive parse rather than parsed again. */
 export function cachedSubstrateDocs(listFn, parseFn) {
     if (_cache.substrateDocs === null) {
-        _cache.substrateDocs = cachedAllMemoryDocs(listFn)
-            .map(parseFn)
-            .filter((d) => d !== null);
+        _cache.substrateDocs = cachedEventCorpusInclusive(listFn, parseFn)
+            .filter((e) => e.doc.scope !== 'node')
+            .map((e) => e.doc);
     }
     return _cache.substrateDocs;
 }

package/dist/core/substrate/surface-match.d.ts

@@ -15,9 +15,9 @@ export declare function underOwningRoot(doc: Pick<SubstrateDoc, 'path'>, absFile
  *  for non-markdown files); an empty record never satisfies
  *  `matchFrontmatter`. */
 export declare function matchesReadEntry(entry: SurfaceEntry, doc: Pick<SubstrateDoc, 'path' | 'scope'>, subject: NodeConfigSubject, absReadFile: string, readFrontmatter: Record<string, unknown>): boolean;
-/** Does a `memory-read` entry on the doc named `carrierName` fit a resolved
- *  read of a doc known by `targetNames`? */
-export declare function matchesMemoryReadEntry(entry: SurfaceEntry, carrierName: string, subject: NodeConfigSubject | null, targetNames: string[]): boolean;
+/** Does a `memory-read` entry on a carrier anchored at `routingAnchor` fit a
+ *  resolved read of the doc known by its exact canonical `name`? */
+export declare function matchesMemoryReadEntry(entry: SurfaceEntry, routingAnchor: string, subject: NodeConfigSubject | null, name: string): boolean;
 /** Does a `command` entry fit the executed command string? */
 export declare function matchesCommandEntry(entry: SurfaceEntry, subject: NodeConfigSubject, command: string): boolean;
 /** The doc's delivery rung for a read of `absReadFile` (already realpathed). */
@@ -25,9 +25,11 @@ export declare function readDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces' | 'p
 /** 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 declare function workspaceOpenRung(doc: Pick<SubstrateDoc, 'surfaces'>, subject: NodeConfigSubject): Rung;
-/** 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 declare function memoryReadDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces' | 'name'>, subject: NodeConfigSubject | null, targetNames: string[]): Rung;
+/** The doc's delivery rung for a `crtr memory read` that resolved a doc known
+ *  by its exact canonical `name` — no mount-stripped or other alias.
+ *  `routingAnchor` comes from the doc's resolver descriptor — it is not
+ *  derivable from the canonical name, which cannot say whether the doc fronts
+ *  its own directory. */
+export declare function memoryReadDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces'>, routingAnchor: string, subject: NodeConfigSubject | null, name: string): Rung;
 /** The doc's delivery rung for an executed command string. */
 export declare function commandDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces'>, subject: NodeConfigSubject, command: string): Rung;

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

@@ -7,7 +7,7 @@
 // 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
+// container (its owning repo dir for `read`, its canonical routing anchor for
 // `memory-read`).
 import { basename, isAbsolute, matchesGlob, relative, sep } from 'node:path';
 import { CRTR_DIR_NAME } from '../../types.js';
@@ -77,31 +77,30 @@ export function matchesReadEntry(entry, doc, subject, absReadFile, readFrontmatt
     }
     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) {
+/** One memory-read glob vs the resolved doc's exact canonical name: plain
+ *  globs match that name only — no mount-stripped or other alias, per the
+ *  hard-cut canonical-only routing contract; a `./`-anchored glob matches
+ *  the name relative to the CARRIER's routing anchor — its own canonical
+ *  name when the carrier fronts a directory, its canonical parent when it is
+ *  an ordinary leaf. Names are slash-separated, so path globbing applies
+ *  segment-wise. */
+function memoryReadGlobMatches(glob, routingAnchor, name) {
     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);
-        });
+        if (routingAnchor === '')
+            return safeGlob(name, stripped);
+        if (!name.startsWith(routingAnchor + '/'))
+            return false;
+        return safeGlob(name.slice(routingAnchor.length + 1), stripped);
     }
-    return targetNames.some((name) => safeGlob(name, glob));
+    return 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, subject, targetNames) {
+/** Does a `memory-read` entry on a carrier anchored at `routingAnchor` fit a
+ *  resolved read of the doc known by its exact canonical `name`? */
+export function matchesMemoryReadEntry(entry, routingAnchor, subject, name) {
     if (entry.on !== 'memory-read' || entry.match === undefined || !surfaceEntryGatePasses(entry, subject))
         return false;
-    return entry.match.some((g) => memoryReadGlobMatches(g, carrierName, targetNames));
+    return entry.match.some((g) => memoryReadGlobMatches(g, routingAnchor, name));
 }
 /** A command glob is a STRING glob over the whole command line, not a path
  *  glob: `*` crosses every character (including `/` — command lines carry
@@ -154,13 +153,15 @@ export function workspaceOpenRung(doc, subject) {
     }
     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, subject, targetNames) {
+/** The doc's delivery rung for a `crtr memory read` that resolved a doc known
+ *  by its exact canonical `name` — no mount-stripped or other alias.
+ *  `routingAnchor` comes from the doc's resolver descriptor — it is not
+ *  derivable from the canonical name, which cannot say whether the doc fronts
+ *  its own directory. */
+export function memoryReadDeliveryRung(doc, routingAnchor, subject, name) {
     let r = 'none';
     for (const e of doc.surfaces) {
-        if (!matchesMemoryReadEntry(e, doc.name, subject, targetNames))
+        if (!matchesMemoryReadEntry(e, routingAnchor, subject, name))
             continue;
         if (rungRank(e.at) > rungRank(r))
             r = e.at;

package/dist/daemon/__tests__/helpers/source-daemon.d.ts

@@ -0,0 +1,30 @@
+import { type ChildProcess } from 'node:child_process';
+export interface SourceDaemonFixture {
+    root: string;
+    home: string;
+    cwd: string;
+    canvasHome: string;
+    pidfile: string;
+    socket: string;
+    tcpPort: number;
+    dispose(): void;
+}
+export interface SourceDaemonProcess {
+    child: ChildProcess;
+    exited: Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+    stdout(): string;
+    stderr(): string;
+    stop(): Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+}
+export declare function createSourceDaemonFixture(): Promise<SourceDaemonFixture>;
+export declare function startSourceDaemon(fixture: SourceDaemonFixture): SourceDaemonProcess;
+export declare function healthRequest(port: number, timeoutMs?: number): Promise<boolean>;
+export declare function waitForHealth(process: SourceDaemonProcess, port: number, timeoutMs?: number): Promise<void>;
+export declare function healthWasReadyBeforeExit(process: SourceDaemonProcess, port: number): Promise<boolean>;
+export declare function brokerPidsForCanvas(canvasHome: string): number[];

package/dist/daemon/__tests__/helpers/source-daemon.js

@@ -0,0 +1,174 @@
+import { spawn, execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { request } from 'node:http';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function reserveTcpPort() {
+    const server = createServer();
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    if (address === null || typeof address === 'string')
+        throw new Error('test TCP listener did not receive a port');
+    await new Promise((resolve, reject) => server.close((error) => error === undefined ? resolve() : reject(error)));
+    return address.port;
+}
+export async function createSourceDaemonFixture() {
+    const root = mkdtempSync('/tmp/crtr-migration-daemon-');
+    const home = join(root, 'home');
+    const cwd = join(home, 'work');
+    const canvasHome = join(root, 'canvas');
+    const pidfile = join(canvasHome, 'ready.pid');
+    const socket = join(canvasHome, 'crtrd.sock');
+    mkdirSync(cwd, { recursive: true });
+    mkdirSync(canvasHome, { recursive: true });
+    const tcpPort = await reserveTcpPort();
+    return {
+        root,
+        home,
+        cwd,
+        canvasHome,
+        pidfile,
+        socket,
+        tcpPort,
+        dispose: () => rmSync(root, { recursive: true, force: true }),
+    };
+}
+export function startSourceDaemon(fixture) {
+    const require = createRequire(import.meta.url);
+    const tsxLoader = pathToFileURL(require.resolve('tsx/esm')).href;
+    const entry = fileURLToPath(new URL('../../crtrd-cli.ts', import.meta.url));
+    const env = {
+        ...process.env,
+        HOME: fixture.home,
+        CRTR_HOME: fixture.canvasHome,
+        CRTR_PIDFILE: fixture.pidfile,
+        CRTRD_TCP: `127.0.0.1:${fixture.tcpPort}`,
+        XDG_CACHE_HOME: join(fixture.root, 'cache'),
+        XDG_CONFIG_HOME: join(fixture.root, 'config'),
+        XDG_DATA_HOME: join(fixture.root, 'data'),
+    };
+    for (const key of [
+        'CRTR_NODE_ID',
+        'CRTR_KIND',
+        'CRTR_MODE',
+        'CRTR_LIFECYCLE',
+        'CRTR_NODE_CWD',
+        'CRTR_CONTEXT_DIR',
+        'CRTR_CYCLES',
+        'CRTR_PROFILE_ID',
+        'CRTR_PARENT_NODE_ID',
+        'CRTR_FRONT_DOOR',
+        'CRTR_BROKER_ENGINE',
+        'CRTR_PI_BINARY',
+        'NODE_OPTIONS',
+    ])
+        delete env[key];
+    const child = spawn(process.execPath, [
+        '--conditions=crtr-src',
+        '--import', tsxLoader,
+        entry,
+        '--canvas-home', fixture.canvasHome,
+    ], {
+        cwd: fixture.cwd,
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    const exited = new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('close', (code, signal) => resolve({ code, signal }));
+    });
+    return {
+        child,
+        exited,
+        stdout: () => stdout,
+        stderr: () => stderr,
+        stop: async () => {
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill('SIGTERM');
+            const timeout = setTimeout(() => {
+                if (child.exitCode === null && child.signalCode === null)
+                    child.kill('SIGKILL');
+            }, 10_000);
+            try {
+                return await exited;
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        },
+    };
+}
+export function healthRequest(port, timeoutMs = 200) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (ready) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(ready);
+        };
+        const req = request({ host: '127.0.0.1', port, path: '/healthz', method: 'GET', agent: false }, (response) => {
+            response.resume();
+            response.once('end', () => finish(response.statusCode === 200));
+        });
+        req.once('error', () => finish(false));
+        req.setTimeout(timeoutMs, () => {
+            req.destroy();
+            finish(false);
+        });
+        req.end();
+    });
+}
+export async function waitForHealth(process, port, timeoutMs = 20_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (await healthRequest(port))
+            return;
+        if (process.child.exitCode !== null || process.child.signalCode !== null) {
+            const result = await process.exited;
+            throw new Error(`source daemon exited before health readiness (${JSON.stringify(result)}):\n${process.stderr()}`);
+        }
+        await delay(10);
+    }
+    throw new Error(`source daemon did not answer /healthz within ${timeoutMs}ms:\n${process.stderr()}`);
+}
+export async function healthWasReadyBeforeExit(process, port) {
+    let exited = false;
+    void process.exited.then(() => { exited = true; });
+    while (!exited) {
+        if (await healthRequest(port, 50))
+            return true;
+        await delay(2);
+    }
+    return false;
+}
+export function brokerPidsForCanvas(canvasHome) {
+    let table;
+    try {
+        table = execFileSync('ps', ['-ax', '-o', 'pid=,command='], { encoding: 'utf8', timeout: 2_000 });
+    }
+    catch {
+        return [];
+    }
+    const declaration = `--canvas-home ${canvasHome}`;
+    return table.split('\n').flatMap((line) => {
+        if (!line.includes('broker-cli') || !line.includes(declaration))
+            return [];
+        const pid = Number.parseInt(line.trim().split(/\s+/, 1)[0] ?? '', 10);
+        return Number.isInteger(pid) ? [pid] : [];
+    });
+}

package/dist/daemon/__tests__/integration/migration-startup.test.d.ts

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

package/dist/daemon/__tests__/integration/migration-startup.test.js

@@ -0,0 +1,97 @@
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, watch, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import test from 'node:test';
+import { onDiskMigrationIdentity } from '../../../migrations/registry.js';
+import { brokerPidsForCanvas, createSourceDaemonFixture, healthWasReadyBeforeExit, startSourceDaemon, waitForHealth, } from '../helpers/source-daemon.js';
+const PRE_MIGRATION_DOC = `---
+kind: knowledge
+name: daemon-ordering
+system-prompt-visibility: preview
+file-read-visibility: content
+applies-to:
+  - "**/*.ts"
+read-when:
+  language: typescript
+---
+# Daemon ordering
+
+This document begins in the pre-surfaces schema.
+`;
+function writeUserMemory(home, name, source) {
+    const path = join(home, '.crouter', 'memory', name);
+    mkdirSync(join(home, '.crouter', 'memory'), { recursive: true });
+    writeFileSync(path, source, 'utf8');
+    return path;
+}
+test('source daemon migrates the pre-migration corpus and writes its marker before API readiness', { timeout: 30_000 }, async () => {
+    const fixture = await createSourceDaemonFixture();
+    const docPath = writeUserMemory(fixture.home, 'daemon-ordering.md', PRE_MIGRATION_DOC);
+    const markerPath = join(fixture.canvasHome, 'on-disk-migrations.json');
+    const dbPath = join(fixture.canvasHome, 'canvas.db');
+    assert.equal(existsSync(markerPath), false, 'fixture starts without a migration marker');
+    assert.equal(existsSync(dbPath), false, 'fixture starts without canvas.db');
+    assert.match(readFileSync(docPath, 'utf8'), /system-prompt-visibility:/, 'fixture is genuinely pre-migration');
+    const daemon = startSourceDaemon(fixture);
+    try {
+        const markerDeadline = Date.now() + 20_000;
+        while (!existsSync(markerPath) && Date.now() < markerDeadline) {
+            await new Promise((resolve) => setTimeout(resolve, 1));
+        }
+        assert.equal(existsSync(markerPath), true, `marker was not written; stderr:\n${daemon.stderr()}`);
+        const migratedAtMarker = readFileSync(docPath, 'utf8');
+        assert.doesNotMatch(migratedAtMarker, /system-prompt-visibility:|file-read-visibility:|applies-to:|read-when:/);
+        assert.equal(existsSync(fixture.pidfile), false, 'pidfile readiness is not published when the marker first appears');
+        assert.equal(existsSync(fixture.socket), false, 'API readiness is not published when the marker first appears');
+        await waitForHealth(daemon, fixture.tcpPort);
+        const migrated = readFileSync(docPath, 'utf8');
+        assert.doesNotMatch(migrated, /system-prompt-visibility:|file-read-visibility:|applies-to:|read-when:/);
+        assert.match(migrated, /surfaces:/);
+        assert.match(migrated, /on: boot/);
+        assert.match(migrated, /on: read/);
+        assert.deepEqual(JSON.parse(readFileSync(markerPath, 'utf8')), onDiskMigrationIdentity());
+        assert.equal(existsSync(fixture.pidfile), true, 'health readiness follows the pidfile readiness mirror');
+        assert.equal(existsSync(fixture.socket), true, 'the unique unix API listener is bound at readiness');
+        assert.equal(existsSync(dbPath), true, 'daemon ownership opens canvas.db only after migration');
+        assert.ok(statSync(markerPath).mtimeMs <= statSync(fixture.pidfile).mtimeMs, 'the completion marker is written no later than the readiness pidfile');
+        assert.ok(statSync(markerPath).mtimeMs <= statSync(fixture.socket).mtimeMs, 'the completion marker is written no later than the API listener');
+    }
+    finally {
+        const exit = await daemon.stop();
+        fixture.dispose();
+        assert.deepEqual(exit, { code: 0, signal: null }, `daemon must stop cleanly; stderr:\n${daemon.stderr()}`);
+    }
+});
+test('a real migration blocker exits before database, pidfile, listeners, or broker effects', { timeout: 30_000 }, async () => {
+    const fixture = await createSourceDaemonFixture();
+    const blockerPath = writeUserMemory(fixture.home, 'blocked.md', `---\nkind: knowledge\nbroken: [\n---\n# Blocked\n`);
+    const effectNames = new Set();
+    const effects = watch(fixture.canvasHome, (_event, filename) => {
+        if (filename !== null)
+            effectNames.add(filename.toString());
+    });
+    const daemon = startSourceDaemon(fixture);
+    const readiness = healthWasReadyBeforeExit(daemon, fixture.tcpPort);
+    const exit = await daemon.exited;
+    const wasReady = await readiness;
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    effects.close();
+    try {
+        assert.equal(exit.signal, null);
+        assert.notEqual(exit.code, 0, `blocker must exit nonzero; stderr:\n${daemon.stderr()}`);
+        assert.match(daemon.stderr(), new RegExp(blockerPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+        assert.match(daemon.stderr(), /Repair: crtr sys migrate/);
+        assert.equal(wasReady, false, 'the unique TCP endpoint never answered health');
+        const databaseFiles = readdirSync(fixture.canvasHome).filter((name) => name.startsWith('canvas.db'));
+        assert.deepEqual(databaseFiles, [], 'canvas.db and its journals were never created');
+        assert.equal(existsSync(fixture.pidfile), false, 'readiness pidfile was never created');
+        assert.equal(existsSync(fixture.socket), false, 'unix API listener was never created');
+        assert.equal(existsSync(join(fixture.canvasHome, 'on-disk-migrations.json')), false, 'blocker never gets a completion marker');
+        assert.equal(existsSync(join(fixture.canvasHome, 'nodes')), false, 'no node/broker state was created');
+        assert.deepEqual(brokerPidsForCanvas(fixture.canvasHome), [], 'no broker process declares the isolated canvas');
+        assert.deepEqual([...effectNames].filter((name) => name.startsWith('canvas.db') || name === 'ready.pid' || name === 'crtrd.sock' || name === 'nodes'), [], `filesystem watcher saw no transient daemon effects (all events: ${[...effectNames].join(', ')})`);
+    }
+    finally {
+        fixture.dispose();
+    }
+});