@crouton-kit/crouter 0.3.14 → 0.3.16

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

@@ -0,0 +1,185 @@
+// Phase 2 keystone — runtime authority moved into the WAL'd row.
+//
+// These four guard the load-bearing invariants of the split:
+//   1. concurrency  — two writers of DIFFERENT runtime fields both land (the old
+//                     whole-meta read-modify-write dropped one).
+//   2. isolation    — a single-column setter never disturbs the other runtime
+//                     fields (single-statement atomicity).
+//   3. persistence  — meta.json on disk holds NO runtime fields, yet getNode
+//                     still returns them (hydrated from the row).
+//   4. backfill     — a v2-shaped db with runtime still in meta migrates (v3) so
+//                     runtime lands in the authoritative row.
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, readFileSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { createNode, getNode, setStatus, setIntent, setPresence, recordPid, clearPid, } from '../canvas/canvas.js';
+import { openDb, closeDb, MIGRATIONS } from '../canvas/db.js';
+import { nodeDir, nodeMetaPath, 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,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-keystone-'));
+    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'];
+});
+// 1. concurrency — both interleaved writers survive.
+test('concurrency: an interleaved setStatus and recordPid both land', () => {
+    createNode(node('a', { status: 'active', pi_pid: null }));
+    // Two writers each take a STALE snapshot, exactly as the old cross-process
+    // race did (the daemon stamping pi_pid while the node flips status).
+    const snapDaemon = getNode('a');
+    const snapNode = getNode('a');
+    assert.equal(snapDaemon?.pi_pid ?? null, null);
+    assert.equal(snapNode?.status, 'active');
+    // Interleave their writes through the atomic per-column setters.
+    recordPid('a', 4321); // writer 1 (daemon)
+    setStatus('a', 'idle'); // writer 2 (node)
+    // Under the OLD whole-meta read-modify-write, writer 2 writing back its stale
+    // snapshot (pi_pid still null) would have CLOBBERED writer 1's pid. Atomic
+    // single-column UPDATEs serialized by WAL keep BOTH.
+    const m = getNode('a');
+    assert.equal(m?.pi_pid, 4321, 'the pid write survived');
+    assert.equal(m?.status, 'idle', 'the status write survived');
+});
+// 2. isolation — single-column atomicity in both directions.
+test('isolation: setPresence and setStatus/setIntent never disturb each other', () => {
+    createNode(node('a', { status: 'active', intent: 'refresh', pi_pid: 99 }));
+    setPresence('a', { tmux_session: 's', window: '@1' });
+    let m = getNode('a');
+    assert.equal(m?.status, 'active', 'status undisturbed by setPresence');
+    assert.equal(m?.intent, 'refresh', 'intent undisturbed by setPresence');
+    assert.equal(m?.pi_pid, 99, 'pi_pid undisturbed by setPresence');
+    assert.equal(m?.tmux_session, 's');
+    assert.equal(m?.window, '@1');
+    // The reverse: flipping status + intent leaves presence and pid intact.
+    setStatus('a', 'done');
+    setIntent('a', 'done');
+    m = getNode('a');
+    assert.equal(m?.status, 'done');
+    assert.equal(m?.intent, 'done');
+    assert.equal(m?.tmux_session, 's', 'tmux_session undisturbed by setStatus/setIntent');
+    assert.equal(m?.window, '@1', 'window undisturbed by setStatus/setIntent');
+    assert.equal(m?.pi_pid, 99, 'pi_pid undisturbed by setStatus/setIntent');
+    clearPid('a');
+    assert.equal(getNode('a')?.pi_pid, null, 'clearPid nulls only the pid');
+    assert.equal(getNode('a')?.tmux_session, 's', 'clearPid leaves presence intact');
+});
+// 3. persistence-split — meta.json has no runtime; getNode still hydrates it.
+test('persistence-split: meta.json holds no runtime fields, getNode hydrates them', () => {
+    createNode(node('a', {
+        status: 'active',
+        intent: 'refresh',
+        pi_pid: 7,
+        tmux_session: 's',
+        window: '@1',
+    }));
+    setStatus('a', 'done');
+    setPresence('a', { tmux_session: 's2', window: '@2' });
+    const raw = JSON.parse(readFileSync(nodeMetaPath('a'), 'utf8'));
+    for (const k of ['status', 'intent', 'pi_pid', 'window', 'tmux_session']) {
+        assert.ok(!(k in raw), `meta.json must NOT contain runtime field "${k}"`);
+    }
+    // identity is still on disk
+    assert.equal(raw['kind'], 'general');
+    assert.equal(raw['node_id'], 'a');
+    // ...while the hydrated view returns runtime from the authoritative row.
+    const m = getNode('a');
+    assert.equal(m?.status, 'done');
+    assert.equal(m?.tmux_session, 's2');
+    assert.equal(m?.window, '@2');
+    assert.equal(m?.intent, 'refresh');
+    assert.equal(m?.pi_pid, 7);
+});
+// 4. backfill — v2-shaped db with runtime in meta migrates so runtime lands in
+// the row.
+test('backfill (v3): runtime in legacy meta.json is copied into the row', () => {
+    ensureHome();
+    // A legacy meta with runtime STILL on disk (pre-keystone shape).
+    mkdirSync(nodeDir('n1'), { recursive: true });
+    writeFileSync(nodeMetaPath('n1'), JSON.stringify({
+        node_id: 'n1',
+        name: 'N1',
+        created: '2020-01-01T00:00:00Z',
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        // legacy runtime, still living in meta.json:
+        status: 'idle',
+        intent: 'refresh',
+        pi_pid: 555,
+        window: '@9',
+        tmux_session: 'sess',
+    }, null, 2));
+    // Hand-build a v2-shaped db: all columns present, runtime seeded NULL,
+    // user_version 2 (so the runner runs ONLY v3 = backfill).
+    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
+    );
+  `);
+    raw
+        .prepare('INSERT INTO nodes (node_id, name, kind, mode, lifecycle, status, cwd, parent, created) VALUES (?,?,?,?,?,?,?,?,?)')
+        .run('n1', 'N1', 'general', 'base', 'terminal', 'idle', '/tmp/work', null, '2020-01-01T00:00:00Z');
+    raw.exec('PRAGMA user_version = 2;');
+    // Precondition: runtime columns are NULL before the backfill.
+    const before = raw
+        .prepare('SELECT intent, pi_pid, "window", tmux_session FROM nodes WHERE node_id = ?')
+        .get('n1');
+    assert.equal(before['intent'], null);
+    assert.equal(before['pi_pid'], null);
+    raw.close();
+    // openDb() runs the migration runner forward → v3 backfill copies meta→row.
+    const db = openDb();
+    assert.equal(db.prepare('PRAGMA user_version').get().user_version, MIGRATIONS.length);
+    const r = db
+        .prepare('SELECT status, intent, pi_pid, "window", tmux_session FROM nodes WHERE node_id = ?')
+        .get('n1');
+    assert.equal(r['status'], 'idle', 'status already mirrored — untouched');
+    assert.equal(r['intent'], 'refresh', 'intent backfilled from meta');
+    assert.equal(r['pi_pid'], 555, 'pi_pid backfilled from meta');
+    assert.equal(r['window'], '@9', 'window backfilled from meta');
+    assert.equal(r['tmux_session'], 'sess', 'tmux_session backfilled from meta');
+    // And the hydrated view now reflects it.
+    const m = getNode('n1');
+    assert.equal(m?.intent, 'refresh');
+    assert.equal(m?.pi_pid, 555);
+    assert.equal(m?.window, '@9');
+    assert.equal(m?.tmux_session, 'sess');
+});

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

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

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

@@ -0,0 +1,89 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/kickoff.test.ts
+//
+// The fresh-revive kickoff split (runtime/kickoff.ts). drainBearings is the ONE
+// consuming step (consume the yield note, advance the feed cursor); after it,
+// buildReviveKickoff is a PURE string assembler — calling it twice produces the
+// same string and mutates NOTHING (note stays gone, cursor stays put). This is
+// the regression guard for the old "build had hidden side effects" smell.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, subscribe } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { drainBearings, buildReviveKickoff, writeYieldMessage, yieldMessagePath, } from '../runtime/kickoff.js';
+import { appendInbox, readCursor } from '../feed/inbox.js';
+let home;
+function node(id) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-kickoff-'));
+    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'];
+});
+test('drainBearings consumes the yield note + advances the cursor exactly once', () => {
+    const id = 'n1';
+    const meta = createNode(node(id));
+    writeYieldMessage(id, 'on wake, finish step 3');
+    appendInbox(id, { from: 'w1', tier: 'normal', kind: 'update', label: 'first', ref: '/tmp/a.md' });
+    const last = appendInbox(id, { from: 'w1', tier: 'normal', kind: 'update', label: 'second', ref: '/tmp/b.md' });
+    // First drain: captures the note + digests the unread feed.
+    const b1 = drainBearings(meta);
+    assert.equal(b1.yieldMsg?.trim(), 'on wake, finish step 3');
+    assert.ok(b1.unreadDigest !== null && b1.unreadDigest.length > 0);
+    assert.equal(existsSync(yieldMessagePath(id)), false, 'yield note deleted on read');
+    assert.equal(readCursor(id), last.ts, 'cursor advanced to the last unread entry');
+    // Second drain: the note is gone and the cursor is past the feed → nothing left.
+    const b2 = drainBearings(meta);
+    assert.equal(b2.yieldMsg, null);
+    assert.equal(b2.unreadDigest, null);
+});
+test('the feed block frames awaiting workers as alive + auto-waking, so a fresh revive has no reason to peek', () => {
+    const parent = createNode(node('p1'));
+    const child = createNode(node('c1')); // status 'active' by default
+    subscribe(parent.node_id, child.node_id); // parent awaits child
+    const msg = buildReviveKickoff(parent, drainBearings(parent));
+    // The roster names the live child...
+    assert.ok(msg.includes(child.node_id), 'awaiting roster lists the live child');
+    // ...and asserts aliveness + the automatic wake at the source, so the node
+    // does not burn a turn confirming with `feed read`/`feed peek`.
+    assert.ok(/alive and running/.test(msg), 'states the worker is alive and running');
+    assert.ok(/wake you the moment/.test(msg), 'states the wake is automatic on push');
+    assert.ok(/still working, not stalled/.test(msg), 'frames the empty feed as expected, not a problem');
+});
+test('buildReviveKickoff is pure — building twice eats nothing', () => {
+    const id = 'n2';
+    const meta = createNode(node(id));
+    writeYieldMessage(id, 'remember the invariant');
+    const last = appendInbox(id, { from: 'w', tier: 'normal', kind: 'update', label: 'r', ref: '/tmp/r.md' });
+    // Drain once (the consuming step), then build twice off the same bearings.
+    const bearings = drainBearings(meta);
+    const cursorAfterDrain = readCursor(id);
+    assert.equal(cursorAfterDrain, last.ts);
+    const s1 = buildReviveKickoff(meta, bearings);
+    const s2 = buildReviveKickoff(meta, bearings);
+    // Identical output, and the build mutated nothing: cursor unchanged, note gone.
+    assert.equal(s1, s2);
+    assert.ok(s1.includes('remember the invariant'), 'yield note surfaced in the message');
+    assert.equal(readCursor(id), cursorAfterDrain, 'build does not touch the cursor');
+    assert.equal(existsSync(yieldMessagePath(id)), false, 'build does not resurrect the note');
+});

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

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

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

@@ -0,0 +1,178 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/lifecycle.test.ts
+//
+// The status×intent state machine (runtime/lifecycle.ts). Every LEGAL event
+// from every valid from-status lands the documented (status, intent), and every
+// ILLEGAL move throws — illegal states are unrepresentable. This IS the old
+// markCleanExitDone guard + the dozen scattered setStatus/setIntent pairs, now
+// table-driven. All assertions read back through getNode() (the hydrated view).
+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 { createNode, getNode, setStatus, setIntent } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { transition } from '../runtime/lifecycle.js';
+let home;
+function node(id) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+}
+/** Create a node forced into a precise (status, intent) start state. */
+function mk(id, status, intent = null) {
+    createNode(node(id));
+    setStatus(id, status);
+    setIntent(id, intent);
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-lifecycle-'));
+    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'];
+});
+const ALL = ['active', 'idle', 'done', 'dead', 'canceled'];
+const LIVE = ['active', 'idle'];
+const TERMINAL = ['done', 'dead', 'canceled'];
+// ---------------------------------------------------------------------------
+// finalize → done + intent='done', legal only from active|idle
+// ---------------------------------------------------------------------------
+test('finalize: active|idle → done + intent=done', () => {
+    for (const from of LIVE) {
+        mk(`n_${from}`, from, 'refresh');
+        const m = transition(`n_${from}`, 'finalize');
+        assert.equal(m.status, 'done', `finalize from ${from}`);
+        assert.equal(m.intent, 'done', `finalize from ${from} sets intent=done`);
+    }
+});
+test('finalize: illegal from done|dead|canceled → throws, status untouched', () => {
+    for (const from of TERMINAL) {
+        mk(`n_${from}`, from);
+        assert.throws(() => transition(`n_${from}`, 'finalize'), /illegal lifecycle transition/);
+        assert.equal(getNode(`n_${from}`)?.status, from, `${from} unchanged on illegal finalize`);
+    }
+});
+// ---------------------------------------------------------------------------
+// reap → done + intent cleared, legal from ANY status (forced teardown)
+// ---------------------------------------------------------------------------
+test('reap: any status → done + intent cleared', () => {
+    for (const from of ALL) {
+        mk(`n_${from}`, from, 'refresh');
+        const m = transition(`n_${from}`, 'reap');
+        assert.equal(m.status, 'done', `reap from ${from}`);
+        assert.equal(m.intent, null, `reap from ${from} clears intent`);
+    }
+});
+// ---------------------------------------------------------------------------
+// cancel → canceled + intent cleared, legal from ANY status
+// ---------------------------------------------------------------------------
+test('cancel: any status → canceled + intent cleared', () => {
+    for (const from of ALL) {
+        mk(`n_${from}`, from, 'idle-release');
+        const m = transition(`n_${from}`, 'cancel');
+        assert.equal(m.status, 'canceled', `cancel from ${from}`);
+        assert.equal(m.intent, null, `cancel from ${from} clears intent`);
+    }
+});
+// ---------------------------------------------------------------------------
+// crash → dead, intent UNCHANGED, legal only from active|idle
+// ---------------------------------------------------------------------------
+test('crash: active|idle → dead, intent preserved', () => {
+    for (const from of LIVE) {
+        mk(`n_${from}`, from, 'refresh');
+        const m = transition(`n_${from}`, 'crash');
+        assert.equal(m.status, 'dead', `crash from ${from}`);
+        assert.equal(m.intent, 'refresh', `crash from ${from} leaves intent untouched`);
+    }
+});
+test('crash: illegal from done|dead|canceled → throws', () => {
+    for (const from of TERMINAL) {
+        mk(`n_${from}`, from);
+        assert.throws(() => transition(`n_${from}`, 'crash'), /illegal lifecycle transition/);
+    }
+});
+// ---------------------------------------------------------------------------
+// yield → intent='refresh', status UNCHANGED, legal only from active|idle
+// ---------------------------------------------------------------------------
+test('yield: active|idle → intent=refresh, status preserved', () => {
+    for (const from of LIVE) {
+        mk(`n_${from}`, from);
+        const m = transition(`n_${from}`, 'yield');
+        assert.equal(m.status, from, `yield from ${from} keeps status`);
+        assert.equal(m.intent, 'refresh', `yield from ${from} sets intent=refresh`);
+    }
+});
+test('yield: illegal from done|dead|canceled → throws', () => {
+    for (const from of TERMINAL) {
+        mk(`n_${from}`, from);
+        assert.throws(() => transition(`n_${from}`, 'yield'), /illegal lifecycle transition/);
+    }
+});
+// ---------------------------------------------------------------------------
+// release → idle + intent='idle-release', legal only from active|idle
+// ---------------------------------------------------------------------------
+test('release: active|idle → idle + intent=idle-release', () => {
+    for (const from of LIVE) {
+        mk(`n_${from}`, from);
+        const m = transition(`n_${from}`, 'release');
+        assert.equal(m.status, 'idle', `release from ${from}`);
+        assert.equal(m.intent, 'idle-release', `release from ${from} sets intent=idle-release`);
+    }
+});
+test('release: illegal from done|dead|canceled → throws', () => {
+    for (const from of TERMINAL) {
+        mk(`n_${from}`, from);
+        assert.throws(() => transition(`n_${from}`, 'release'), /illegal lifecycle transition/);
+    }
+});
+// ---------------------------------------------------------------------------
+// revive → active + intent cleared, legal from ANY status (the universal "back")
+// ---------------------------------------------------------------------------
+test('revive: any status → active + intent cleared', () => {
+    for (const from of ALL) {
+        mk(`n_${from}`, from, 'idle-release');
+        const m = transition(`n_${from}`, 'revive');
+        assert.equal(m.status, 'active', `revive from ${from}`);
+        assert.equal(m.intent, null, `revive from ${from} clears intent`);
+    }
+});
+// ---------------------------------------------------------------------------
+// boot → active, intent UNCHANGED (reviveInPlace keeps the refresh safety net),
+// legal only from active|idle
+// ---------------------------------------------------------------------------
+test('boot: active|idle → active, intent preserved (refresh net survives)', () => {
+    for (const from of LIVE) {
+        mk(`n_${from}`, from, 'refresh');
+        const m = transition(`n_${from}`, 'boot');
+        assert.equal(m.status, 'active', `boot from ${from}`);
+        assert.equal(m.intent, 'refresh', `boot from ${from} keeps intent (proof-of-boot net)`);
+    }
+});
+test('boot: illegal from done|dead|canceled → throws', () => {
+    for (const from of TERMINAL) {
+        mk(`n_${from}`, from);
+        assert.throws(() => transition(`n_${from}`, 'boot'), /illegal lifecycle transition/);
+    }
+});
+// ---------------------------------------------------------------------------
+// unknown node → throws for every event
+// ---------------------------------------------------------------------------
+test('transition on an unknown node throws', () => {
+    for (const ev of ['finalize', 'reap', 'cancel', 'crash', 'yield', 'release', 'revive', 'boot']) {
+        assert.throws(() => transition('ghost', ev), /unknown node/);
+    }
+});

package/dist/core/__tests__/listing-completeness.test.d.ts

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

package/dist/core/__tests__/listing-completeness.test.js

@@ -0,0 +1,31 @@
+// Completeness guard for the assembled parent-level listings.
+// Run with: node --import tsx/esm --test src/core/__tests__/listing-completeness.test.ts
+//
+// Each non-hidden child surfaced in a branch's `help.listing` must carry a real
+// self-description: both `description` and `whenToUse` non-empty. The listing is
+// assembled by defineBranch from the child defs, so a blank attribute here means
+// a child def forgot to declare its description/whenToUse. Walks the whole live
+// command tree (buildRoot) so every shipped subtree is covered.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildRoot } from '../../build-root.js';
+test('every non-hidden listing child declares description + whenToUse', () => {
+    const root = buildRoot();
+    const missing = [];
+    const walk = (branch, path) => {
+        for (const child of branch.help.listing ?? []) {
+            if (child.tier === 'hidden')
+                continue;
+            if (child.description.trim() === '' || child.whenToUse.trim() === '') {
+                missing.push(`${path} ${child.name}: empty description/whenToUse`);
+            }
+        }
+        for (const child of branch.children) {
+            if (child.kind === 'branch')
+                walk(child, `${path} ${child.name}`);
+        }
+    };
+    for (const subtree of root.subtrees)
+        walk(subtree, subtree.name);
+    assert.deepEqual(missing, [], `listing children missing self-description:\n${missing.join('\n')}`);
+});

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

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

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

@@ -0,0 +1,152 @@
+// Tests for the three-tier scoped memory (src/core/runtime/memory.ts):
+//   1. The three store paths land under crtrHome (user-global / project / node).
+//   2. projectKey resolves the git-repo-root (walk up for .git), and falls back
+//      to the cwd itself when not inside a repo.
+//   3. seed* are guarded/idempotent (never clobber an evolved index).
+//   4. promote() seeds ALL THREE stores, guarded across re-promotion.
+//   5. The kernel + promotion guidance name the type\u2192store mapping.
+//
+// CRTR_HOME isolation, like context-intro.test.ts.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/memory.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 { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb } from '../canvas/db.js';
+import { crtrHome } from '../canvas/paths.js';
+import { mangleCwd } from '../artifact.js';
+import { spawnNode } from '../runtime/nodes.js';
+import { promote } from '../runtime/promote.js';
+import { personaDrift } from '../runtime/persona.js';
+import { loadKernel } from '../personas/index.js';
+import { memoryDir, memoryPath, userMemoryDir, userMemoryPath, hasUserMemory, readUserMemory, seedUserMemory, projectKey, projectMemoryDir, projectMemoryPath, hasProjectMemory, readProjectMemory, seedProjectMemory, hasMemory, USER_MEMORY_TEMPLATE, PROJECT_MEMORY_TEMPLATE, } from '../runtime/memory.js';
+let home;
+// Scratch repos created per-test for the git-root keying cases; tracked so they
+// can be removed in `after` regardless of which test created them.
+const scratch = [];
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-memory-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    for (const d of scratch)
+        rmSync(d, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+// ---------------------------------------------------------------------------
+// Store paths
+// ---------------------------------------------------------------------------
+test('the three stores all live under crtrHome, at their scoped paths', () => {
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
+    // user-global: <crtrHome>/memory/
+    assert.equal(userMemoryDir(), join(crtrHome(), 'memory'));
+    assert.equal(userMemoryPath(), join(crtrHome(), 'memory', 'MEMORY.md'));
+    // project: <crtrHome>/projects/<key>/memory/
+    assert.equal(projectMemoryDir('/tmp/work'), join(crtrHome(), 'projects', projectKey('/tmp/work'), 'memory'));
+    assert.equal(projectMemoryPath('/tmp/work'), join(projectMemoryDir('/tmp/work'), 'MEMORY.md'));
+    // node-local: <crtrHome>/nodes/<id>/context/memory/ (unchanged)
+    assert.ok(memoryDir(meta.node_id).startsWith(join(crtrHome(), 'nodes', meta.node_id)));
+    assert.ok(memoryPath(meta.node_id).endsWith('/context/memory/MEMORY.md'));
+});
+// ---------------------------------------------------------------------------
+// projectKey: git-root vs not-in-a-repo fallback
+// ---------------------------------------------------------------------------
+test('projectKey resolves the git-repo-root by walking up for a .git entry', () => {
+    const repo = mkdtempSync(join(tmpdir(), 'crtr-repo-'));
+    scratch.push(repo);
+    mkdirSync(join(repo, '.git')); // a .git directory marks the repo root
+    const nested = join(repo, 'pkg', 'src');
+    mkdirSync(nested, { recursive: true });
+    // A cwd deep inside the repo keys to the repo ROOT, not the cwd.
+    assert.equal(projectKey(nested), mangleCwd(repo));
+    assert.equal(projectKey(repo), mangleCwd(repo));
+    // A .git FILE (worktree/submodule) is recognized the same way.
+    const wt = mkdtempSync(join(tmpdir(), 'crtr-wt-'));
+    scratch.push(wt);
+    writeFileSync(join(wt, '.git'), 'gitdir: /elsewhere\n');
+    assert.equal(projectKey(join(wt, 'a')), mangleCwd(wt));
+});
+test('projectKey falls back to the mangled cwd when not inside a repo', () => {
+    const bare = mkdtempSync(join(tmpdir(), 'crtr-bare-'));
+    scratch.push(bare);
+    const sub = join(bare, 'x', 'y');
+    mkdirSync(sub, { recursive: true });
+    // No .git anywhere up the tree \u2192 the cwd itself is the key.
+    assert.equal(projectKey(sub), mangleCwd(sub));
+});
+// ---------------------------------------------------------------------------
+// seed*: guarded / idempotent
+// ---------------------------------------------------------------------------
+test('seedUserMemory / seedProjectMemory write the template once, then never clobber', () => {
+    assert.equal(hasUserMemory(), false);
+    assert.equal(seedUserMemory(), true, 'first seed writes');
+    assert.equal(readUserMemory(), USER_MEMORY_TEMPLATE);
+    assert.equal(hasUserMemory(), true);
+    const evolved = '# Memory\n\n- [Likes terse replies](terse.md) \u2014 keep it short\n';
+    writeFileSync(userMemoryPath(), evolved);
+    assert.equal(seedUserMemory(), false, 'second seed is a no-op');
+    assert.equal(readUserMemory(), evolved, 'evolved index left untouched');
+    assert.equal(seedProjectMemory('/tmp/work'), true, 'project first seed writes');
+    assert.equal(readProjectMemory('/tmp/work'), PROJECT_MEMORY_TEMPLATE);
+    assert.equal(seedProjectMemory('/tmp/work'), false, 'project second seed is a no-op');
+});
+// ---------------------------------------------------------------------------
+// promote(): seeds all three, guarded across re-promotion
+// ---------------------------------------------------------------------------
+test('promote() seeds all three stores and surfaces all three paths', () => {
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
+    assert.equal(hasMemory(meta.node_id), false);
+    assert.equal(hasUserMemory(), false);
+    assert.equal(hasProjectMemory('/tmp/work'), false);
+    const res = promote(meta.node_id);
+    assert.ok(hasMemory(meta.node_id), 'node-local seeded');
+    assert.ok(hasUserMemory(), 'user-global seeded');
+    assert.ok(hasProjectMemory('/tmp/work'), 'project seeded');
+    assert.ok(existsSync(userMemoryDir()), 'user dir created for direct writes');
+    assert.ok(existsSync(projectMemoryDir('/tmp/work')), 'project dir created for direct writes');
+    assert.equal(res.memoryPath, memoryPath(meta.node_id));
+    assert.equal(res.userMemoryPath, userMemoryPath());
+    assert.equal(res.projectMemoryPath, projectMemoryPath('/tmp/work'));
+});
+test('promote() is idempotent across re-promotion \u2014 never clobbers evolved stores', () => {
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
+    promote(meta.node_id);
+    const evolvedUser = '# Memory\n\n- [CTO, terse](cto.md) \u2014 senior, wants density\n';
+    const evolvedProject = '# Memory\n\n- [ESM only](esm.md) \u2014 .js extensions required\n';
+    writeFileSync(userMemoryPath(), evolvedUser);
+    writeFileSync(projectMemoryPath('/tmp/work'), evolvedProject);
+    promote(meta.node_id); // re-promote
+    assert.equal(readUserMemory(), evolvedUser, 'user store survived re-promotion');
+    assert.equal(readProjectMemory('/tmp/work'), evolvedProject, 'project store survived re-promotion');
+});
+// ---------------------------------------------------------------------------
+// The kernel + guidance name the type\u2192store mapping
+// ---------------------------------------------------------------------------
+test('the orchestration kernel names the three stores and the type\u2192store mapping', () => {
+    const kernel = loadKernel();
+    for (const store of ['user-global', 'project', 'node-local']) {
+        assert.ok(kernel.includes(store), `kernel names the ${store} store`);
+    }
+    // The type taxonomy still drives placement.
+    assert.match(kernel, /`type`/, 'kernel still frames the type taxonomy');
+    assert.match(kernel, /user.*\u2192.*user-global|`user` \u2192 user-global/, 'maps user \u2192 user-global');
+});
+test('promotion guidance names all three stores so a base-spawned node learns where to write', () => {
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
+    promote(meta.node_id);
+    // Guidance is now built by the persona injector, not returned by promote().
+    const guidance = personaDrift(meta.node_id)?.guidance ?? '';
+    for (const store of ['user-global', 'project', 'node-local']) {
+        assert.ok(guidance.includes(store), `guidance names the ${store} store`);
+    }
+    assert.ok(guidance.includes(userMemoryDir()), 'guidance names the user-global dir');
+    assert.ok(guidance.includes(projectMemoryDir('/tmp/work')), 'guidance names the project dir');
+});

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

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