@crouton-kit/crouter 0.3.33 → 0.3.35

package/dist/core/__tests__/pane-column.test.js

@@ -1,153 +0,0 @@
-// Run with: node --import tsx/esm --test src/core/__tests__/pane-column.test.ts
-//
-// STEP 2 of the placement/focus migration: the `pane` runtime column —
-// LOCATION's authoritative handle (the durable tmux `%pane_id`). This step is
-// PURELY ADDITIVE: the column exists, setPresence writes it, getNode/getRow read
-// it back, but nothing READS it for behavior yet (population wires up in Steps
-// 3+). Covers:
-//   - migration v5 adds `pane` to a fresh db (and a legacy v4 db migrates up)
-//   - createNode seeds pane; setPresence writes it atomically with window/session
-//   - getNode (hydrated view) + getRow (row) both read pane back
-//   - a row never given a pane reads pane=null (legacy/back-compat)
-//   - the migration is idempotent / forward-only (re-open is a no-op)
-import { test, before, beforeEach, after } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { DatabaseSync } from 'node:sqlite';
-import { createNode, getNode, getRow, setPresence } from '../canvas/canvas.js';
-import { openDb, closeDb, migrate, MIGRATIONS } from '../canvas/db.js';
-import { canvasDbPath, ensureHome } from '../canvas/paths.js';
-let home;
-function node(id, over = {}) {
-    return {
-        node_id: id,
-        name: id,
-        created: new Date().toISOString(),
-        cwd: '/tmp/work',
-        kind: 'general',
-        mode: 'base',
-        lifecycle: 'terminal',
-        status: 'active',
-        ...over,
-    };
-}
-function userVersion(db) {
-    return db.prepare('PRAGMA user_version').get().user_version;
-}
-function nodeColumns(db) {
-    return db.prepare('PRAGMA table_info(nodes)').all().map((r) => r.name);
-}
-before(() => {
-    home = mkdtempSync(join(tmpdir(), 'crtr-pane-'));
-    process.env['CRTR_HOME'] = home;
-});
-beforeEach(() => {
-    closeDb();
-    rmSync(home, { recursive: true, force: true });
-});
-after(() => {
-    closeDb();
-    rmSync(home, { recursive: true, force: true });
-    delete process.env['CRTR_HOME'];
-});
-// ---------------------------------------------------------------------------
-// Migration v5 — the additive `pane` column.
-// ---------------------------------------------------------------------------
-test('a fresh db migrates to the latest version and has the pane column', () => {
-    const db = openDb();
-    assert.equal(userVersion(db), MIGRATIONS.length);
-    assert.ok(nodeColumns(db).includes('pane'), 'nodes.pane exists on a fresh db');
-});
-test('a v4 db migrates forward, adding pane=NULL without disturbing existing data', () => {
-    // Hand-build a db at exactly v4: baseline + the four v2 runtime columns +
-    // edges WITH the v4 FK shape, user_version=4 — the shape just before v5.
-    ensureHome();
-    const raw = new DatabaseSync(canvasDbPath());
-    raw.exec(`
-    CREATE TABLE nodes (
-      node_id TEXT PRIMARY KEY, name TEXT NOT NULL, kind TEXT NOT NULL,
-      mode TEXT NOT NULL DEFAULT 'base', lifecycle TEXT NOT NULL DEFAULT 'terminal',
-      status TEXT NOT NULL DEFAULT 'active', cwd TEXT NOT NULL, parent TEXT,
-      created TEXT NOT NULL,
-      intent TEXT, pi_pid INTEGER, window TEXT, tmux_session TEXT
-    );
-    CREATE TABLE edges (
-      type TEXT NOT NULL, from_id TEXT NOT NULL, to_id TEXT NOT NULL,
-      active INTEGER NOT NULL DEFAULT 1, created TEXT NOT NULL,
-      PRIMARY KEY (type, from_id, to_id),
-      FOREIGN KEY (from_id) REFERENCES nodes(node_id) ON DELETE CASCADE,
-      FOREIGN KEY (to_id)   REFERENCES nodes(node_id) ON DELETE CASCADE
-    );
-    PRAGMA user_version = 4;
-  `);
-    raw
-        .prepare('INSERT INTO nodes (node_id, name, kind, status, cwd, created, window, tmux_session) VALUES (?,?,?,?,?,?,?,?)')
-        .run('legacy', 'Legacy', 'general', 'idle', '/tmp/work', '2020-01-01T00:00:00Z', '@9', 'crtr');
-    assert.equal(userVersion(raw), 4);
-    assert.ok(!nodeColumns(raw).includes('pane'), 'precondition: no pane column at v4');
-    raw.close();
-    // openDb() runs v5 forward.
-    const db = openDb();
-    assert.equal(userVersion(db), MIGRATIONS.length);
-    assert.ok(nodeColumns(db).includes('pane'), 'pane column added by v5');
-    // The pre-existing row is intact; its pane backfills NULL (additive default).
-    const row = db
-        .prepare('SELECT status, window, tmux_session, pane FROM nodes WHERE node_id = ?')
-        .get('legacy');
-    assert.equal(row['status'], 'idle', 'existing status untouched');
-    assert.equal(row['window'], '@9', 'existing window untouched');
-    assert.equal(row['tmux_session'], 'crtr', 'existing session untouched');
-    assert.equal(row['pane'], null, 'pane defaults NULL for a legacy row');
-});
-test('the migration is idempotent / forward-only on re-run and re-open', () => {
-    const db = openDb();
-    assert.equal(userVersion(db), MIGRATIONS.length);
-    // Re-running migrate() is a no-op — the gate skips applied steps, so the v5
-    // ALTER ADD COLUMN never fires twice (which would throw "duplicate column").
-    assert.doesNotThrow(() => migrate(db));
-    assert.equal(userVersion(db), MIGRATIONS.length);
-    // Re-opening from disk is likewise a no-op.
-    closeDb();
-    const db2 = openDb();
-    assert.equal(userVersion(db2), MIGRATIONS.length);
-    assert.ok(nodeColumns(db2).includes('pane'));
-});
-// ---------------------------------------------------------------------------
-// Round-trip: pane is a RUNTIME field, authoritative in the row, read back by
-// both the hydrated view (getNode) and the row (getRow).
-// ---------------------------------------------------------------------------
-test('createNode seeds pane and getNode/getRow read it back', () => {
-    createNode(node('n', { tmux_session: 'crtr', window: '@1', pane: '%5' }));
-    assert.equal(getNode('n')?.pane, '%5', 'getNode hydrates pane from the row');
-    assert.equal(getRow('n')?.pane, '%5', 'getRow returns pane on the NodeRow');
-});
-test('a node created without a pane reads pane=null (legacy / back-compat)', () => {
-    createNode(node('n', { tmux_session: 'crtr', window: '@1' }));
-    assert.equal(getNode('n')?.pane, null, 'no pane given → null on the hydrated view');
-    assert.equal(getRow('n')?.pane, null, 'no pane given → null on the row');
-});
-test('setPresence writes pane atomically alongside window + session', () => {
-    createNode(node('n'));
-    setPresence('n', { tmux_session: 'user-sess', window: '@2', pane: '%7' });
-    const m = getNode('n');
-    assert.equal(m?.pane, '%7', 'setPresence wrote the pane');
-    assert.equal(m?.window, '@2', 'setPresence wrote the window in the same statement');
-    assert.equal(m?.tmux_session, 'user-sess', 'setPresence wrote the session in the same statement');
-});
-test('setPresence without pane writes null (the Step-2 contract: nobody reads pane yet)', () => {
-    createNode(node('n', { pane: '%7' }));
-    assert.equal(getNode('n')?.pane, '%7');
-    // A presence write that omits pane resets it to null — fine for Step 2 because
-    // no reader depends on pane until the placement layer lands (Steps 3+).
-    setPresence('n', { tmux_session: 'crtr', window: '@3' });
-    assert.equal(getNode('n')?.pane, null, 'omitted pane → null (no half-written LOCATION)');
-});
-test('pane is a RUNTIME field — it never leaks into meta.json identity', () => {
-    createNode(node('n', { pane: '%5' }));
-    setPresence('n', { pane: '%9', window: '@1', tmux_session: 'crtr' });
-    // meta.json is durable identity only; the runtime pane lives in the row.
-    const onDisk = openDb().prepare('SELECT pane FROM nodes WHERE node_id = ?').get('n');
-    assert.equal(onDisk.pane, '%9', 'pane is authoritative in the row');
-});

