@crouton-kit/crouter 0.3.14 → 0.3.15

package/dist/core/canvas/canvas.js

@@ -4,37 +4,86 @@
 // Source-of-truth split: a node's meta.json is canonical for its own fields;
 // the db row is a queryable index re-derivable from it. The subscribes_to edges
 // are db-authoritative (mutable, many-writers — what WAL is for).
-import { existsSync, readFileSync, writeFileSync, renameSync, readdirSync, } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, renameSync, readdirSync, rmSync, } from 'node:fs';
 import { join } from 'node:path';
 import { openDb } from './db.js';
 import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, } from './paths.js';
 // ---------------------------------------------------------------------------
-// meta.json (source of truth)
+// meta.json (durable identity — the source of truth for what PERSISTS)
+//
+// One authoritative store per fact: meta.json holds NodeIdentity only; the six
+// runtime fields (status, intent, pi_pid, window, tmux_session, pane) are
+// authoritative in the WAL'd `nodes` row, each mutated by one atomic setter
+// below. getNode() hydrates the two back into the historical NodeMeta view.
 // ---------------------------------------------------------------------------
+/** The identity keys meta.json persists. Listed explicitly so no runtime field
+ *  can ever leak onto disk even when a fully-hydrated NodeMeta is handed in. */
+const IDENTITY_KEYS = [
+    'node_id', 'name', 'description', 'cycles', 'created', 'cwd', 'kind', 'mode',
+    'lifecycle', 'persona_ack', 'parent', 'spawned_by', 'passive_default',
+    'home_session', 'pi_session_id', 'pi_session_file', 'launch',
+];
+/** Project any node object down to its durable-identity subset. */
+function toIdentity(m) {
+    const out = {};
+    for (const k of IDENTITY_KEYS) {
+        if (m[k] !== undefined)
+            out[k] = m[k];
+    }
+    return out;
+}
 function readMeta(nodeId) {
     const p = nodeMetaPath(nodeId);
     if (!existsSync(p))
         return null;
+    // Legacy metas may still carry runtime fields on disk; toIdentity-on-read is
+    // unnecessary (callers go through getNode, which overlays the row), but the
+    // raw parse is typed as identity — extra props are ignored.
     return JSON.parse(readFileSync(p, 'utf8'));
 }
+/** Serialize ONLY the identity subset → meta.json never holds runtime fields. */
 function writeMeta(meta) {
     const p = nodeMetaPath(meta.node_id);
     const tmp = `${p}.tmp`;
-    writeFileSync(tmp, JSON.stringify(meta, null, 2));
+    writeFileSync(tmp, JSON.stringify(toIdentity(meta), null, 2));
     renameSync(tmp, p);
 }
 // ---------------------------------------------------------------------------
-// row index (derived from meta)
+// row index — identity columns are a derived projection of meta; runtime
+// columns are authoritative. The two have DIFFERENT writers: upsertRow only
+// ever touches identity (so a re-index never clobbers live runtime), while
+// createNode seeds runtime once and the atomic setters own it thereafter.
 // ---------------------------------------------------------------------------
