@north-light/crouter 0.3.226 → 0.3.228

package/dist/daemon/api/__tests__/bridge-heartbeat.test.js

@@ -6,25 +6,53 @@ class FakeSocket extends EventEmitter {
     pings = 0;
     terminated = 0;
     ping() { this.pings += 1; }
-    terminate() { this.terminated += 1; }
+    terminate() {
+        this.terminated += 1;
+        this.emit('terminated');
+    }
 }
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-test('remote attach heartbeat pings an idle viewer and keeps a ponging observer alive', async () => {
+function waitForTermination(ws, timeoutMs = 1_000) {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => reject(new Error('heartbeat did not terminate the peer')), timeoutMs);
+        timeout.unref();
+        ws.once('terminated', () => {
+            clearTimeout(timeout);
+            resolve();
+        });
+    });
+}
+test('a quiet attach puts nothing on the wire', async () => {
+    // Regression: an unconditional 25s ping made a hosted guest's connection never
+    // idle, so the sandbox never suspended and whole fleets billed for 15h awake.
+    const ws = new FakeSocket();
+    // The first timer tick is deliberately after the quiet window, so this test
+    // observes the contract without depending on scheduler timing.
+    const heartbeat = startRemoteAttachHeartbeat(ws, 20, 15);
+    await sleep(40);
+    assert.equal(ws.pings, 0, 'a quiet attach sends no heartbeat after its quiet window');
+    assert.equal(ws.terminated, 0, 'a quiet attach is left open, never terminated by the heartbeat');
+    heartbeat.stop();
+});
+test('relayed traffic arms the heartbeat and a pong keeps a relaying observer alive', async () => {
     const ws = new FakeSocket();
-    const stop = startRemoteAttachHeartbeat(ws, 20);
+    const heartbeat = startRemoteAttachHeartbeat(ws, 20, 10_000);
+    heartbeat.noteActivity();
     await sleep(25);
-    assert.equal(ws.pings, 1, 'an idle attach receives a WebSocket ping before proxy idle timeout');
+    assert.equal(ws.pings, 1, 'a relaying attach is pinged across a gap between frames');
     ws.emit('pong');
     await sleep(10);
     assert.equal(ws.terminated, 0, 'a pong renews the heartbeat without terminating the observer');
-    stop();
+    heartbeat.stop();
 });