package/dist/core/__tests__/persona-compose.test.d.ts

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

package/dist/core/__tests__/persona-compose.test.js

@@ -1,53 +0,0 @@
-// Run: node --import tsx/esm --test src/core/__tests__/persona-compose.test.ts
-//
-// The static system-prompt composer (core/personas/resolve.ts) varies the
-// runtime protocol on TWO axes beyond kind×mode:
-//   • lifecycle (terminal | resident) — the "how you end" contract.
-//   • spine position (hasManager) — whether the push-up family is taught AT ALL.
-// These assert the four corners, especially the resident+no-manager root that
-// must never hear about `push` (final OR update).
-import { test } from 'node:test';
-import assert from 'node:assert/strict';
-import { resolve } from '../personas/index.js';
-// The lifecycle fragment is identified by its signature contract phrase, not by
-// the raw "push final" substring — the resident fragment legitimately NAMES
-// `push final` only to forbid it. The kind body is now lifecycle-neutral, so the
-// only finish contract in the prompt is whichever fragment composed.
-const TERMINAL_CONTRACT = /owe a final result and you reap when done/i;
-const RESIDENT_CONTRACT = /never forced to submit a final result/i;
-const PUSH_UP = /crtr push (update|urgent)/i;
-test('terminal + has-manager (the default child worker): terminal finish + push up', () => {
-    const p = resolve('general', 'base', { lifecycle: 'terminal', hasManager: true });
-    assert.match(p.systemPrompt, TERMINAL_CONTRACT, 'a terminal node owes a final and finishes via push final');
-    assert.doesNotMatch(p.systemPrompt, RESIDENT_CONTRACT);
-    assert.match(p.systemPrompt, PUSH_UP, 'a managed node reports up via push update/urgent');
-    assert.equal(p.lifecycle, 'terminal');
-});
-test('resident + no-manager (the user-facing root): resident finish, and NO push-up family at all', () => {
-    const p = resolve('general', 'base', { lifecycle: 'resident', hasManager: false });
-    assert.match(p.systemPrompt, RESIDENT_CONTRACT, 'a resident root is never forced to submit');
-    assert.doesNotMatch(p.systemPrompt, TERMINAL_CONTRACT, 'it does not get the terminal finish contract');
-    assert.doesNotMatch(p.systemPrompt, PUSH_UP, 'a top-of-spine root has nobody to push up to');
-    assert.match(p.systemPrompt, /top of your spine/i, 'oriented as top-of-spine');
-    assert.match(p.systemPrompt, /dormant/i, 'told it goes dormant and wakes');
-});
-test('resident + has-manager (interactable sub-orchestrator): resident finish, but still push up', () => {
-    const p = resolve('general', 'base', { lifecycle: 'resident', hasManager: true });
-    assert.match(p.systemPrompt, RESIDENT_CONTRACT, 'resident is never forced to submit a final');
-    assert.doesNotMatch(p.systemPrompt, TERMINAL_CONTRACT);
-    assert.match(p.systemPrompt, PUSH_UP, 'still reports progress up to its manager');
-});
-test('terminal + no-manager (a terminal root): terminal finish, but no push up', () => {
-    const p = resolve('general', 'base', { lifecycle: 'terminal', hasManager: false });
-    assert.match(p.systemPrompt, TERMINAL_CONTRACT, 'terminal still finishes via push final (self-completes)');
-    assert.doesNotMatch(p.systemPrompt, PUSH_UP, 'nobody subscribes, so no report-up family');
-});
-test('the lifecycle-neutral base survives in every corner (delegate + human ask)', () => {
-    for (const hasManager of [true, false]) {
-        for (const lifecycle of ['terminal', 'resident']) {
-            const p = resolve('general', 'base', { lifecycle, hasManager });
-            assert.match(p.systemPrompt, /crtr node new/, `delegate verb present (${lifecycle}/${hasManager})`);
-            assert.match(p.systemPrompt, /crtr human ask/, `human-ask present (${lifecycle}/${hasManager})`);
-        }
-    }
-});

