@north-light/crouter 0.3.173 → 0.3.175

package/dist/core/__tests__/helpers/harness.js

@@ -10,7 +10,7 @@
 //
 // See harness-design.md §4/§5 and vehicle-and-hooks.md §6 for the architecture
 // this implements. The ONE production seam used is CRTR_PI_BINARY in
-// piCommand (src/core/runtime/tmux.ts) — no production file is modified.
+// piCommand (src/core/runtime/tmux-driver.ts) — no production file is modified.
 //
 // Isolation contract (harness-design.md §4a):
 //   • The harness itself runs AS a canvas node, so its OWN process.env carries
@@ -28,7 +28,6 @@ import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 import { createNode, getNode, recordPid, subscribersOf, subscriptionsOf, } from '../../canvas/canvas.js';
 import { closeDb } from '../../canvas/db.js';
-import { isFocused } from '../../runtime/placement.js';
 import { reviveNode } from '../../runtime/revive.js';
 import { superviseTick } from '../../../daemon/crtrd.js';
 import { DaemonFleet } from '../../../daemon/fleet.js';
@@ -57,18 +56,13 @@ const TSX_ESM = COMPILED ? null : createRequire(import.meta.url).resolve('tsx/es
 // A multi-word launcher, baked verbatim ahead of the (shell-quoted) argv by the
 // seam. Absolute paths so it works regardless of the spawned window's cwd.
 const FAKE_PI_BINARY = [process.execPath, ...(TSX_ESM === null ? [] : ['--import', TSX_ESM]), FAKE_PI_HOST].join(' ');
-// Every raw `tmux` call the harness/full-tier tests make against the shared
+// Every raw `tmux` call the harness/compiled-seam tests make against the shared
 // DEFAULT server is synchronous (spawnSync). Node's spawnSync blocks the WHOLE
 // worker (no event loop, no `node --test` timeout can preempt it) until the
-// child exits — with no `timeout` option it can wait FOREVER. A wedged/CPU-
-// starved tmux server (the acknowledged "intermittent Linux-only crash-revive
-// wedge", CI-only) has been observed to hang one of these calls indefinitely,
-// which permanently consumes one of the `--test-concurrency` slots; as more
-// full-tier files each hit the SAME wedged server, every slot eventually gets
-// consumed the same way and the whole suite flatlines with zero further TAP
-// output (confirmed 3/3 in CI, see ci-full-suite-hang-blocker.md). TMUX_TIMEOUT_MS
-// bounds every raw tmux spawnSync call so a wedge fails that ONE call (and the
-// test it belongs to) fast instead of hanging the run.
+// child exits — with no `timeout` option it can wait forever. A wedged or
+// CPU-starved tmux server would consume a serialized seam worker indefinitely.
+// TMUX_TIMEOUT_MS makes that one call and its test fail instead of hanging the
+// whole suite.
 export const TMUX_TIMEOUT_MS = 10_000;
 /** True when a usable tmux is on PATH — tests gate on this and SKIP otherwise. */
 export function hasTmux() {
@@ -382,7 +376,7 @@ export async function createHarness(opts = {}) {
             // count). Scope the scan to "one or more lowercase-alnum segments ending
             // in an 8-hex random suffix" so a stray non-node sibling under nodes/ is
             // never miscounted as a new node dir — e.g. a `reports/` dir created for
-            // an empty node id (the rare CI flake on full-tier run 27459304455 that
+            // an empty node id (the rare CI flake on compiled-seam run 27459304455 that
             // broke the spawn counters with `expected exactly 1 new node dir, got
             // [<id>, reports]`), or literal `reports` (no hyphen, no hex suffix).
             return readdirSync(join(home, 'nodes')).filter((d) => /^[a-z0-9]+(?:-[a-z0-9]+)*-[0-9a-f]{8}$/.test(d));
@@ -513,27 +507,6 @@ export async function createHarness(opts = {}) {
             closeDb();
             return id;
         },
-        async spawnChild(parentId, task, o = {}) {
-            const before = new Set(nodeDirs());
-            const args = ['node', 'new', task, '--parent', parentId, '--cwd', CROUTER];
-            if (o.kind)
-                args.push('--kind', o.kind);
-            if (o.mode)
-                args.push('--mode', o.mode);
-            if (o.model)
-                args.push('--model', o.model);
-            const res = cli(parentId, args);
-            if (res.code !== 0) {
-                throw new Error(`spawnChild(${parentId}) failed (code ${res.code})\n--stdout--\n${res.stdout}\n--stderr--\n${res.stderr}`);
-            }
-            const added = nodeDirs().filter((d) => !before.has(d));
-            if (added.length !== 1) {
-                throw new Error(`spawnChild: expected exactly 1 new node dir, got [${added.join(', ')}]`);
-            }
-            const childId = added[0];
-            await harness.awaitBoot(childId);
-            return childId;
-        },
         async spawnHeadlessChild(parentId, task, o = {}) {
             const before = new Set(nodeDirs());
             // The synchronous CLI must reach the separate API fixture process, which
@@ -576,48 +549,12 @@ export async function createHarness(opts = {}) {
             await harness.awaitBoot(childId, { minCount: priorBoots + 1 });
             return childId;
         },
-        async spawnHeadlessChildNoBoot(parentId, task, o = {}) {
-            const before = new Set(nodeDirs());
-            const args = ['node', 'new', task, '--parent', parentId, '--cwd', CROUTER];
-            if (o.kind)
-                args.push('--kind', o.kind);
-            if (o.mode)
-                args.push('--mode', o.mode);
-            if (o.model)
-                args.push('--model', o.model);
-            const res = cli(parentId, args);
-            if (res.code !== 0) {
-                throw new Error(`spawnHeadlessChildNoBoot(${parentId}) failed (code ${res.code})\n--stdout--\n${res.stdout}\n--stderr--\n${res.stderr}`);
-            }
-            const added = nodeDirs().filter((d) => !before.has(d));
-            if (added.length !== 1) {
-                throw new Error(`spawnHeadlessChildNoBoot: expected exactly 1 new node dir, got [${added.join(', ')}]`);
-            }
-            return added[0];
-        },
         cli,
-        async turn(nodeId, text = '') {
-            const base = eventCount(nodeId, 'agent_end');
-            sendCmd(nodeId, { cmd: 'turn', id: `turn-${Date.now()}`, text });
-            await awaitAgentEnd(nodeId, base, `turn agent_end for ${nodeId}`);
-        },
         async stop(nodeId, reason = 'stop', errorMessage) {
             const base = eventCount(nodeId, 'agent_end');
             sendCmd(nodeId, { cmd: 'stop', id: `stop-${Date.now()}`, reason, errorMessage });
             await awaitAgentEnd(nodeId, base, `stop agent_end for ${nodeId}`);
         },
-        async finish(nodeId, finalText) {
-            const res = cli(nodeId, ['push', 'final', finalText]);
-            if (res.code !== 0) {
-                throw new Error(`finish(${nodeId}): push final failed (code ${res.code})\n${res.stderr}`);
-            }
-            // Fire agent_end so the now-done node runs the real (b) done branch
-            // (null presence + ctx.shutdown → window closes), exactly as real pi would.
-            const base = eventCount(nodeId, 'agent_end');
-            sendCmd(nodeId, { cmd: 'stop', id: `finish-${Date.now()}` });
-            await awaitAgentEnd(nodeId, base, `finish agent_end for ${nodeId}`);
-            await harness.waitForPaneGone(nodeId);
-        },
         async tick(now) {
             closeDb();
             // On the lane, after every already-enqueued exit job — the same strict
@@ -632,7 +569,6 @@ export async function createHarness(opts = {}) {
             await drainLane();
             closeDb();
         },
-        drainFleet: drainLane,
         async awaitFleetExit(nodeId, timeoutMs = 15_000) {
             await waitFor(() => !fleet.has(nodeId), {
                 timeoutMs,
@@ -706,18 +642,6 @@ export async function createHarness(opts = {}) {
             }, { timeoutMs: o.timeoutMs ?? 15_000, label: `wake delivery for ${nodeId}` });
             return fresh.map((e) => e.content);
         },
-        async waitForStatus(nodeId, status, timeoutMs = 20_000) {
-            await waitFor(() => {
-                closeDb();
-                return getNode(nodeId)?.status === status;
-            }, { timeoutMs, label: `status=${status} for ${nodeId}` });
-        },
-        async waitForPaneGone(nodeId, timeoutMs = 20_000) {
-            await waitFor(() => {
-                closeDb();
-                return !isFocused(nodeId);
-            }, { timeoutMs, label: `viewer gone for ${nodeId}` });
-        },
         waitFor,
         node(nodeId) {
             closeDb();
@@ -727,10 +651,6 @@ export async function createHarness(opts = {}) {
             closeDb();
             return getNode(nodeId)?.status ?? null;
         },
-        paneAlive(nodeId) {
-            closeDb();
-            return isFocused(nodeId);
-        },
         inbox(nodeId) {
             closeDb();
             return readInboxSince(nodeId);

package/dist/core/__tests__/helpers/viewer-panes.js

@@ -4,7 +4,7 @@
 // onto a tmux pane option that the `crtr surface attach` viewer self-sets once
 // its startup checkpoint clears (`clients/attach/session/pane-tag.ts`). These
 // helpers are the ground truth for "which pane is a node's viewer", shared by
-// every full-tier test that asserts viewer dedup or teardown.
+// every compiled-seam test that asserts viewer dedup or teardown.
 //
 // The waiter dumps the live pane table AND each pane's rendered screen on
 // failure: when a viewer never tags, the reason is almost always printed inside

package/dist/core/__tests__/inline-memory-refs.test.js

@@ -1,148 +1,19 @@
 // Run with: node --import tsx/esm --test src/core/__tests__/inline-memory-refs.test.ts
 //
-// Load-bearing shared-contract regression for the inline memory-reference
-// token grammar (spec §4.1): `src/core/memory/inline-ref-grammar.ts` is the
-// SINGLE implementation the broker, terminal attach viewer, and web composer
-// all consume. This file (Wave C1) covers the grammar/caret cases. Wave C4
-// extends it (below, in its own `describe`) with the
-// corpus/inventory/guidance cases: `buildRefInventory`'s precedence dedup,
-// both-kinds/gated/slash:false referenceability, INDEX naming, and
-// metadata-only output, plus `buildGuidance`'s exact-match resolution,
-// duplicate collapse, and first-appearance ordering.
+// Load-bearing corpus regression for `buildRefInventory` — the authoritative
+// inventory the broker and terminal attach viewer both resolve inline memory
+// references against. Covers scope precedence dedup, referenceability
+// (both kinds, gated and slash docs), INDEX folding, malformed-doc omission,
+// metadata-only rows, and stable ordering, all over real on-disk fixtures.
 import { test, describe, before, beforeEach, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { findRefTokens, formatRefToken, findRefTokenAtCaret, } from '../memory/inline-ref-grammar.js';
 import { resetScopeCache } from '../scope.js';
 import { clearSessionCache } from '../substrate/session-cache.js';
 import { memoryDir as nodeMemoryDir } from '../runtime/memory.js';
 import { buildRefInventory } from '../memory/inline-ref-inventory.js';
-import { buildGuidance } from '../memory/inline-ref-guidance.js';
-// One compact case table drives `findRefTokens` over the spec §4.1 + §5
-// examples: candidate decoding, punctuation trimming, first-segment-only
-// stops, and ASCII whitespace-boundary rejection.
-const GRAMMAR_CASES = [
-    { text: '/dev', expect: [{ raw: '/dev', candidate: 'dev' }] },
-    { text: 'read /dev before starting', expect: [{ raw: '/dev', candidate: 'dev' }] },
-    { text: '/taste:foo', expect: [{ raw: '/taste:foo', candidate: 'taste/foo' }] },
-    { text: '/a:b:c', expect: [{ raw: '/a:b:c', candidate: 'a/b/c' }] },
-    // Trailing punctuation is excluded (never even captured, since it is
-    // outside the [A-Za-z0-9_:-] class).
-    { text: 'read /dev. before starting', expect: [{ raw: '/dev', candidate: 'dev' }] },
-    { text: 'see /taste:foo)', expect: [{ raw: '/taste:foo', candidate: 'taste/foo' }] },
-    { text: '/dev,', expect: [{ raw: '/dev', candidate: 'dev' }] },
-    // Trailing `:` `-` `_` inside the captured run ARE trimmed (step 3).
-    { text: '/dev:', expect: [{ raw: '/dev', candidate: 'dev' }] },
-    { text: '/dev-', expect: [{ raw: '/dev', candidate: 'dev' }] },
-    { text: '/dev_', expect: [{ raw: '/dev', candidate: 'dev' }] },
-    { text: '/dev__--::', expect: [{ raw: '/dev', candidate: 'dev' }] },
-    // Nothing survives the trim -> no token.
-    { text: '/___', expect: [] },
-    { text: '/:::', expect: [] },
-    // A first segment only: `/foo/bar` yields the token `/foo`; `/bar` is not
-    // at a whitespace boundary.
-    { text: '/foo/bar', expect: [{ raw: '/foo', candidate: 'foo' }] },
-    // ASCII boundary rejection: a `/` preceded by any non-whitespace character
-    // is not a token start.
-    { text: 'http://example.com', expect: [] },
-    { text: 'and/or', expect: [] },
-    { text: '/usr/local/bin', expect: [{ raw: '/usr', candidate: 'usr' }] },
-    // Case sensitivity: candidate preserves original case (no normalization).
-    { text: '/Dev', expect: [{ raw: '/Dev', candidate: 'Dev' }] },
-    { text: '/dev /Dev', expect: [{ raw: '/dev', candidate: 'dev' }, { raw: '/Dev', candidate: 'Dev' }] },
-    // No leading text at all: start-of-input is a valid boundary.
-    { text: '/dev fix the build', expect: [{ raw: '/dev', candidate: 'dev' }] },
-    // No token characters at all after the slash.
-    { text: 'a / b', expect: [] },
-];
-test('findRefTokens: §4.1 grammar table', () => {
-    for (const { text, expect } of GRAMMAR_CASES) {
-        const tokens = findRefTokens(text);
-        assert.deepEqual(tokens.map((t) => ({ raw: t.raw, candidate: t.candidate })), expect, `findRefTokens(${JSON.stringify(text)})`);
-        // start/end must always bound `raw` exactly.
-        for (const t of tokens) {
-            assert.equal(text.slice(t.start, t.end), t.raw, `span mismatch for ${JSON.stringify(text)}`);
-        }
-    }
-});
-test('findRefTokens: nested-decode offsets are exact', () => {
-    const text = 'see /taste:foo) now';
-    const [tok] = findRefTokens(text);
-    assert.equal(tok.start, 4);
-    assert.equal(tok.end, 14); // just past 'o' in 'foo', before ')'
-    assert.equal(text.slice(tok.start, tok.end), '/taste:foo');
-});
-test('formatRefToken: canonical name -> surface token', () => {
-    assert.equal(formatRefToken('dev'), '/dev');
-    assert.equal(formatRefToken('taste/foo'), '/taste:foo');
-    assert.equal(formatRefToken('a/b/c'), '/a:b:c');
-});
-test('formatRefToken round-trips through findRefTokens candidates', () => {
-    for (const name of ['dev', 'taste/foo', 'a/b/c', 'spec-driven-development/spec-writing']) {
-        const surface = formatRefToken(name);
-        const [tok] = findRefTokens(surface);
-        assert.equal(tok?.candidate, name, `round-trip for ${name}`);
-    }
-});
-test('findRefTokenAtCaret: incomplete prefix (no trailing name segment yet)', () => {
-    const text = '/taste:';
-    const caret = findRefTokenAtCaret(text, text.length);
-    assert.deepEqual(caret, { start: 0, end: 7, surfacePrefix: '/taste:' });
-});
-test('findRefTokenAtCaret: caret mid-token is suffix-inclusive', () => {
-    const text = 'before /dev after';
-    const idx = text.indexOf('/dev') + 2; // caret between 'd' and 'e'
-    const caret = findRefTokenAtCaret(text, idx);
-    assert.deepEqual(caret, { start: 7, end: 11, surfacePrefix: '/d' });
-    assert.equal(text.slice(caret.start, caret.end), '/dev');
-});
-test('findRefTokenAtCaret: caret just after a bare slash', () => {
-    const text = 'prose / ';
-    const caret = findRefTokenAtCaret(text, text.indexOf('/') + 1);
-    assert.deepEqual(caret, { start: 6, end: 7, surfacePrefix: '/' });
-});
-test('findRefTokenAtCaret: no token touching caret -> null', () => {
-    assert.equal(findRefTokenAtCaret('plain prose', 3), null);
-    assert.equal(findRefTokenAtCaret('and/or here', 6), null); // '/' not a token start
-    assert.equal(findRefTokenAtCaret('', 0), null);
-});
-test('findRefTokenAtCaret: caret at start of a leading token', () => {
-    const text = '/dev fix this';
-    const caret = findRefTokenAtCaret(text, 1); // right after the slash
-    assert.deepEqual(caret, { start: 0, end: 4, surfacePrefix: '/' });
-});
-// ---------------------------------------------------------------------------
-// Wave C4 — buildGuidance: pure over (text, names), no filesystem/corpus
-// involved. See the fixture-backed buildRefInventory suite below for the
-// corpus/precedence/metadata cases.
-// ---------------------------------------------------------------------------
-const GUIDANCE_HEADER = 'The human explicitly referenced these memory documents. Before acting on the portion of their message that references each document, run the corresponding command and treat its returned content as authoritative context:';
-test('buildGuidance: single resolved ref emits the exact directive header + one read line', () => {
-    const names = new Set(['dev']);
-    const result = buildGuidance('read /dev before starting', names);
-    assert.equal(result, [GUIDANCE_HEADER, '- crtr memory read dev'].join('\n'));
-});
-test('buildGuidance: nested-name candidates decode back to slash form in the read line', () => {
-    const names = new Set(['taste/foo']);
-    const result = buildGuidance('see /taste:foo) now', names);
-    assert.equal(result, [GUIDANCE_HEADER, '- crtr memory read taste/foo'].join('\n'));
-});
-test('buildGuidance: duplicate refs collapse to one instruction; distinct refs list in first-appearance order', () => {
-    const names = new Set(['dev', 'taste/foo']);
-    const result = buildGuidance('/dev do X, then /taste:foo, and /dev again', names);
-    assert.equal(result, [GUIDANCE_HEADER, '- crtr memory read dev', '- crtr memory read taste/foo'].join('\n'));
-});
-test('buildGuidance: an unresolved/unknown token produces no guidance', () => {
-    assert.equal(buildGuidance('/nope has nothing to do with it', new Set(['dev'])), null);
-});
-test('buildGuidance: text with no slash tokens at all returns null', () => {
-    assert.equal(buildGuidance('plain prose, nothing to see here', new Set(['dev'])), null);
-});
-test('buildGuidance: exact case-sensitive matching — a differently-cased token does not resolve', () => {
-    assert.equal(buildGuidance('/Dev fix this', new Set(['dev'])), null);
-});
 // ---------------------------------------------------------------------------
 // Wave C4 — buildRefInventory: the authoritative corpus builder. Fixture-
 // backed (node/project/user scope docs on disk), since precedence dedup,

package/dist/core/__tests__/kickoff.test.js

@@ -15,7 +15,7 @@ import { closeDb } from '../canvas/db.js';
 import { buildReviveKickoff, clearYieldMessage, drainBearings, readYieldMessage, writeYieldMessage, yieldMessagePath, } from '../runtime/kickoff.js';
 import { appendInbox, readCursor } from '../feed/inbox.js';
 import { appendSituationalContext } from '../runtime/situational-context.js';
-import { buildContextIntro } from '../../pi-extensions/canvas-context-intro.js';
+import { buildContextBearings as buildContextIntro } from '../runtime/bearings.js';
 let home;
 function node(id) {
     return {

package/dist/core/__tests__/memory-resolver-precedence.test.js

@@ -20,7 +20,7 @@ import { mkdtempSync, mkdirSync, rmSync, writeFileSync, realpathSync } from 'nod
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { resetScopeCache } from '../scope.js';
-import { resolveMemoryDoc } from '../memory-resolver.js';
+import { resolveMemoryDoc, resolveMemoryDocs } from '../memory-resolver.js';
 let home;
 let base;
 let root;
@@ -91,6 +91,18 @@ test('a physical-path query whose nearest match diverged in identity from a fart
         process.chdir(prevCwd);
     }
 });
+test('batch resolution preserves direct-path precedence over a farther matching identity', () => {
+    process.chdir(child);
+    resetScopeCache();
+    try {
+        const doc = resolveMemoryDocs(['AGENTS']).get('AGENTS');
+        assert.equal(doc?.path, join(child, '.crouter', 'memory', 'AGENTS.md'));
+        assert.match(doc?.body ?? '', /CHILD AGENTS BODY/);
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
+});
 test('a migrated nested doc resolves by its explicit slashed identity', () => {
     process.chdir(grandchild);
     resetScopeCache();
@@ -128,6 +140,22 @@ test('a bare-directory query resolves to that dir\'s INDEX.md, nearest copy firs
         process.chdir(prevCwd);
     }
 });
+test("an explicit '<dir>/INDEX' identity resolves to that physical INDEX.md", () => {
+    // The assembled memory tree addresses a directory INDEX by its extensionless
+    // resolver identity, so `<dir>/INDEX` must resolve to the physical INDEX.md
+    // and report back the same identifier it was asked for.
+    process.chdir(child);
+    resetScopeCache();
+    try {
+        const doc = resolveMemoryDoc('taste/INDEX');
+        assert.equal(doc.path, join(child, '.crouter', 'memory', 'taste', 'INDEX.md'));
+        assert.equal(doc.name, 'taste/INDEX');
+        assert.match(doc.body, /CHILD TASTE INDEX/);
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
+});
 test('--kind skips a nearer wrong-kind (frontmatter-less, kind-defaulted) doc and resolves the farther matching-kind doc', () => {
     process.chdir(child);
     resetScopeCache();

package/dist/core/__tests__/migration.test.js

@@ -8,6 +8,7 @@ import { DatabaseSync } from 'node:sqlite';
 import { openDb, closeDb, migrate, MIGRATIONS } from '../canvas/db.js';
 import { canvasDbPath, ensureHome } from '../canvas/paths.js';
 import { customExtensionPaths } from '../canvas/extensions.js';
+import { assertMandatoryCanvasExtensions, CANVAS_EXTENSIONS, mergeCanvasExtensions } from '../runtime/canvas-extensions.js';
 import { updateNode } from '../canvas/canvas.js';
 import { spawn, spawnSync } from 'node:child_process';
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -84,6 +85,21 @@ test('a persisted review-boundary canvas prefix is not treated as custom extensi
     const persisted = REVIEW_BOUNDARY_CANVAS_EXTENSION_NAMES.map((name) => `/old-generation/pi-extensions/${name}.js`);
     assert.deepEqual(customExtensionPaths(persisted), []);
 });
+test('stale generation hooks are retired structurally without dropping user extensions', () => {
+    const stale = [
+        'canvas-inbox-watcher', 'canvas-stophook', 'canvas-recap', 'canvas-goal-capture',
+        'canvas-passive-context', 'canvas-context-intro', 'canvas-tool-guide',
+        'canvas-doc-substrate', 'canvas-structured-output', 'canvas-bash-valve',
+    ].map((name) => `/Users/silasrhyneer/.crouter/runtime/generations/d3ff9346e6df88f88c44af898a028a8fd6f03466eb216d7cd3b70a734f71a11b/dist/pi-extensions/${name}.js`);
+    assert.deepEqual(customExtensionPaths(stale), []);
+    assert.deepEqual(customExtensionPaths([...stale, '/Users/silasrhyneer/extensions/canvas-foo.js']), ['/Users/silasrhyneer/extensions/canvas-foo.js']);
+});
+test('a retained custom extension sharing a canvas-hook basename still launches', () => {
+    const custom = '/Users/silasrhyneer/extensions/canvas-recap.js';
+    assert.deepEqual(customExtensionPaths([custom]), [custom]);
+    assert.doesNotThrow(() => assertMandatoryCanvasExtensions(mergeCanvasExtensions([custom])));
+    assert.throws(() => assertMandatoryCanvasExtensions([...CANVAS_EXTENSIONS, '/stale-root/pi-extensions/canvas-recap.js']), /duplicate mandatory canvas extension basename canvas-recap/);
+});
 test('a v14 canvas normalizes historical canvas paths while retaining custom launch extras', () => {
     const metaPath = join(home, 'nodes', 'saved', 'meta.json');
     mkdirSync(join(home, 'nodes', 'saved'), { recursive: true });
@@ -265,54 +281,6 @@ test('v4 migrates a db with a pre-existing orphan edge without throwing', () =>
     assert.equal(surviving.from_id, 'n1');
     assert.equal(surviving.to_id, 'n2');
 });
-test('v4 leaves the FK live: an edge to a missing node is rejected', () => {
-    const raw = buildV3Db();
-    insertNode(raw, 'n1');
-    raw.close();
-    const db = openDb();
-    assert.equal(userVersion(db), MIGRATIONS.length);
-    // Inserting an edge whose endpoint has no node row now violates the FK.
-    assert.throws(() => db
-        .prepare('INSERT INTO edges (type, from_id, to_id, active, created) VALUES (?,?,?,?,?)')
-        .run('spawned_by', 'n1', 'missing', 1, '2020-01-01T00:00:00Z'), /FOREIGN KEY|constraint/i);
-    // A fully-valid edge (both endpoints present) still inserts fine.
-    insertNode(db, 'n3');
-    assert.doesNotThrow(() => db
-        .prepare('INSERT INTO edges (type, from_id, to_id, active, created) VALUES (?,?,?,?,?)')
-        .run('subscribes_to', 'n1', 'n3', 1, '2020-01-01T00:00:00Z'));
-});
-test('v4 deleting a node cascade-deletes its edges', () => {
-    const raw = buildV3Db();
-    insertNode(raw, 'a');
-    insertNode(raw, 'b');
-    insertEdge(raw, 'subscribes_to', 'a', 'b');
-    insertEdge(raw, 'spawned_by', 'b', 'a');
-    raw.close();
-    const db = openDb();
-    assert.equal(edgeCount(db), 2);
-    // Delete one endpoint — every edge touching it cascades away.
-    db.prepare('DELETE FROM nodes WHERE node_id = ?').run('a');
-    assert.equal(edgeCount(db), 0);
-});
-test('v4 is idempotent on re-open', () => {
-    const raw = buildV3Db();
-    insertNode(raw, 'n1');
-    insertEdge(raw, 'subscribes_to', 'n1', 'n1');
-    raw.close();
-    const db = openDb();
-    assert.equal(userVersion(db), MIGRATIONS.length);
-    assert.equal(edgeCount(db), 1);
-    // Re-running migrate() directly is a no-op (gate skips applied steps); the
-    // edges table is NOT rebuilt again.
-    assert.doesNotThrow(() => migrate(db));
-    assert.equal(userVersion(db), MIGRATIONS.length);
-    assert.equal(edgeCount(db), 1);
-    // Re-opening from disk is likewise a no-op — the FK + data persist.
-    closeDb();
-    const db2 = openDb();
-    assert.equal(userVersion(db2), MIGRATIONS.length);
-    assert.equal(edgeCount(db2), 1);
-});
 function buildV4DbWithLaterColumns() {
     ensureHome();
     const raw = new DatabaseSync(canvasDbPath());
@@ -365,6 +333,25 @@ test('bug #99: a stale v4 db with later columns already present migrates cleanly
     assert.equal(row.pane, '%9');
     assert.equal(row.host_kind, 'broker');
 });
+test('v16 repairs a v15 database missing canonical finalization columns', () => {
+    ensureHome();
+    const db = new DatabaseSync(join(home, 'finalization.db'));
+    try {
+        MIGRATIONS[0](db);
+        db.exec('PRAGMA user_version = 15');
+        migrate(db);
+        const columns = nodeColumns(db);
+        assert.ok(columns.includes('final_report'));
+        assert.ok(columns.includes('finalized_at'));
+        // migrate() always brings a db to the latest schema, not just v16 — assert
+        // against the live migration count rather than a version snapshot that will
+        // go stale every time a new migration is appended.
+        assert.equal(userVersion(db), MIGRATIONS.length);
+    }
+    finally {
+        db.close();
+    }
+});
 // --- v22: legacy schedules → crons ------------------------------------------
 function buildV21Db() {
     ensureHome();

package/dist/core/__tests__/on-read-dedup-resume.test.js

@@ -1,16 +1,17 @@
 // On-read context surfaces at most once per conversation. The dedup set lives
 // at nodes/<id>/injected-docs.json so a process resumed onto the same transcript
-// rehydrates it, while a fresh transcript clears it.
+// rehydrates it, while a fresh transcript clears it. The same loader resolves a
+// doc's identity with the explicit-name-then-path-fallback rule the boot resolver
+// uses (schema.ts's resolveDocName), never deriving `name` from the path alone.
 //
 // Run: node --import tsx/esm --test src/core/__tests__/on-read-dedup-resume.test.ts
 import { test, before, beforeEach, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { closeDb } from '../canvas/db.js';
 import { resetScopeCache } from '../scope.js';
-import { injectedDocsPath } from '../canvas/paths.js';
 import { spawnNode } from '../runtime/nodes.js';
 import { renderOnReadDocs } from '../substrate/on-read.js';
 import { loadInjectedDocs, saveInjectedDocs, clearInjectedDocs, } from '../substrate/injected-store.js';
@@ -44,15 +45,6 @@ after(() => {
     else
         process.env['HOME'] = prevHomeEnv;
 });
-test('injected-store round-trips and clears', () => {
-    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
-    assert.deepEqual([...loadInjectedDocs(node)], [], 'cold load is empty');
-    saveInjectedDocs(node, new Set(['/a', '/b']));
-    assert.deepEqual([...loadInjectedDocs(node)].sort(), ['/a', '/b'], 'save then load round-trips');
-    clearInjectedDocs(node);
-    assert.ok(!existsSync(injectedDocsPath(node)), 'clear removes the file');
-    assert.deepEqual([...loadInjectedDocs(node)], [], 'load after clear is empty');
-});
 test('project and user memory docs without applies-to do not fire on file reads', () => {
     const fakeHome = mkdtempSync(join(tmpdir(), 'crtr-onread-user-home-'));
     process.env['HOME'] = fakeHome;
@@ -107,3 +99,21 @@ test('on-read doc surfaces once, stays deduped across a revive(resume), re-surfa
     const seenFresh = loadInjectedDocs(node);
     assert.ok(renderOnReadDocs(node, readFile, seenFresh).includes(FIXTURE_BODY), 'a fresh transcript surfaces the doc again');
 });
+test('an explicitly routed doc injects on-read under its frontmatter name, not the path-derived one', () => {
+    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+    const memDir = join(work, '.crouter', 'memory');
+    mkdirSync(memDir, { recursive: true });
+    writeFileSync(join(memDir, 'physical-guide.md'), '---\nkind: knowledge\n' +
+        'name: acme-project\n' +
+        'when-and-why-to-read: When reading acme source, this knowledge should be read because it carries the project-specific implementation constraints.\n' +
+        'file-read-visibility: content\n' +
+        'applies-to: "src/**"\n---\n' +
+        'ACME PROJECT OPERATING GUIDE\n');
+    const readFile = join(work, 'src', 'file.ts');
+    mkdirSync(join(work, 'src'), { recursive: true });
+    writeFileSync(readFile, 'export const x = 1;\n');
+    const rendered = renderOnReadDocs(node, readFile, new Set());
+    assert.ok(rendered.includes('ACME PROJECT OPERATING GUIDE'), 'the matching explicit route fires');
+    assert.ok(rendered.includes('<memory kind="knowledge" name="acme-project"'), `expected explicit frontmatter name "acme-project" in the injected envelope, got: ${rendered}`);
+    assert.ok(!rendered.includes('name="physical-guide"'), 'must not fall back to the path-derived name when frontmatter sets one');
+});