-test('remote attach heartbeat drops only an unresponsive observer socket', async () => {
+test('an unresponsive peer is dropped only while the relay is active', async () => {
     const ws = new FakeSocket();
-    const stop = startRemoteAttachHeartbeat(ws, 5);
-    await sleep(16);
+    const heartbeat = startRemoteAttachHeartbeat(ws, 5, 10_000);
+    const terminated = waitForTermination(ws);
+    heartbeat.noteActivity();
+    await terminated;
     assert.equal(ws.terminated, 1, 'two missed heartbeat intervals terminate the detached viewer');
-    stop();
+    heartbeat.stop();
 });

package/dist/daemon/api/bridge.d.ts

@@ -1,11 +1,42 @@
 import type { IncomingMessage } from 'node:http';
 import type { Duplex } from 'node:stream';
 import { type WebSocket } from 'ws';
-/** Keep an otherwise quiet observer connection alive through common 60s proxy
- * idle limits. A viewer only observes a broker, so a missed heartbeat may close
- * this socket but must never affect the broker or its in-flight work. */
+/** Keep a RELAYING connection alive across a gap between frames, through common
+ * 60s proxy idle limits. A viewer only observes a broker, so a missed heartbeat
+ * may close this socket but must never affect the broker or its in-flight work. */
 export declare const REMOTE_ATTACH_HEARTBEAT_MS = 25000;
-export declare function startRemoteAttachHeartbeat(ws: WebSocket, intervalMs?: number): () => void;
+/** How long after the last relayed frame the heartbeat keeps pinging. Past this,
+ * the attach is carrying nothing — no viewer output, no streaming node — and the
+ * heartbeat goes silent so the network path underneath can reap the connection.
+ *
+ * This matters far beyond a socket: on a hosted guest (Blaxel) a connection that
+ * is pinged every 25s is never idle, so the host never suspends the sandbox. An
+ * unconditional heartbeat held whole fleets awake for 15h at a time. A drop on a
+ * quiet attach is a normal close the remote peer re-attaches from, and real work
+ * is anchored by its own keep-alive, not by this ping.
+ *
+ * The clock starts when the attach OPENS, not at its first relayed frame: a
+ * never-relaying attach still gets pings until this window elapses. The welcome
+ * frame lands in milliseconds, so this only pads the tail of the very first
+ * window.
+ *
+ * ROLLOUT ORDER — this half is only half the answer, and shipping it FIRST is
+ * strictly worse than shipping nothing. The host that owns the attach must also
+ * let go of a quiet one; Northlight Core does that at its own 60s quiesce
+ * (`CROUTER_FOLLOW_QUIESCE_MS`). Against a host that holds the attach forever,
+ * going quiet here only moves the drop to the network path, the host reports a
+ * detach, its client reconnects, and the box wakes again — the same pin, now
+ * with a full re-snapshot every couple of minutes. Ship the host's quiesce
+ * first, then roll the guest image. */
+export declare const REMOTE_ATTACH_QUIET_MS = 60000;
+export interface RemoteAttachHeartbeat {
+    /** Stop the heartbeat permanently (teardown). Idempotent. */
+    stop: () => void;
+    /** Record a relayed frame in either direction — this is what keeps the
+     *  heartbeat armed, and what re-arms it after a quiet stretch. */
+    noteActivity: () => void;
+}
+export declare function startRemoteAttachHeartbeat(ws: WebSocket, intervalMs?: number, quietMs?: number): RemoteAttachHeartbeat;
 /** Handle the HTTP upgrade for `GET /v1/nodes/{id}/attach`. A-9 matches the
  *  route, extracts `{id}`, and calls this with the raw upgrade triplet; this
  *  owns the WS handshake (its own noServer `wss` above) AND the spec §5.3

package/dist/daemon/api/bridge.js

@@ -33,13 +33,38 @@ import { probeViewSocket, waitForBrokerViewSocket } from '../../core/runtime/vie
  *  client cap) so a remote peer cannot buffer 256MiB before the broker's 24MiB
  *  decoder rejects the message. */
 const wss = new WebSocketServer({ noServer: true, maxPayload: BROKER_READ_CAPS.maxLineBytes });
-/** Keep an otherwise quiet observer connection alive through common 60s proxy
- * idle limits. A viewer only observes a broker, so a missed heartbeat may close
- * this socket but must never affect the broker or its in-flight work. */
+/** Keep a RELAYING connection alive across a gap between frames, through common
+ * 60s proxy idle limits. A viewer only observes a broker, so a missed heartbeat
+ * may close this socket but must never affect the broker or its in-flight work. */
 export const REMOTE_ATTACH_HEARTBEAT_MS = 25_000;
-export function startRemoteAttachHeartbeat(ws, intervalMs = REMOTE_ATTACH_HEARTBEAT_MS) {
+/** How long after the last relayed frame the heartbeat keeps pinging. Past this,
+ * the attach is carrying nothing — no viewer output, no streaming node — and the
+ * heartbeat goes silent so the network path underneath can reap the connection.
+ *
+ * This matters far beyond a socket: on a hosted guest (Blaxel) a connection that
+ * is pinged every 25s is never idle, so the host never suspends the sandbox. An
+ * unconditional heartbeat held whole fleets awake for 15h at a time. A drop on a
+ * quiet attach is a normal close the remote peer re-attaches from, and real work
+ * is anchored by its own keep-alive, not by this ping.
+ *
+ * The clock starts when the attach OPENS, not at its first relayed frame: a
+ * never-relaying attach still gets pings until this window elapses. The welcome
+ * frame lands in milliseconds, so this only pads the tail of the very first
+ * window.
+ *
+ * ROLLOUT ORDER — this half is only half the answer, and shipping it FIRST is
+ * strictly worse than shipping nothing. The host that owns the attach must also
+ * let go of a quiet one; Northlight Core does that at its own 60s quiesce
+ * (`CROUTER_FOLLOW_QUIESCE_MS`). Against a host that holds the attach forever,
+ * going quiet here only moves the drop to the network path, the host reports a
+ * detach, its client reconnects, and the box wakes again — the same pin, now
+ * with a full re-snapshot every couple of minutes. Ship the host's quiesce
+ * first, then roll the guest image. */
+export const REMOTE_ATTACH_QUIET_MS = 60_000;
+export function startRemoteAttachHeartbeat(ws, intervalMs = REMOTE_ATTACH_HEARTBEAT_MS, quietMs = REMOTE_ATTACH_QUIET_MS) {
     let alive = true;
     let stopped = false;
+    let lastActivityAt = Date.now();
     const acknowledge = () => { alive = true; };
     const stop = () => {
         if (stopped)
@@ -50,6 +75,13 @@ export function startRemoteAttachHeartbeat(ws, intervalMs = REMOTE_ATTACH_HEARTB
     };
     ws.on('pong', acknowledge);
     const timer = setInterval(() => {
+        if (Date.now() - lastActivityAt > quietMs) {
+            // Nothing is flowing: send no ping and run no liveness check, so an idle
+            // attach puts zero packets on the wire. A dead peer here is closed by the
+            // network path or by teardown, not by us.
+            alive = true;
+            return;
+        }
         if (!alive) {
             stop();
             ws.terminate();
@@ -65,7 +97,15 @@ export function startRemoteAttachHeartbeat(ws, intervalMs = REMOTE_ATTACH_HEARTB
         }
     }, intervalMs);
     timer.unref();
-    return stop;
+    return {
+        stop,
+        // Frames are not liveness evidence: only a pong proves the peer is there.
+        // Marking a relayed frame alive would disable dead-peer detection for
+        // exactly as long as a turn streams — the one stretch it is for.
+        noteActivity: () => {
+            lastActivityAt = Date.now();
+        },
+    };
 }
 /** A WS close reason is capped at 123 UTF-8 bytes by the protocol. */
 function clampReason(reason) {
@@ -140,7 +180,7 @@ function bridgeConnection(ws, nodeId) {
     const decoder = new FrameDecoder(CLIENT_READ_CAPS);
     let closed = false;
     let viewerFaultRecorded = false;
-    let stopHeartbeat;
+    let heartbeat;
     socket.on('connect', () => {
         clearFault(nodeId, { link: 'relay↔broker' });
     });
@@ -148,7 +188,7 @@ function bridgeConnection(ws, nodeId) {
         if (closed)
             return;
         closed = true;
-        stopHeartbeat?.();
+        heartbeat?.stop();
         if (!socket.destroyed) {
             try {
                 socket.destroy();
@@ -164,9 +204,10 @@ function bridgeConnection(ws, nodeId) {
             /* ignore */
         }
     };
-    stopHeartbeat = startRemoteAttachHeartbeat(ws);
+    heartbeat = startRemoteAttachHeartbeat(ws);
     // socket → WS: bounded decode, one WS text message per complete frame.
     socket.on('data', (chunk) => {
+        heartbeat?.noteActivity();
         let frames;
         try {
             frames = decoder.push(chunk);
@@ -245,6 +286,7 @@ function bridgeConnection(ws, nodeId) {
     ws.on('message', (data) => {
         if (closed || socket.destroyed)
             return;
+        heartbeat?.noteActivity();
         const buf = Array.isArray(data)
             ? Buffer.concat(data)
             : Buffer.isBuffer(data)

package/dist/daemon/api/handlers/broker-ops.js

@@ -1,8 +1,7 @@
 // Broker-originated canvas operations. The broker sends Pi lifecycle facts;
 // crtrd validates and commits their durable effects while the handler stays
 // strictly canvas-write-only — no broker launch, kill, or view.sock round trip.
-import { getNode, isWarmSpare, listNodes, recordPid, setPresence, subscriptionsOf, updateNode } from '../../../core/canvas/canvas.js';
-import { isSafeNodeId } from '../../../core/canvas/paths.js';
+import { canonicalSessionFile, findNodeBySessionFile, getNode, isWarmSpare, listNodes, recordPid, setPresence, subscriptionsOf, updateNode } from '../../../core/canvas/canvas.js';
 import { editorLabel } from '../../../core/canvas/labels.js';
 import { assembleNodeSubject } from '../../../core/substrate/subject.js';
 import { withCanvasWrite } from '../../../core/canvas/db.js';
@@ -128,9 +127,9 @@ function extensionState(nodeId) {
         .filter((child) => child !== null && child.kind !== 'human')
         .sort((a, b) => (a.status === b.status ? 0 : a.status === 'active' ? -1 : b.status === 'active' ? 1 : 0))
         .map(extensionNode);
-    const source = node.fork_from === undefined || node.fork_from === null || node.fork_from === '' || !isSafeNodeId(node.fork_from)
-        ? null
-        : getNode(node.fork_from);
+    const source = typeof node.fork_source_file === 'string'
+        ? findNodeBySessionFile(node.fork_source_file)
+        : null;
     const subject = assembleNodeSubject(nodeId);
     if (subject === null)
         throw notFound(`unknown node: ${nodeId}`, { received: nodeId });
@@ -146,7 +145,7 @@ function extensionState(nodeId) {
     };
 }
 function samePersona(a, b) {
-    return a?.mode === b.mode && a?.lifecycle === b.lifecycle;
+    return a?.kind === b.kind && a?.mode === b.mode && a?.lifecycle === b.lifecycle;
 }
 function parseGeneratedNameBody(body) {
     const value = objectBody(body, 'broker generated-name');
@@ -169,6 +168,7 @@ function parsePersonaAckBody(body) {
     const parse = (key) => {
         const persona = value[key];
         if (typeof persona !== 'object' || persona === null || Array.isArray(persona)
+            || typeof persona['kind'] !== 'string'
             || (persona['mode'] !== 'base' && persona['mode'] !== 'orchestrator')
             || (persona['lifecycle'] !== 'terminal' && persona['lifecycle'] !== 'resident')) {
             throw usage(`${key} must be a persona state`);
@@ -180,6 +180,7 @@ function parsePersonaAckBody(body) {
 function handleSessionBound(ctx) {
     const nodeId = ctx.params['id'];
     const request = parseSessionBoundBody(ctx.body);
+    const sessionFile = request.sessionFile === null ? null : canonicalSessionFile(request.sessionFile);
     const result = withCanvasWrite(() => {
         const before = requireNode(nodeId);
         // The broker reports the markers present in Pi's current branch; crtrd owns
@@ -196,10 +197,10 @@ function handleSessionBound(ctx) {
                 action = 'relaunch_root';
             }
             else {
-                handleNewSession(nodeId, request.piSessionId, request.sessionFile);
+                handleNewSession(nodeId, request.piSessionId, sessionFile);
             }
         }
-        else if (before.fork_from != null && before.pi_session_id == null && request.sessionFile === null) {
+        else if (before.fork_from != null && before.pi_session_id == null && sessionFile === null) {
             // Pi has not exposed complete writable coordinates for this ordinary fork.
             // Leave it unbound so recovery cannot fork provenance twice.
             action = 'shutdown';
@@ -210,7 +211,7 @@ function handleSessionBound(ctx) {
             clearYieldMessage(nodeId);
             updateNode(nodeId, {
                 pi_session_id: request.piSessionId,
-                pi_session_file: request.sessionFile,
+                pi_session_file: sessionFile,
                 cycle_pending: false,
             });
             recordPid(nodeId, request.pid);
@@ -378,20 +379,24 @@ function handleGeneratedName(ctx) {
     });
     return { status: 200, body: result };
 }
-/** Ack after Pi accepted transition guidance. The expected transition prevents a
- * stale broker from acknowledging a later persona change it did not describe. */
+/** Ack after the matching baseline or transition context is durable. The
+ * expected pair prevents a stale broker from acknowledging a later change. */
 function handlePersonaAck(ctx) {
     const nodeId = ctx.params['id'];
     const request = parsePersonaAckBody(ctx.body);
-    withCanvasWrite(() => {
+    const result = withCanvasWrite(() => {
         const node = requireNode(nodeId);
-        const current = { mode: node.mode, lifecycle: node.lifecycle };
-        const acknowledged = node.persona_ack ?? current;
+        const current = { kind: node.kind, mode: node.mode, lifecycle: node.lifecycle };
+        // A pre-kind ack reads its kind as the node's current one, matching how the
+        // broker resolved the `from` it is acknowledging.
+        const ack = node.persona_ack;
+        const acknowledged = ack === undefined ? current : { kind: ack.kind ?? node.kind, mode: ack.mode, lifecycle: ack.lifecycle };
         if (!samePersona(current, request.to) || !samePersona(acknowledged, request.from))
-            return;
+            return { applied: false };
         updateNode(nodeId, { persona_ack: request.to });
+        return { applied: true };
     });
-    return { status: 204 };
+    return { status: 200, body: result };
 }
 export const brokerOperationRoutes = [
     { method: 'POST', pattern: '/v1/nodes/:id/broker/session-bound', handler: handleSessionBound },

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

@@ -39,6 +39,8 @@ function handleResolve(ctx) {
         name: doc.name,
         scope: doc.scope,
         path: doc.path,
+        store_root: doc.store.storeRoot,
+        physical_relative_path: doc.physicalRelativePath,
         ...(doc.plugin === undefined ? {} : { plugin: doc.plugin }),
     };
     return { status: 200, body };

package/dist/daemon/crtrd.js

@@ -75,6 +75,7 @@ import { migrateLegacyInboxIdentities } from '../core/feed/inbox-migrate.js';
 import { emitEvent } from '../core/events/emit.js';
 import { operationIdContext } from '../core/events/operation-id.js';
 import { bindDaemonEventSource } from '../core/events/source.js';
+import { ensureOnDiskMigrations } from '../migrations/activation.js';
 // A broker DECLARES its owning canvas in argv at spawn (host.ts launch:
 // `broker-cli.js --canvas-home <home> --epoch <id> <nodeId>`), so ownership is
 // an exact match on this daemon's own canvas home — no path inference. An
@@ -350,6 +351,7 @@ export async function superviseTick(now = Date.now(), lifecycle = directTickLife
  *  quiesces admitted work, removes its readiness mirror, and releases its exact
  *  claim. */
 export async function runDaemon(opts = {}) {
+    await ensureOnDiskMigrations();
     const ownership = claimDaemonOwnership(randomBytes(16).toString('hex'));
     if (!ownership.claimed) {
         // A losing claim isn't always a singleton race: `own_identity_indeterminate`

package/dist/daemon/human/finish.js

@@ -282,7 +282,14 @@ export async function deliverTerminalResult(ticketId) {
         }
         if (failedTo.length > 0)
             throw new Error(`cancellation notice failed for ${failedTo.join(', ')}`);
-        transition(bridgeNodeId, 'finish');
+        // Parking the bridge done is the cancellation's END STATE, not a step it
+        // owes: a bridge already done — parked by an earlier cancel replay, or by a
+        // close that finished it while the page was still pending — is already
+        // there, and `finish` is illegal from done. Re-running it would turn a
+        // recorded, delivered cancellation into delivery_failed and make every
+        // retry repeat that error.
+        if (node.status !== 'done')
+            transition(bridgeNodeId, 'finish');
         return true;
     }
     if (result.kind === 'page') {

package/dist/daemon/manage.d.ts

@@ -47,7 +47,6 @@ export interface SpawnDaemonResult {
     /** PID of the already-running daemon, if it was already up. */
     existing_pid?: number;
 }
-export declare const DAEMON_VERIFY_WINDOW_MS = 20000;
 export interface DaemonWaitDeps {
     readPidfile?: () => number | null;
     isPidAlive?: (pid: number) => boolean;

package/dist/daemon/manage.js

@@ -14,6 +14,7 @@ import { hostExecPath } from '../core/runtime/branded-host.js';
 // Pulled from the lean db-free pidfile module (NOT crtrd.js, whose module graph
 // reaches openDb) so the CLI daemon front door stays canvas.db-free (plan B-0).
 import { isDaemonRunning, readPidfile, isPidAlive } from './pidfile.js';
+import { DAEMON_STARTUP_WINDOW_MS } from './startup-policy.js';
 // ---------------------------------------------------------------------------
 // Daemon env sanitization
 // ---------------------------------------------------------------------------
@@ -204,18 +205,8 @@ export async function execDaemon() {
     const launchArgs = await resolveDaemonLaunch();
     return execve(executable, [executable, ...launchArgs, '--canvas-home', crtrHome()], sanitizedDaemonEnv());
 }
-// Daemon lifecycle transitions are bounded so callers never claim a state
-// change before the pidfile and process liveness agree.
-//
-// A cold boot right after `install-runtime` (empty module cache, fresh
-// generation, possible pending db migration) can take several seconds to reach
-// writePidfile(), so the window is wide enough to tolerate that slow-but-valid
-// cold start rather than report a false "did not become ready"; a process exit
-// (signal/non-zero code) still fails immediately regardless of this window.
-// Exported so `commands/api-client.ts` can align the CLI-side `CrtrClient`'s
-// cold-start `/healthz` poll window with this authoritative valid-startup bound
-// instead of the two windows drifting independently.
-export const DAEMON_VERIFY_WINDOW_MS = 20_000;
+// Shutdown stays short even though startup may include corpus migration.
+const DAEMON_SHUTDOWN_WINDOW_MS = 20_000;
 const DAEMON_VERIFY_POLL_MS = 10;
 function sleepMs(ms) {
     return new Promise((resolve) => {
@@ -235,7 +226,7 @@ function sleepMs(ms) {
  *
  *  Returns null when the spawned pid owns the pidfile; returns a different live
  *  daemon pid when startup lost the race to an already-running daemon. */
-export async function verifyDaemonStartup(pid, timeoutMs = DAEMON_VERIFY_WINDOW_MS, deps = {}) {
+export async function verifyDaemonStartup(pid, timeoutMs = DAEMON_STARTUP_WINDOW_MS, deps = {}) {
     const read = deps.readPidfile ?? readPidfile;
     const alive = deps.isPidAlive ?? isPidAlive;
     const exited = deps.childExited;
@@ -265,7 +256,7 @@ export async function verifyDaemonStartup(pid, timeoutMs = DAEMON_VERIFY_WINDOW_
 /** Wait until a signaled daemon has exited and relinquished its pidfile. This
  *  makes a following start safe to claim the singleton rather than racing its
  *  previous owner. */
-export async function waitForDaemonExit(pid, timeoutMs = DAEMON_VERIFY_WINDOW_MS, deps = {}) {
+export async function waitForDaemonExit(pid, timeoutMs = DAEMON_SHUTDOWN_WINDOW_MS, deps = {}) {
     const read = deps.readPidfile ?? readPidfile;
     const alive = deps.isPidAlive ?? isPidAlive;
     const sleep = deps.sleepMs ?? sleepMs;
@@ -298,7 +289,7 @@ const DAEMON_KILL_WINDOW_MS = 2_000;
  *  waits on process death alone after a kill, never on pidfile release.
  *
  *  Returns how the daemon went down, for a truthful report. */
-export async function stopDaemonProcess(pid, timeoutMs = DAEMON_VERIFY_WINDOW_MS, deps = {}) {
+export async function stopDaemonProcess(pid, timeoutMs = DAEMON_SHUTDOWN_WINDOW_MS, deps = {}) {
     const alive = deps.isPidAlive ?? isPidAlive;
     const sleep = deps.sleepMs ?? sleepMs;
     const now = deps.now ?? Date.now;
@@ -377,7 +368,7 @@ export async function spawnDaemon() {
         exitState = { code, signal };
     });
     child.unref();
-    const existingPid = await verifyDaemonStartup(pid, DAEMON_VERIFY_WINDOW_MS, {
+    const existingPid = await verifyDaemonStartup(pid, DAEMON_STARTUP_WINDOW_MS, {
         childExited: () => exitState,
     });
     if (existingPid !== null) {

package/dist/daemon/startup-policy.d.ts

@@ -0,0 +1 @@
+export declare const DAEMON_STARTUP_WINDOW_MS: number;

package/dist/daemon/startup-policy.js

@@ -0,0 +1 @@
+export const DAEMON_STARTUP_WINDOW_MS = 5 * 60 * 1_000;

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

@@ -1,9 +1,7 @@
 // 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).
+// `read-when`) into explicit `surfaces` entries and bakes INDEX boot ceilings
+// into each doc's boot rung (per store).
 //
 // 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
@@ -13,14 +11,13 @@
 // 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
+// dead fields dying and `surfaces` appearing — 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 { isMap, parse as parseYaml, parseDocument, stringify } from 'yaml';
+import { parse as parseYaml } from 'yaml';
 import { parseFrontmatterGeneric } from '../core/frontmatter.js';
-import { findDocLinks } from '../core/memory/doc-link-grammar.js';
+import { appendRenderedKey, dropTopLevelKeys, proveFrontmatterRoundTrip, rebuildDocSource, } from './frontmatter-splice.js';
 const OLD_FIELDS = ['system-prompt-visibility', 'file-read-visibility', 'applies-to', 'read-when'];
 // ---------------------------------------------------------------------------
 // Frozen old-schema parsing (pre-cut substrate/schema.ts semantics).
@@ -133,122 +130,37 @@ function planEntries(d, bootRung) {
     return entries;
 }
 // ---------------------------------------------------------------------------
-// Rule 5: bare-dir `[[ref]]` → `[[dir/INDEX]]`. A ref is rewritten only when
-// the owning target corpus proves the old bare-directory convenience and the
-// explicit INDEX spelling resolve to the same file. The decision cache belongs
-// to one migration target; profile-local names never leak across stores.
+// Serialization: cut the dead keys' exact line spans out of the raw
+// frontmatter text, append the rendered `surfaces:` block, re-parse to prove
+// the splice is meaning-preserving.
 // ---------------------------------------------------------------------------
-function rewriteBareDirRefs(body, context, decisions) {
-    const links = findDocLinks(body);
-    if (links.length === 0)
-        return body;
-    let out = '';
-    let pos = 0;
-    for (const link of links) {
-        let repl = decisions.get(link.name);
-        if (repl === undefined) {
-            repl = context?.legacyDirectoryIndex(link.name) ?? null;
-            decisions.set(link.name, repl);
-        }
-        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$/, '');
+    let out = dropTopLevelKeys(rawYaml, OLD_FIELDS, docPath);
+    if (entries.length > 0)
+        out = appendRenderedKey(out, 'surfaces', entries, docPath);
+    else
+        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}`);
-    }
+    proveFrontmatterRoundTrip(out, expected, 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 = {
+    id: '001-surfaces-frontmatter',
     lane: 'convergent',
-    description: 'surfaces frontmatter: fold visibility/applies-to/read-when routing into surfaces entries; rewrite bare-directory [[refs]] to [[dir/INDEX]]',
-    apply(store, context) {
+    description: 'surfaces frontmatter: fold visibility/applies-to/read-when routing into surfaces entries',
+    apply(store) {
         const docs = store.docs.map(classify).filter((d) => d !== null);
         const ceiling = buildCeiling(docs);
-        const decisions = new Map();
         const changes = [];
         for (const d of docs) {
-            const newBody = rewriteBareDirRefs(d.doc.body, context, decisions);
-            if (!d.hasOldFields && newBody === d.doc.body)
+            if (!d.hasOldFields)
                 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) });
+            const newYaml = migratedYaml(parseFrontmatterGeneric(d.doc.source).raw, planEntries(d, effectiveBootRung(d, ceiling)), d.doc.path);
+            changes.push({ path: d.doc.path, after: rebuildDocSource(d.doc.source, newYaml, d.doc.path) });
         }
         return changes;
     },

package/dist/migrations/002-profile-project-memory.js

@@ -32,6 +32,7 @@ function isMemory(value) {
     return typeof value === 'string' && PROFILE_PROJECT_MEMORY_VALUES.includes(value);
 }
 export const profileProjectMemoryMigration = {
+    id: '002-profile-project-memory',
     lane: 'profile-manifest',
     description: 'profile projects carry an explicit memory value',
     apply(input) {