package/dist/core/__tests__/persona-subkind.test.d.ts

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

package/dist/core/__tests__/persona-subkind.test.js

@@ -1,65 +0,0 @@
-// Run: node --import tsx/esm --test src/core/__tests__/persona-subkind.test.ts
-//
-// Scoped persona sub-personas: a kind has specialist reviewer personas at
-// `<kind>/reviewers/<name>/PERSONA.md`, enumerated by `subPersonasFor(kind)` and
-// rendered into that kind's composed prompt (and nowhere else) by `resolve`.
-// Visibility = membership (the sub-persona's `availableTo`, default = its
-// top-level ancestor kind): only `plan` sees the `plan/reviewers/*` menu; the
-// `reviewers/` grouping dir is transparent so the kind string keeps it; the
-// sub-personas never pollute the global `availableKinds()` list; and a
-// sub-persona itself boots as a real composed persona with the terminal finish
-// contract.
-import { test } from 'node:test';
-import assert from 'node:assert/strict';
-import { resolve } from '../personas/resolve.js';
-import { subPersonasFor, availableKinds } from '../personas/loader.js';
-const PLAN_REVIEWER_KINDS = [
-    'plan/reviewers/architecture-fit',
-    'plan/reviewers/code-smells',
-    'plan/reviewers/pattern-consistency',
-    'plan/reviewers/requirements-coverage',
-    'plan/reviewers/security',
-];
-const MENU_HEADER = 'Sub-personas you may spawn';
-test('subPersonasFor("plan") returns the five reviewers sorted, each with a non-empty whenToUse', () => {
-    const subs = subPersonasFor('plan');
-    assert.deepEqual(subs.map((s) => s.kind), PLAN_REVIEWER_KINDS, 'the five plan reviewer kind strings in sorted order — the transparent reviewers/ dir keeps the full kind path');
-    for (const s of subs) {
-        assert.ok(s.whenToUse.length > 0, `${s.kind} carries a non-empty whenToUse`);
-    }
-});
-test('availability is membership: a kind with no available sub-personas yields []', () => {
-    assert.deepEqual(subPersonasFor('explore'), [], 'no sub-persona is availableTo explore');
-    assert.deepEqual(subPersonasFor('plan/reviewers/security'), [], 'the five reviewers default availableTo:[plan] — none are available to a reviewer kind');
-});
-test('availableKinds() contains no plan/reviewers/* — sub-personas never pollute the global list', () => {
-    const kinds = availableKinds();
-    for (const k of PLAN_REVIEWER_KINDS) {
-        assert.ok(!kinds.includes(k), `${k} must not appear in availableKinds()`);
-    }
-    assert.ok(!kinds.some((k) => k.includes('reviewers')), 'no kind contains "reviewers"');
-});
-test('resolve(plan, orchestrator) renders the menu with all five reviewer strings', () => {
-    const p = resolve('plan', 'orchestrator', { lifecycle: 'terminal', hasManager: true });
-    assert.match(p.systemPrompt, new RegExp(MENU_HEADER), 'the menu header is present');
-    for (const k of PLAN_REVIEWER_KINDS) {
-        assert.ok(p.systemPrompt.includes(k), `menu lists ${k}`);
-    }
-});
-test('resolve(plan, base) ALSO renders the menu (render-for-both decision)', () => {
-    const p = resolve('plan', 'base', { lifecycle: 'terminal', hasManager: true });
-    assert.match(p.systemPrompt, new RegExp(MENU_HEADER), 'a base plan node sees the roster too');
-    for (const k of PLAN_REVIEWER_KINDS) {
-        assert.ok(p.systemPrompt.includes(k), `menu lists ${k}`);
-    }
-});
-test('resolve(general, orchestrator) does NOT render the menu (visibility = membership)', () => {
-    const p = resolve('general', 'orchestrator', { lifecycle: 'terminal', hasManager: true });
-    assert.doesNotMatch(p.systemPrompt, new RegExp(MENU_HEADER), 'general owns no roster, so no menu');
-});
-test('a reviewer sub-kind boots as a real composed persona with the terminal finish contract and no menu', () => {
-    const p = resolve('plan/reviewers/security', 'base', { lifecycle: 'terminal', hasManager: true });
-    assert.ok(p.systemPrompt.includes('concrete exploit path'), 'the security-reviewer lens expertise is present');
-    assert.match(p.systemPrompt, /owe a final result and you reap when done/i, 'the terminal finish contract composed in — it boots as a real persona');
-    assert.doesNotMatch(p.systemPrompt, new RegExp(MENU_HEADER), 'a sub-kind owns no roster of its own — it renders no menu');
-});