+/** Upsert the IDENTITY columns of a node's row. ON CONFLICT updates identity
+ *  ONLY — runtime columns (status/intent/pi_pid/window/tmux_session/pane) are left
+ *  exactly as they are, so re-indexing or an identity edit never disturbs live
+ *  state. A fresh insert takes the schema defaults for runtime. */
 function upsertRow(meta) {
     openDb()
-        .prepare(`INSERT INTO nodes (node_id, name, kind, mode, lifecycle, status, cwd, parent, created)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        .prepare(`INSERT INTO nodes (node_id, name, kind, mode, lifecycle, cwd, parent, created)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(node_id) DO UPDATE SET
          name=excluded.name, kind=excluded.kind, mode=excluded.mode,
-         lifecycle=excluded.lifecycle, status=excluded.status, cwd=excluded.cwd,
-         parent=excluded.parent`)
-        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.status, meta.cwd, meta.parent ?? null, meta.created);
+         lifecycle=excluded.lifecycle, cwd=excluded.cwd, parent=excluded.parent`)
+        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.parent ?? null, meta.created);
+}
+/** Seed a node's row at BIRTH: identity columns + runtime columns taken from the
+ *  incoming meta (defaults: status='active', the rest null). The only writer
+ *  that sets runtime columns alongside identity in one statement — afterwards
+ *  the atomic setters are the sole runtime writers. */
+function seedRow(meta) {
+    openDb()
+        .prepare(`INSERT INTO nodes
+         (node_id, name, kind, mode, lifecycle, cwd, parent, created,
+          status, intent, pi_pid, "window", tmux_session, pane)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(node_id) DO UPDATE SET
+         name=excluded.name, kind=excluded.kind, mode=excluded.mode,
+         lifecycle=excluded.lifecycle, cwd=excluded.cwd, parent=excluded.parent,
+         status=excluded.status, intent=excluded.intent, pi_pid=excluded.pi_pid,
+         "window"=excluded."window", tmux_session=excluded.tmux_session,
+         pane=excluded.pane`)
+        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.parent ?? null, meta.created, meta.status ?? 'active', meta.intent ?? null, meta.pi_pid ?? null, meta.window ?? null, meta.tmux_session ?? null, meta.pane ?? null);
 }
 function rowFrom(r) {
     return {
@@ -47,22 +96,52 @@ function rowFrom(r) {
         cwd: r['cwd'],
         parent: r['parent'] ?? null,
         created: r['created'],
+        intent: r['intent'] ?? null,
+        pi_pid: r['pi_pid'] ?? null,
+        window: r['window'] ?? null,
+        tmux_session: r['tmux_session'] ?? null,
+        pane: r['pane'] ?? null,
+    };
+}
+/** The authoritative runtime fields for `nodeId`, read from its row. Null when
+ *  no row exists yet (the hydration then falls back to whatever the meta held). */
+function runtimeFromRow(nodeId) {
+    const r = openDb()
+        .prepare('SELECT status, intent, pi_pid, "window", tmux_session, pane FROM nodes WHERE node_id = ?')
+        .get(nodeId);
+    if (r === undefined)
+        return null;
+    return {
+        status: r['status'] ?? 'active',
+        intent: r['intent'] ?? null,
+        pi_pid: r['pi_pid'] ?? null,
+        window: r['window'] ?? null,
+        tmux_session: r['tmux_session'] ?? null,
+        pane: r['pane'] ?? null,
     };
 }
 // ---------------------------------------------------------------------------
 // Nodes
 // ---------------------------------------------------------------------------
-/** Create a node: scaffold its dirs, write meta.json, index the row. */
+/** Create a node: scaffold its dirs, persist identity to meta.json, and seed the
+ *  row (identity + runtime from the incoming meta). Returns the hydrated view. */
 export function createNode(meta) {
     ensureHome();
     ensureNodeDirs(meta.node_id);
     writeMeta(meta);
-    upsertRow(meta);
-    return meta;
+    seedRow(meta);
+    return getNode(meta.node_id);
 }
-/** The canonical node record (from meta.json), or null if unknown. */
+/** The canonical node record: durable identity (meta.json) ∪ authoritative
+ *  runtime (the row). Null if unknown. */
 export function getNode(nodeId) {
-    return readMeta(nodeId);
+    const ident = readMeta(nodeId);
+    if (ident === null)
+        return null;
+    const rt = runtimeFromRow(nodeId);
+    // The row is authoritative for runtime; overlay it over identity. When no row
+    // exists yet (rare — pre-rebuild), keep whatever the meta carried.
+    return { ...ident, ...(rt ?? {}) };
 }
 /** The indexed row (from the db) — cheap for queries that don't need full meta. */
 export function getRow(nodeId) {
@@ -71,7 +150,20 @@ export function getRow(nodeId) {
         .get(nodeId);
     return r ? rowFrom(r) : null;
 }
-/** Merge a patch into a node's meta.json and re-index its row. */
+/** The node row whose durable LOCATION pane is `pane`, or null. Lets placement
+ *  resolve "who sits in this pane" by the first-class `%pane_id` handle (e.g.
+ *  to adopt a caller's pane as a focus). pane is not UNIQUE in the schema, but a
+ *  live pane backs at most one node, so this returns the single match. */
+export function getRowByPane(pane) {
+    const r = openDb()
+        .prepare('SELECT * FROM nodes WHERE pane = ?')
+        .get(pane);
+    return r ? rowFrom(r) : null;
+}
+/** Merge an IDENTITY patch into a node's meta.json and re-index its identity
+ *  columns. Identity has a single writer per node, so this read-modify-write is
+ *  safe (the contended runtime fields were moved out — see the atomic setters
+ *  below). Returns the hydrated view (runtime included). */
 export function updateNode(nodeId, patch) {
     const cur = readMeta(nodeId);
     if (!cur)
@@ -79,11 +171,41 @@ export function updateNode(nodeId, patch) {
     const next = { ...cur, ...patch, node_id: cur.node_id };
     writeMeta(next);
     upsertRow(next);
-    return next;
+    return getNode(nodeId);
 }
-/** Convenience for the most common mutation. */
+// ---------------------------------------------------------------------------
+// Atomic runtime setters — each one a single-statement UPDATE on the WAL'd row,
+// the authoritative store for live state. No read-modify-write, so concurrent
+// writers of DIFFERENT fields (the daemon stamping pi_pid while a node flips
+// status) can never clobber each other: WAL serializes the two statements.
+// `"window"` is quoted defensively — it is a SQLite keyword.
+// ---------------------------------------------------------------------------
+/** Set a node's status. Atomic single-column write. */
 export function setStatus(nodeId, status) {
-    updateNode(nodeId, { status });
+    openDb().prepare('UPDATE nodes SET status = ? WHERE node_id = ?').run(status, nodeId);
+}
+/** Set a node's exit intent. Atomic single-column write. */
+export function setIntent(nodeId, intent) {
+    openDb().prepare('UPDATE nodes SET intent = ? WHERE node_id = ?').run(intent ?? null, nodeId);
+}
+/** Set a node's tmux presence in one atomic write: the durable LOCATION anchor
+ *  `pane` (the `%pane_id`) plus its derived cache (`tmux_session` + `window`).
+ *  All three move together — `pane` joins the others inside the single UPDATE so
+ *  a move never half-writes the location. `pane` is optional: a caller that does
+ *  not yet track it (every caller, until the placement layer lands) writes null,
+ *  which is harmless because nothing reads `pane` yet. */
+export function setPresence(nodeId, presence) {
+    openDb()
+        .prepare('UPDATE nodes SET tmux_session = ?, "window" = ?, pane = ? WHERE node_id = ?')
+        .run(presence.tmux_session ?? null, presence.window ?? null, presence.pane ?? null, nodeId);
+}
+/** Record the live pi pid (daemon liveness signal). Atomic single-column write. */
+export function recordPid(nodeId, pid) {
+    openDb().prepare('UPDATE nodes SET pi_pid = ? WHERE node_id = ?').run(pid, nodeId);
+}
+/** Clear the pi pid (window-backed relaunch, before the fresh pi re-records it). */
+export function clearPid(nodeId) {
+    openDb().prepare('UPDATE nodes SET pi_pid = NULL WHERE node_id = ?').run(nodeId);
 }
 /** All rows, optionally filtered by status. */
 export function listNodes(filter) {
@@ -192,19 +314,85 @@ export function hasActiveLiveSubscription(nodeId) {
 // Index rebuild
 // ---------------------------------------------------------------------------
 /** Rebuild node rows from on-disk metas (the db node table is a derived index).
+ *  Only the IDENTITY columns are rebuilt — they are a projection of meta. The
+ *  runtime columns (status/intent/pi_pid/window/tmux_session/pane) are NOT in meta
+ *  and NOT re-derivable from it: they describe live process/presence state, so
+ *  an existing row keeps them and a freshly re-created row takes the schema's
+ *  quiescent defaults (status='active', the rest null). The daemon reconciles
+ *  liveness from tmux reality, not from a stale file.
  *  Edges are left intact — subscribes_to is db-authoritative; spawned_by is
- *  re-derived from each meta's `parent`. */
+ *  re-derived from each meta's `spawned_by` (fallback: `parent` for legacy metas). */
 export function rebuildIndex() {
     if (!existsSync(nodesRoot()))
         return;
+    // Collect every on-disk meta first, then index in TWO passes. Under the
+    // edges→nodes FK (migration v4), a `spawned_by` edge insert whose endpoint
+    // row isn't present yet violates the constraint — so ALL node rows must exist
+    // before ANY edge is added.
+    const metas = [];
     for (const id of readdirSync(nodesRoot())) {
         if (!existsSync(join(nodeDir(id), 'meta.json')))
             continue;
         const meta = readMeta(id);
         if (!meta)
             continue;
+        metas.push(meta);
+    }
+    // Pass 1 — upsert every node row (the edge endpoints).
+    for (const meta of metas)
         upsertRow(meta);
-        if (meta.parent)
-            recordSpawn(meta.node_id, meta.parent);
+    // Pass 2 — add the audit-only `spawned_by` provenance edges. Skip any whose
+    // provenance node has no on-disk meta (a deleted/pruned ancestor): the FK
+    // would reject it, and an orphan provenance edge is exactly what v4 makes
+    // unrepresentable.
+    const known = new Set(metas.map((m) => m.node_id));
+    for (const meta of metas) {
+        const prov = meta.spawned_by ?? meta.parent;
+        if (prov && known.has(prov))
+            recordSpawn(meta.node_id, prov);
+    }
+}
+/** Retention sweep: remove TERMINAL nodes (status dead | done | canceled) whose
+ *  `created` is older than `ttlDays`, bounding the otherwise-unbounded growth of
+ *  node rows + dirs. The edges→nodes FK (`ON DELETE CASCADE`, migration v4) GCs
+ *  each pruned node's edges automatically; the on-disk `nodes/<id>/` dir is
+ *  removed too. Live nodes are NEVER touched: active | idle are the daemon's
+ *  domain, a DISJOINT status set, so prune and supervision can't interfere.
+ *
+ *  The row deletes run in ONE transaction (so the sweep is all-or-nothing); the
+ *  dir removals follow after COMMIT — the fs isn't transactional, and by then the
+ *  rows are gone, so a re-run never re-finds a half-deleted node. `dryRun`
+ *  reports the candidate set and deletes NOTHING. */
+export function pruneNodes(opts) {
+    const dryRun = opts.dryRun ?? false;
+    const cutoff = new Date(Date.now() - opts.ttlDays * 86_400_000).toISOString();
+    const db = openDb();
+    const candidates = db
+        .prepare(`SELECT node_id, status, created FROM nodes
+         WHERE status IN ('dead', 'done', 'canceled') AND created < ?
+         ORDER BY created`)
+        .all(cutoff).map((r) => ({
+        node_id: r['node_id'],
+        status: r['status'],
+        created: r['created'],
+    }));
+    if (dryRun || candidates.length === 0)
+        return { pruned: candidates, dryRun };
+    // One transactioned sweep — delete the rows; the FK cascades their edges.
+    db.exec('BEGIN');
+    try {
+        const del = db.prepare('DELETE FROM nodes WHERE node_id = ?');
+        for (const c of candidates)
+            del.run(c.node_id);
+        db.exec('COMMIT');
+    }
+    catch (e) {
+        db.exec('ROLLBACK');
+        throw e;
+    }
+    // Remove each pruned node's on-disk dir (best-effort, after COMMIT).
+    for (const c of candidates) {
+        rmSync(nodeDir(c.node_id), { recursive: true, force: true });
     }
+    return { pruned: candidates, dryRun };
 }

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

@@ -1,4 +1,12 @@
 import { DatabaseSync } from 'node:sqlite';
+/** The ordered migration list. Index `i` is migration version `i + 1`; the db's
+ *  `user_version` tracks how many have been applied. Append only. */
+export declare const MIGRATIONS: ReadonlyArray<(db: DatabaseSync) => void>;
+/** Bring `db` up to the latest schema version. Reads `user_version`, runs each
+ *  pending migration in order, and bumps `user_version` after each so the work
+ *  is gated and idempotent: re-running is a no-op once `user_version` reaches
+ *  `MIGRATIONS.length`. Forward-only. */
+export declare function migrate(db: DatabaseSync): void;
 /** Open (or reuse) the canvas db at the current `CRTR_HOME`, initializing the
  *  schema and WAL on first open. Keyed by path so tests with distinct homes get
  *  independent handles. */

package/dist/core/canvas/db.js

@@ -5,8 +5,19 @@
 // truth). The `subscribes_to` edges are the one genuinely-mutable part no meta
 // owns, so the db is authoritative for them.
 import { DatabaseSync } from 'node:sqlite';
-import { canvasDbPath, ensureHome } from './paths.js';
-const SCHEMA = `
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { canvasDbPath, ensureHome, nodesRoot, nodeMetaPath } from './paths.js';
+// --- Schema as a forward-only migration list ------------------------------
+//
+// The schema is the migration list: one place a schema change is expressed,
+// one gate (`PRAGMA user_version`) that applies it. `migrate()` runs every
+// pending step in order and bumps `user_version` after each, so a fresh db and
+// the live fleet (all at `user_version 0`) converge on the same final shape.
+// Migrations are append-only and forward-only — never edit a shipped step.
+/** v1 — the baseline tables + indexes. `IF NOT EXISTS` makes this a no-op on
+ *  any existing db (the live fleet already has these tables). */
+function baselineSchema(db) {
+    db.exec(`
 CREATE TABLE IF NOT EXISTS nodes (
   node_id    TEXT PRIMARY KEY,
   name       TEXT NOT NULL,
@@ -31,7 +42,196 @@ CREATE TABLE IF NOT EXISTS edges (
 CREATE INDEX IF NOT EXISTS idx_edges_to   ON edges(type, to_id);
 CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(type, from_id);
 CREATE INDEX IF NOT EXISTS idx_nodes_status ON nodes(status);
-`;
+`);
+}
+/** v2 — additive runtime columns the keystone (Phase 2) will make
+ *  authoritative: `intent, pi_pid, window, tmux_session`. `status` already
+ *  lives in the baseline row, so it is NOT re-added here. All four default to
+ *  NULL, so nothing observes a behavior change until a later phase reads them. */
+function addRuntimeColumns(db) {
+    db.exec(`ALTER TABLE nodes ADD COLUMN intent       TEXT;`);
+    db.exec(`ALTER TABLE nodes ADD COLUMN pi_pid       INTEGER;`);
+    db.exec(`ALTER TABLE nodes ADD COLUMN window       TEXT;`);
+    db.exec(`ALTER TABLE nodes ADD COLUMN tmux_session TEXT;`);
+}
+/** v3 — DATA backfill (keystone, Phase 2). The runtime fields
+ *  (`intent, pi_pid, window, tmux_session`) become authoritative in the row;
+ *  copy each existing node's values out of its meta.json into the row columns
+ *  once, so the version boundary loses no live state. `status` already mirrors
+ *  the row, so it is not re-copied.
+ *
+ *  LAYERING NOTE (explicitly sanctioned by the runtime-fix plan): a *data*
+ *  migration must read meta.json, which db.ts normally would not. Reading it
+ *  directly here — via paths.ts, a one-time, clearly-labeled boot-time data
+ *  migration — is the deliberate choice over splitting the `user_version`
+ *  counter across two modules. Idempotent and gated: it runs exactly once at the
+ *  v2→v3 boundary. An UPDATE for a node with no row yet hits 0 rows (harmless). */
+function backfillRuntime(db) {
+    const root = nodesRoot();
+    if (!existsSync(root))
+        return;
+    const upd = db.prepare('UPDATE nodes SET intent = ?, pi_pid = ?, "window" = ?, tmux_session = ? WHERE node_id = ?');
+    for (const id of readdirSync(root)) {
+        const p = nodeMetaPath(id);
+        if (!existsSync(p))
+            continue;
+        let meta;
+        try {
+            meta = JSON.parse(readFileSync(p, 'utf8'));
+        }
+        catch {
+            continue; // a single unreadable meta never aborts the migration
+        }
+        upd.run(meta['intent'] ?? null, meta['pi_pid'] ?? null, meta['window'] ?? null, meta['tmux_session'] ?? null, id);
+    }
+}
+/** v4 — edges referential integrity (IRREVERSIBLE table rebuild). Rebuild the
+ *  `edges` table so `from_id`/`to_id` are FOREIGN KEYs to `nodes(node_id)` with
+ *  `ON DELETE CASCADE`: after this, deleting a node can NEVER orphan an edge —
+ *  the schema GCs them, so prune (and any future delete) doesn't have to. The
+ *  cargo-cult `PRAGMA foreign_keys = ON` (openDb) finally enforces something.
+ *
+ *  GOTCHA — pre-existing orphan edges. Nothing ever deleted a node before this
+ *  phase, but manual dir removals / failed spawns can have left `edges` whose
+ *  endpoint has no `nodes` row. Copying those into the FK-constrained table
+ *  would violate the constraint, so the rebuild runs with `foreign_keys = OFF`
+ *  (it MUST be toggled in autocommit — a no-op inside a txn) and the
+ *  INSERT…SELECT FILTERS orphans: only edges whose BOTH endpoints have a row
+ *  survive. `PRAGMA foreign_key_check` then confirms the rebuilt table is clean,
+ *  and a row-count assertion guards that every NON-orphan edge is preserved.
+ *
+ *  CRASH-SAFETY — the whole rebuild is one transaction. A throw ROLLs it back to
+ *  the pre-v4 state (the `edges_new` scratch table and all copies vanish) and
+ *  `user_version` stays at 3, so the next open re-runs v4 cleanly: no half-state.
+ *  Even a crash between COMMIT and the version bump is safe — re-running v4 over
+ *  an already-rebuilt (clean) `edges` is idempotent in effect. */
+function edgesForeignKeyCascade(db) {
+    // Degenerate db with no `edges` table (a real db always has it — v1 created it
+    // — but a hand-seeded fixture may not). Nothing to rebuild; create the
+    // FK-shaped table fresh so the schema still converges, then we're done.
+    const hasEdges = db
+        .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'edges'")
+        .get() !== undefined;
+    if (!hasEdges) {
+        db.exec(`
+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
+);
+CREATE INDEX IF NOT EXISTS idx_edges_to   ON edges(type, to_id);
+CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(type, from_id);
+`);
+        return;
+    }
+    // FK enforcement must be toggled OUTSIDE a transaction (a no-op within one).
+    db.exec('PRAGMA foreign_keys = OFF;');
+    try {
+        // Non-orphan edges that MUST survive the rebuild (both endpoints present).
+        const expected = db
+            .prepare(`SELECT COUNT(*) AS n FROM edges
+           WHERE from_id IN (SELECT node_id FROM nodes)
+             AND to_id   IN (SELECT node_id FROM nodes)`)
+            .get().n;
+        db.exec('BEGIN');
+        try {
+            db.exec(`
+CREATE TABLE edges_new (
+  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
+);
+INSERT INTO edges_new (type, from_id, to_id, active, created)
+  SELECT type, from_id, to_id, active, created FROM edges
+  WHERE from_id IN (SELECT node_id FROM nodes)
+    AND to_id   IN (SELECT node_id FROM nodes);
+DROP TABLE edges;
+ALTER TABLE edges_new RENAME TO edges;
+CREATE INDEX IF NOT EXISTS idx_edges_to   ON edges(type, to_id);
+CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(type, from_id);
+`);
+            // Row-count assertion: every non-orphan edge preserved across the rebuild.
+            const after = db.prepare('SELECT COUNT(*) AS n FROM edges').get().n;
+            if (after !== expected) {
+                throw new Error(`edges FK rebuild lost rows: expected ${expected} non-orphan edge(s), got ${after}`);
+            }
+            // Belt-and-suspenders: the rebuilt table must hold no FK violations (the
+            // orphan filter above should guarantee this).
+            const violations = db.prepare('PRAGMA foreign_key_check').all();
+            if (violations.length > 0) {
+                throw new Error(`edges FK rebuild left ${violations.length} foreign-key violation(s)`);
+            }
+            db.exec('COMMIT');
+        }
+        catch (e) {
+            db.exec('ROLLBACK');
+            throw e;
+        }
+    }
+    finally {
+        db.exec('PRAGMA foreign_keys = ON;');
+    }
+}
+/** v5 — additive runtime column `pane`: LOCATION's authoritative handle, the
+ *  durable tmux `%pane_id` a node's pane is anchored on. Unlike the derived
+ *  `window`/`tmux_session` cache (v2), the pane id survives a user
+ *  `move-pane`/`join-pane`/`break-pane` and window renumbering, so a later step
+ *  reconciles window/session FROM it and uses pane-existence for liveness.
+ *  Defaults NULL — nothing reads it until the placement layer lands, so this
+ *  observes no behavior change. Additive, forward-only. */
+function addPaneColumn(db) {
+    db.exec(`ALTER TABLE nodes ADD COLUMN pane TEXT;`);
+}
+/** v6 — the `focuses` table: durable, PLURAL on-screen viewports, one row per
+ *  viewport (Q7 widens canvas.db from "topology" to "topology + focuses"). Each
+ *  row is anchored on the durable tmux `%pane_id`; `session` is a derived cache
+ *  reconciled from the pane; `node_id` is UNIQUE so a node occupies at most one
+ *  focus (Q5). Additive, forward-only — nothing reads it as authority yet (Step 4
+ *  populates it in lockstep with the legacy `focus.ptr` via a transitional
+ *  dual-write; the switch to table-as-authority lands in Step 6). */
+function addFocusesTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS focuses (
+  focus_id  TEXT PRIMARY KEY,   -- stable internal id for the viewport
+  pane      TEXT,               -- the durable %pane_id realizing the focus
+  session   TEXT,               -- derived cache of the user session (reconciled from pane)
+  node_id   TEXT NOT NULL UNIQUE -- the node shown; UNIQUE → a node occupies <=1 focus
+);
+`);
+}
+/** The ordered migration list. Index `i` is migration version `i + 1`; the db's
+ *  `user_version` tracks how many have been applied. Append only. */
+export const MIGRATIONS = [
+    /* v1 */ baselineSchema,
+    /* v2 */ addRuntimeColumns,
+    /* v3 */ backfillRuntime,
+    /* v4 */ edgesForeignKeyCascade,
+    /* v5 */ addPaneColumn,
+    /* v6 */ addFocusesTable,
+];
+/** Bring `db` up to the latest schema version. Reads `user_version`, runs each
+ *  pending migration in order, and bumps `user_version` after each so the work
+ *  is gated and idempotent: re-running is a no-op once `user_version` reaches
+ *  `MIGRATIONS.length`. Forward-only. */
+export function migrate(db) {
+    let v = db.prepare('PRAGMA user_version').get()
+        .user_version;
+    for (; v < MIGRATIONS.length; v++) {
+        MIGRATIONS[v](db);
+        // `user_version` takes no bound parameters; v is a controlled integer.
+        db.exec(`PRAGMA user_version = ${v + 1}`);
+    }
+}
 const handles = new Map();
 /** Open (or reuse) the canvas db at the current `CRTR_HOME`, initializing the
  *  schema and WAL on first open. Keyed by path so tests with distinct homes get
@@ -44,9 +244,11 @@ export function openDb() {
     ensureHome();
     const db = new DatabaseSync(path);
     db.exec('PRAGMA journal_mode = WAL;');
+    // Load-bearing as of migration v4: the edges→nodes FK (ON DELETE CASCADE)
+    // needs this ON at the deleting connection so a node delete reaps its edges.
     db.exec('PRAGMA foreign_keys = ON;');
     db.exec('PRAGMA busy_timeout = 5000;');
-    db.exec(SCHEMA);
+    migrate(db);
     handles.set(path, db);
     return db;
 }

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

@@ -0,0 +1,22 @@
+import type { FocusRow } from './types.js';
+/** INSERT a viewport. Throws on UNIQUE(node_id) if `node_id` already occupies
+ *  another focus (or on PK conflict if `focus_id` exists) — by design. */
+export declare function openFocusRow(focus_id: string, pane: string | null, session: string | null, node_id: string): void;
+/** Hot-swap a focus's occupant — single-statement UPDATE. Respects
+ *  UNIQUE(node_id): if `node_id` already occupies ANOTHER focus this throws
+ *  (correct — vacate-first is retargetFocus's job, Step 6, not this setter's). */
+export declare function setFocusOccupant(focus_id: string, node_id: string): void;
+/** Re-point a focus's durable pane + its derived session cache — for
+ *  reconcileFocus / the daemon (Step 6). Single-statement UPDATE. */
+export declare function setFocusPane(focus_id: string, pane: string | null, session: string | null): void;
+/** DELETE a viewport. */
+export declare function closeFocusRow(focus_id: string): void;
+/** The focus a node occupies (≤1, UNIQUE node_id), or null. */
+export declare function getFocusByNode(node_id: string): FocusRow | null;
+/** The focus realized by a given pane (`%id`), or null. */
+export declare function getFocusByPane(pane: string): FocusRow | null;
+/** A focus by its stable id, or null. (Used by the transitional focus.ptr
+ *  dual-write bridge to read back its single canonical row; removed in Step 8.) */
+export declare function getFocusById(focus_id: string): FocusRow | null;
+/** Every focus row, ordered by id. */
+export declare function listFocuses(): FocusRow[];

package/dist/core/canvas/focuses.js

@@ -0,0 +1,80 @@
+// focuses.ts — the FOCUS table data-access layer (canvas.db, migration v6).
+//
+// Part of the canvas data-access layer: Q7 widens canvas.db from "topology" to
+// "topology + focuses", so the focus-row SQL lives here beside the node+edge
+// model, never in the runtime layer. A FOCUS is one durable on-screen viewport
+// bound to one node; the table is PLURAL (many focuses across windows/sessions),
+// the generalization of the old single `focus.ptr`.
+//
+// placement.ts COMPOSES over these atomic setters/reads (the same way it calls
+// setPresence) — it never runs raw focus SQL itself.
+//
+// Each setter is a single atomic statement. UNIQUE(node_id) upholds "a node
+// occupies at most one focus" (Q5): a second focus row (or an occupant UPDATE)
+// for an already-focused node throws — that is correct, the Q5 vacate-first
+// orchestration is retargetFocus's job (Step 6), not these setters'.
+import { openDb } from './db.js';
+function focusFrom(r) {
+    return {
+        focus_id: r['focus_id'],
+        pane: r['pane'] ?? null,
+        session: r['session'] ?? null,
+        node_id: r['node_id'],
+    };
+}
+// ---------------------------------------------------------------------------
+// Atomic setters — each one a single-statement INSERT/UPDATE/DELETE.
+// ---------------------------------------------------------------------------
+/** INSERT a viewport. Throws on UNIQUE(node_id) if `node_id` already occupies
+ *  another focus (or on PK conflict if `focus_id` exists) — by design. */
+export function openFocusRow(focus_id, pane, session, node_id) {
+    openDb()
+        .prepare('INSERT INTO focuses (focus_id, pane, session, node_id) VALUES (?, ?, ?, ?)')
+        .run(focus_id, pane, session, node_id);
+}
+/** Hot-swap a focus's occupant — single-statement UPDATE. Respects
+ *  UNIQUE(node_id): if `node_id` already occupies ANOTHER focus this throws
+ *  (correct — vacate-first is retargetFocus's job, Step 6, not this setter's). */
+export function setFocusOccupant(focus_id, node_id) {
+    openDb().prepare('UPDATE focuses SET node_id = ? WHERE focus_id = ?').run(node_id, focus_id);
+}
+/** Re-point a focus's durable pane + its derived session cache — for
+ *  reconcileFocus / the daemon (Step 6). Single-statement UPDATE. */
+export function setFocusPane(focus_id, pane, session) {
+    openDb()
+        .prepare('UPDATE focuses SET pane = ?, session = ? WHERE focus_id = ?')
+        .run(pane, session, focus_id);
+}
+/** DELETE a viewport. */
+export function closeFocusRow(focus_id) {
+    openDb().prepare('DELETE FROM focuses WHERE focus_id = ?').run(focus_id);
+}
+// ---------------------------------------------------------------------------
+// Reads.
+// ---------------------------------------------------------------------------
+/** The focus a node occupies (≤1, UNIQUE node_id), or null. */
+export function getFocusByNode(node_id) {
+    const r = openDb()
+        .prepare('SELECT * FROM focuses WHERE node_id = ?')
+        .get(node_id);
+    return r ? focusFrom(r) : null;
+}
+/** The focus realized by a given pane (`%id`), or null. */
+export function getFocusByPane(pane) {
+    const r = openDb()
+        .prepare('SELECT * FROM focuses WHERE pane = ?')
+        .get(pane);
+    return r ? focusFrom(r) : null;
+}
+/** A focus by its stable id, or null. (Used by the transitional focus.ptr
+ *  dual-write bridge to read back its single canonical row; removed in Step 8.) */
+export function getFocusById(focus_id) {
+    const r = openDb()
+        .prepare('SELECT * FROM focuses WHERE focus_id = ?')
+        .get(focus_id);
+    return r ? focusFrom(r) : null;
+}
+/** Every focus row, ordered by id. */
+export function listFocuses() {
+    return openDb().prepare('SELECT * FROM focuses ORDER BY focus_id').all().map(focusFrom);
+}

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

@@ -1,4 +1,7 @@
 export * from './types.js';
+export * from './labels.js';
 export * from './paths.js';
 export * from './canvas.js';
+export * from './focuses.js';
+export * from './telemetry.js';
 export { openDb, closeDb } from './db.js';