@north-light/crouter 0.3.232 → 0.3.234

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

@@ -24,6 +24,28 @@ export declare function updateNode(nodeId: string, patch: Partial<NodeIdentity>)
 export declare function setStatus(nodeId: string, status: NodeStatus): void;
 /** Set a node's exit intent. Atomic single-column write. */
 export declare function setIntent(nodeId: string, intent: ExitIntent): void;
+/** Atomically write status and/or intent, gated on an optional from-status set
+ *  and/or on the row carrying no committed final_report. The lifecycle state
+ *  machine (runtime/lifecycle.ts) is the one caller: it owns the legality
+ *  table and the unknown-node/illegal-move/already-finalized-cancel branching,
+ *  this only performs the single conditional UPDATE it needs. A PRESENT key in
+ *  `fields` (even `intent: null`) writes that column; an ABSENT key leaves it
+ *  unchanged. Returns the row-changed count so the caller can distinguish "no
+ *  such node", "gate failed", and "already applied" without a second query. */
+export declare function transitionStatusIntent(nodeId: string, fields: {
+    status?: NodeStatus;
+    intent?: ExitIntent;
+}, opts?: {
+    fromStatuses?: readonly NodeStatus[];
+    requireNoFinalReport?: boolean;
+}): number;
+/** Read a node's committed-final latch pointer. Pure read, no side effect. */
+export declare function getFinalReport(nodeId: string): string | null;
+/** CAS-clear a node's finalization latch (final_report + finalized_at) —
+ *  retract-pointer-only. Gated on the exact final_report value the caller
+ *  observed via getFinalReport, so a concurrent clear/refinalize can never be
+ *  clobbered. Returns true iff the CAS matched and cleared. */
+export declare function clearFinalReportIfMatches(nodeId: string, expectedFinalReport: string): boolean;
 /** 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

package/dist/core/canvas/canvas.js

@@ -4,20 +4,19 @@
 // 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 { envNodeId } from '../../shared/env.js';
 import { existsSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { openDb, withCanvasWrite } from './db.js';
 import { withMetaLock, readMetaObject, writeMetaObjectLocked, writeJsonFileDurably } from './meta-file.js';
 import { isPidAlive, recordedPidLiveness, capturePidIdentities, identitiesMatch, isLegacyTicksIdentity, isBootScopedIdentity, } from './pid.js';
 import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, jobDir, } from './paths.js';
-// ---------------------------------------------------------------------------
 // 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 = [
@@ -75,12 +74,10 @@ function readMeta(nodeId) {
 function writeMeta(meta) {
     writeJsonFileDurably(nodeMetaPath(meta.node_id), toIdentity(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
@@ -162,9 +159,7 @@ function runtimeFromRow(nodeId) {
         pane: r['pane'] ?? null,
     };
 }
-// ---------------------------------------------------------------------------
 // Nodes
-// ---------------------------------------------------------------------------
 /** 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) {
@@ -236,13 +231,11 @@ export function updateNode(nodeId, patch) {
     upsertRow(next);
     return getNode(nodeId);
 }
-// ---------------------------------------------------------------------------
 // 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) {
     openDb().prepare('UPDATE nodes SET status = ? WHERE node_id = ?').run(status, nodeId);
@@ -251,6 +244,53 @@ export function setStatus(nodeId, status) {
 export function setIntent(nodeId, intent) {
     openDb().prepare('UPDATE nodes SET intent = ? WHERE node_id = ?').run(intent ?? null, nodeId);
 }
+/** Atomically write status and/or intent, gated on an optional from-status set
+ *  and/or on the row carrying no committed final_report. The lifecycle state
+ *  machine (runtime/lifecycle.ts) is the one caller: it owns the legality
+ *  table and the unknown-node/illegal-move/already-finalized-cancel branching,
+ *  this only performs the single conditional UPDATE it needs. A PRESENT key in
+ *  `fields` (even `intent: null`) writes that column; an ABSENT key leaves it
+ *  unchanged. Returns the row-changed count so the caller can distinguish "no
+ *  such node", "gate failed", and "already applied" without a second query. */
+export function transitionStatusIntent(nodeId, fields, opts = {}) {
+    const assignments = [];
+    const values = [];
+    if (Object.prototype.hasOwnProperty.call(fields, 'status')) {
+        assignments.push('status = ?');
+        values.push(fields.status ?? null);
+    }
+    if (Object.prototype.hasOwnProperty.call(fields, 'intent')) {
+        assignments.push('intent = ?');
+        values.push(fields.intent ?? null);
+    }
+    const predicates = ['node_id = ?'];
+    values.push(nodeId);
+    if (opts.fromStatuses !== undefined) {
+        predicates.push(`status IN (${opts.fromStatuses.map(() => '?').join(', ')})`);
+        values.push(...opts.fromStatuses);
+    }
+    if (opts.requireNoFinalReport === true)
+        predicates.push('final_report IS NULL');
+    const result = openDb()
+        .prepare(`UPDATE nodes SET ${assignments.join(', ')} WHERE ${predicates.join(' AND ')}`)
+        .run(...values);
+    return Number(result.changes);
+}
+/** Read a node's committed-final latch pointer. Pure read, no side effect. */
+export function getFinalReport(nodeId) {
+    const row = openDb().prepare('SELECT final_report FROM nodes WHERE node_id = ?').get(nodeId);
+    return row?.final_report ?? null;
+}
+/** CAS-clear a node's finalization latch (final_report + finalized_at) —
+ *  retract-pointer-only. Gated on the exact final_report value the caller
+ *  observed via getFinalReport, so a concurrent clear/refinalize can never be
+ *  clobbered. Returns true iff the CAS matched and cleared. */
+export function clearFinalReportIfMatches(nodeId, expectedFinalReport) {
+    const result = openDb()
+        .prepare('UPDATE nodes SET final_report = NULL, finalized_at = NULL WHERE node_id = ? AND final_report = ?')
+        .run(nodeId, expectedFinalReport);
+    return result.changes > 0;
+}
 /** 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
@@ -387,10 +427,8 @@ export function listNodes(filter) {
     }
     return rows.map(rowFrom);
 }
-// ---------------------------------------------------------------------------
 // Warm pool — spare booted roots awaiting a `prefer_warm` claim (see
 // `runtime/warm-pool.ts` for the recipe key and the mint/refill policy).
-// ---------------------------------------------------------------------------
 /** Mark an already-spawned node as an unclaimed spare for `recipeKey`. Hides it
  *  from every listing until it is claimed. */
 export function registerWarmSpare(nodeId, recipeKey) {
@@ -539,9 +577,7 @@ export function listResumableRoots(cwd) {
         .all(cwd);
     return rows.map(rowFrom);
 }
-// ---------------------------------------------------------------------------
 // Edges
-// ---------------------------------------------------------------------------
 function addEdge(type, from, to, active) {
     openDb()
         .prepare(`INSERT INTO edges (type, from_id, to_id, active, created)
@@ -592,9 +628,7 @@ export function subscriptionsOf(subscriber) {
         created: r['created'],
     }));
 }
-// ---------------------------------------------------------------------------
 // Graph queries
-// ---------------------------------------------------------------------------
 /** A "view": every node whose output cascades up to `root` via subscriptions —
  *  the subscription sub-DAG reachable downward (root → its reports → theirs …).
  *  Returns ids excluding root, in BFS order. Cycle-safe. */
@@ -714,9 +748,7 @@ export function withFreshTerminalGuard(nodeId, isTerminal, body) {
         return { kind: 'ran', result: body() };
     });
 }
-// ---------------------------------------------------------------------------
 // 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
@@ -823,7 +855,7 @@ export function pruneNodes(opts) {
     const dryRun = opts.dryRun ?? false;
     const includeStale = opts.includeStale ?? false;
     const cutoff = new Date(Date.now() - opts.ttlDays * 86_400_000).toISOString();
-    const selfId = process.env['CRTR_NODE_ID'] ?? '';
+    const selfId = envNodeId() ?? '';
     const db = openDb();
     const terminal = db
         .prepare(`SELECT node_id, status, created FROM nodes
@@ -960,7 +992,7 @@ function recencyMs(nodeId, created) {
  *  reports the candidate set and deletes NOTHING. */
 export function pruneToLimit(opts) {
     const dryRun = opts.dryRun ?? false;
-    const selfId = process.env['CRTR_NODE_ID'] ?? '';
+    const selfId = envNodeId() ?? '';
     const rows = listNodes();
     // Rank ALL nodes by recency DESC, tagging protection as we go. Protection is
     // status-only (active|idle) — NOT gated on pi_pid liveness — so a node whose

package/dist/core/canvas/crons.js

@@ -59,9 +59,7 @@ function cronFrom(r) {
         updated: r['updated'],
     };
 }
-// ---------------------------------------------------------------------------
 // Signal safety
-// ---------------------------------------------------------------------------
 /** The ONLY sanctioned way to signal a cron run's process group from a stored
  *  row. Re-captures the CURRENT identity of `run_pid` and signals only when it
  *  MATCHES the fingerprint recorded at lease acquisition. Returns whether the
@@ -101,9 +99,7 @@ export function verifyLeasedCronRun(c) {
         return false; // pid genuinely gone
     return identitiesMatch(current, c.run_pid_identity);
 }
-// ---------------------------------------------------------------------------
 // Writes
-// ---------------------------------------------------------------------------
 /** INSERT one cron row from the pinned arm spec, returning its (caller-
  *  supplied) `cron_id` plus the ids of any deadline it displaced. Stamps
  *  `created`/`updated`; lease fields start idle.
@@ -301,9 +297,7 @@ export function advanceCron(cron_id, nextFireIso) {
         .prepare('UPDATE crons SET fire_at = ?, updated = ? WHERE cron_id = ?')
         .run(nextFireIso, new Date().toISOString(), cron_id);
 }
-// ---------------------------------------------------------------------------
 // Daemon run-executor primitives (src/daemon/cron-run.ts)
-// ---------------------------------------------------------------------------
 /** The daemon's per-tick due query: active, idle, fire_at arrived, in
  *  deterministic order. The idle-only filter IS the default `overlap='skip'`
  *  behavior — a row whose previous run is still leased is simply not due.

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

@@ -1,26 +1,20 @@
 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. Journaled
- *  entries from `src/migrations/registry.ts` follow the local steps, so a new
- *  registry migration lands as the next version. */
-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.
- *
- *  ATOMIC AND RESTARTABLE: each step AND its `user_version` bump run inside one
- *  `BEGIN IMMEDIATE`/`COMMIT` (SQLite journals `user_version` with the
- *  transaction, so a rollback restores it too). An interrupted or failing step
- *  therefore leaves the db exactly at the previous version with none of its
- *  writes committed — a half-applied step can never wedge every later open. The
- *  write lock also serializes concurrent openers; the version is re-read after
- *  acquiring it so a step another process just applied is skipped rather than
- *  re-run. */
-export declare function migrate(db: DatabaseSync): void;
+export { migrate, MIGRATIONS } from './migrations.js';
 /** 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. */
+ *  independent handles.
+ *
+ *  A cache hit trusts the cached handle outright: `crtrd` is this process's
+ *  sole canvas-db owner (see `crtrd-sole-state-owner`), and nothing outside
+ *  `openDb`/`closeDb` ever touches `handles` — there is no other actor in this
+ *  process that could invalidate a live handle out from under it. (A
+ *  2026-06-25 revision added a `PRAGMA database_list` liveness probe here that
+ *  silently closed and reopened the handle on any throw; it shipped alongside
+ *  an unrelated guest-relay `PATH` fix for the now-removed `hearth` guest
+ *  bootstrap, named no concrete failure mode in its commit or a test, and that
+ *  guest-relay path no longer exists. Removed rather than kept-and-logged: a
+ *  silent boot-path reopen is worse than trusting a handle this process
+ *  already owns.) */
 export declare function openDb(): DatabaseSync;
 /** Run `body` under the canvas SQLite write lock, joining an outer transaction
  *  when the shared connection already owns one. This is the common boundary for