package/dist/core/__tests__/persona.test.d.ts

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

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

@@ -1,107 +0,0 @@
-// Run: node --import tsx/esm --test src/core/__tests__/persona.test.ts
-//
-// The persona-transition mechanism: the two-axis model (mode × lifecycle) is
-// switchable independently, and `personaDrift` detects when a node's live
-// {mode,lifecycle} has diverged from the `persona_ack` it was last given
-// guidance for (the central injector then delivers + commits).
-import { test, before, after, beforeEach } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { spawnNode } from '../runtime/nodes.js';
-import { promote } from '../runtime/promote.js';
-import { getNode, updateNode } from '../canvas/canvas.js';
-import { closeDb } from '../canvas/db.js';
-import { personaDrift, commitPersonaAck, transitionGuidance, } from '../runtime/persona.js';
-let home;
-before(() => {
-    home = mkdtempSync(join(tmpdir(), 'crtr-persona-'));
-    process.env['CRTR_HOME'] = home;
-});
-beforeEach(() => {
-    closeDb();
-    rmSync(home, { recursive: true, force: true });
-});
-after(() => {
-    closeDb();
-    rmSync(home, { recursive: true, force: true });
-    delete process.env['CRTR_HOME'];
-});
-// ---------------------------------------------------------------------------
-// Birth: a fresh node is born acked to its own persona — no spurious drift.
-// ---------------------------------------------------------------------------
-test('a freshly spawned node has no persona drift (born acked to its own persona)', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'terminal' });
-    assert.deepEqual(meta.persona_ack, { mode: 'base', lifecycle: 'terminal' });
-    assert.equal(personaDrift(meta.node_id), null, 'no drift at birth');
-});
-// ---------------------------------------------------------------------------
-// Fix 1: promote keeps lifecycle by default; --resident flips it.
-// ---------------------------------------------------------------------------
-test('promote flips mode→orchestrator and KEEPS lifecycle terminal by default', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'terminal' });
-    const res = promote(meta.node_id);
-    assert.equal(res.meta.mode, 'orchestrator');
-    assert.equal(res.meta.lifecycle, 'terminal', 'lifecycle is NOT forced to resident');
-});
-test('promote with resident:true ALSO flips lifecycle→resident', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'terminal' });
-    const res = promote(meta.node_id, { resident: true });
-    assert.equal(res.meta.mode, 'orchestrator');
-    assert.equal(res.meta.lifecycle, 'resident', 'resident flag flips lifecycle');
-});
-test('promote no longer returns a guidance field (injector is the single source)', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'terminal' });
-    const res = promote(meta.node_id);
-    assert.equal('guidance' in res, false, 'promote() returns facts only');
-});
-// ---------------------------------------------------------------------------
-// personaDrift detect + commit.
-// ---------------------------------------------------------------------------
-test('personaDrift detects base→orchestrator after promote, then clears on commit', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'terminal' });
-    promote(meta.node_id); // mode→orchestrator, lifecycle stays terminal
-    const drift = personaDrift(meta.node_id);
-    assert.ok(drift !== null, 'a transition is detected');
-    assert.deepEqual(drift?.from, { mode: 'base', lifecycle: 'terminal' });
-    assert.deepEqual(drift?.to, { mode: 'orchestrator', lifecycle: 'terminal' });
-    assert.ok((drift?.guidance ?? '').length > 0, 'guidance is built');
-    // Caller commits the ack after delivery — drift then clears (idempotent).
-    commitPersonaAck(meta.node_id, drift.to);
-    assert.equal(personaDrift(meta.node_id), null, 'no drift after the ack is committed');
-    assert.deepEqual(getNode(meta.node_id)?.persona_ack, { mode: 'orchestrator', lifecycle: 'terminal' });
-});
-test('personaDrift detects a lifecycle-only flip (terminal→resident)', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'terminal' });
-    // Flip only the lifecycle axis — mode unchanged.
-    updateNode(meta.node_id, { lifecycle: 'resident' });
-    const drift = personaDrift(meta.node_id);
-    assert.ok(drift !== null);
-    assert.deepEqual(drift?.from, { mode: 'base', lifecycle: 'terminal' });
-    assert.deepEqual(drift?.to, { mode: 'base', lifecycle: 'resident' });
-    assert.match(drift?.guidance ?? '', /resident/i, 'guidance describes the resident state');
-});
-// ---------------------------------------------------------------------------
-// transitionGuidance: each lifecycle case + both-axes concatenation.
-// ---------------------------------------------------------------------------
-test('transitionGuidance terminal→resident says it is never forced to submit a final', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'terminal' });
-    const g = transitionGuidance(meta.node_id, { mode: 'base', lifecycle: 'terminal' }, { mode: 'base', lifecycle: 'resident' });
-    assert.match(g, /resident/i);
-    assert.match(g, /never/i);
-    assert.doesNotMatch(g, /orchestrator/i, 'a lifecycle-only change carries no mode section');
-});
-test('transitionGuidance resident→terminal says it owes a final up the spine', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'resident' });
-    const g = transitionGuidance(meta.node_id, { mode: 'base', lifecycle: 'resident' }, { mode: 'base', lifecycle: 'terminal' });
-    assert.match(g, /terminal/i);
-    assert.match(g, /push final/i);
-});
-test('transitionGuidance concatenates BOTH sections when both axes change', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'terminal' });
-    promote(meta.node_id); // ensure roadmap/memory seeded for the orchestrator section
-    const g = transitionGuidance(meta.node_id, { mode: 'base', lifecycle: 'terminal' }, { mode: 'orchestrator', lifecycle: 'resident' });
-    assert.match(g, /orchestrator/i, 'carries the mode (base→orchestrator) section');
-    assert.match(g, /resident/i, 'carries the lifecycle (terminal→resident) section');
-});

package/dist/core/__tests__/unknown-path.test.d.ts

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

package/dist/core/__tests__/unknown-path.test.js

@@ -1,58 +0,0 @@
-// Regression tests for unknown-subcommand error recovery hints.
-// Run with: node --import tsx/esm --test src/core/__tests__/unknown-path.test.ts
-//
-// The `next` road sign must name a command that actually exists: the FULL path
-// to the deepest matched node, not just its local name. A prior bug emitted
-// `crtr inspect -h` (dropping the `pkg` parent) when `crtr pkg inspect bogus` was
-// invoked, sending the caller to a nonexistent top-level command.
-import { test, describe } from 'node:test';
-import assert from 'node:assert/strict';
-import { defineRoot, defineBranch, defineLeaf, walk, unknownPathError } from '../command.js';
-const leaf = defineLeaf({
-    name: 'search',
-    description: 'search',
-    whenToUse: 'x',
-    help: { name: 'search', summary: 'search', output: [], outputKind: 'object', effects: ['None. Read-only.'] },
-    run: async () => ({}),
-});
-const inspectBranch = defineBranch({
-    name: 'inspect',
-    description: 'inspect',
-    whenToUse: 'x',
-    help: { name: 'inspect', summary: 'inspect' },
-    children: [leaf],
-});
-const pkgBranch = defineBranch({
-    name: 'pkg',
-    description: 'pkg',
-    whenToUse: 'x',
-    help: { name: 'pkg', summary: 'pkg' },
-    rootEntry: { concept: 'pkg', desc: 'pkg', useWhen: 'x' },
-    children: [inspectBranch],
-});
-const root = defineRoot({
-    tagline: 'test runtime',
-    globals: [],
-    subtrees: [pkgBranch],
-});
-function nextHint(...tokens) {
-    const { node, path, remaining } = walk(root, tokens);
-    const err = unknownPathError(node, path, remaining[0]);
-    return err.details.next;
-}
-describe('unknown-path error: recovery hint names the full valid path', () => {
-    test('root-level unknown points at `crtr -h`', () => {
-        assert.match(nextHint('bogus'), /Run `crtr -h`/);
-    });
-    test('one-level unknown points at `crtr pkg -h`', () => {
-        assert.match(nextHint('pkg', 'bogus'), /Run `crtr pkg -h`/);
-    });
-    test('two-level unknown points at `crtr pkg inspect -h`, not `crtr inspect -h`', () => {
-        const hint = nextHint('pkg', 'inspect', 'bogus');
-        assert.match(hint, /Run `crtr pkg inspect -h`/);
-        assert.doesNotMatch(hint, /Run `crtr inspect -h`/);
-    });
-    test('valid children of the matched node are listed', () => {
-        assert.match(nextHint('pkg', 'inspect', 'bogus'), /Valid children: search\./);
-    });
-});

package/dist/core/canvas/wakeups.d.ts

@@ -1,76 +0,0 @@
-import type { ArmWakeSpec, Wakeup } from './types.js';
-/** A thrown integrity-backstop error from armWake. `code` is the AC-N3 code the
- *  command surface (the ONLY sanctioned caller of armWake) maps to a rendered
- *  error block — armWake carries integrity backstops only (empty body / recur-on-
- *  deadline / unknown kind); target-resolvability + recoverable-state + the
- *  per-owner cap live in the surface (Min-6), so a non-surface armer could insert
- *  a dangling wake — every armer MUST route through the surface. */
-export declare class WakeArmError extends Error {
-    readonly code: string;
-    constructor(code: string, message: string);
-}
-/** Which wakes a listWakes call returns. Distinguished by which key is present
- *  (mirrors listNodes' filter shape):
- *   - { node }    — wakes anchored to this node (node_id = ?).
- *   - { owner }   — wakes this node ARMED (owner_id = ?); the per-owner cap count.
- *   - { subtree } — wakes anchored to any node in this id set (node_id IN (…)).
- *   - { due }     — wakes whose fire_at <= this ISO instant.
- *   - { canvas }  — every wake on the canvas. */
-export type WakeScope = {
-    node: string;
-} | {
-    owner: string;
-} | {
-    subtree: string[];
-} | {
-    due: string;
-} | {
-    canvas: true;
-};
-/** INSERT one wakeup row from the pinned spec, returning its (caller-supplied)
- *  `wakeup_id`. JSON.stringifies the typed `payload` union into the TEXT column
- *  and stamps `created`.
- *
- *  Deadline upsert (design Q3, "≤1 deadline per node"): for `kind === 'deadline'`
- *  the node's existing deadline is canceled first, then the new one inserted — the
- *  partial unique index `idx_wakeups_deadline` is the schema-level backstop.
- *
- *  Integrity backstops (throw WakeArmError; the surface maps the code to AC-N3):
- *   - empty/whitespace note `body` for `noted`/`deadline` → `empty_note`.
- *   - non-NULL `recur` on a `deadline`                    → `deadline_cannot_recur`.
- *   - unknown `kind`                                      → `bad_kind`.
- *  NO target-resolvability / recoverable-state / cap backstop here (Min-6). */
-export declare function armWake(spec: ArmWakeSpec): string;
-/** UPDATE the next fire time — recurrence advancement (the daemon settles a
- *  recurring row to its next slot BEFORE enacting, crash-safe; design D4). */
-export declare function advanceWake(wakeup_id: string, nextFireIso: string): void;
-/** DELETE one wakeup by id — one-shot consumption (the daemon settles a one-shot
- *  row BEFORE enacting, crash-safe; design D4). */
-export declare function consumeWake(wakeup_id: string): void;
-/** DELETE one wakeup by id — the explicit user/surface cancel. Idempotent:
- *  0 rows ⇒ no error (AC-C2). */
-export declare function cancelWake(wakeup_id: string): void;
-/** DELETE every wake anchored to this node AND every detached wake it ARMED —
- *  deliberate close/reap (ruling A). Hooked at transition('cancel'). */
-export declare function cancelWakesFor(node_id: string): void;
-/** DELETE this node's one-shot self-alarms (recur IS NULL); node-anchored crons
- *  SURVIVE — finalize is the instance finishing, not a teardown of standing
- *  schedules (design Q1). Hooked at transition('finalize'). */
-export declare function cancelSelfAlarms(node_id: string): void;
-/** DELETE this node's pending deadline(s) — cancel-on-wake (design §6.4).
- *  Hooked at reviveNode, so the deadline always belongs to the dormancy left. */
-export declare function cancelDeadlinesFor(node_id: string): void;
-/** The daemon's per-tick due query: every row whose fire_at has arrived, in
- *  fire_at order, with `payload` parsed into the typed union. Returns exactly ONE
- *  row per recurring wake regardless of missed slots — coalescing is structural
- *  (AC-E2). */
-export declare function dueWakes(nowIso: string): Wakeup[];
-/** List wakes for a scope (node / owner / subtree / due / canvas), `payload`
- *  parsed as in dueWakes. The subtree variant binds the id set with `?`
- *  placeholders (mirroring listNodes — the codebase's one safe dynamic-IN spot);
- *  ids are NEVER string-concatenated (Min-10). */
-export declare function listWakes(scope: WakeScope): Wakeup[];
-/** True if the node has ANY pending self-anchored wake (of any kind). Consumed by
- *  the stop-guard self-wake seam so a no-child poll node releases dormant after
- *  arming instead of being nagged to finish (AC-X3/AC-R1). */
-export declare function hasPendingSelfWake(node_id: string): boolean;