@north-light/crouter 0.3.312 → 0.3.313

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

@@ -1,3 +1,4 @@
+import { openDb } from './db.js';
 export type CronScope = 'profile' | 'global';
 export type CronOverlap = 'skip' | 'queue' | 'replace';
 export type CronOnOutput = 'silent' | 'on-failure' | 'always' | 'on-change';
@@ -297,4 +298,5 @@ export declare function runningCrons(): Cron[];
  *  written: a cron canceled while its run was in flight is already gone (and
  *  its history cascaded), so a settling run no-ops with `false` instead of
  *  violating the FK. */
+export declare function recordCronRunLocked(db: ReturnType<typeof openDb>, run: CronRunRecord): boolean;
 export declare function recordCronRun(run: CronRunRecord): boolean;

package/dist/core/canvas/crons.js

@@ -484,20 +484,21 @@ export function runningCrons() {
  *  written: a cron canceled while its run was in flight is already gone (and
  *  its history cascaded), so a settling run no-ops with `false` instead of
  *  violating the FK. */
+export function recordCronRunLocked(db, run) {
+    if (db.prepare('SELECT 1 FROM crons WHERE cron_id = ?').get(run.cron_id) === undefined) {
+        return false;
+    }
+    db.prepare(`INSERT INTO cron_runs (
+       run_id, cron_id, started, finished, duration_ms, exit_code,
+       stdout_head, stderr_head, delivered
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(run.run_id, run.cron_id, run.started, run.finished, run.duration_ms, run.exit_code, run.stdout_head, run.stderr_head, run.delivered);
+    db.prepare(`DELETE FROM cron_runs
+     WHERE cron_id = ? AND run_id NOT IN (
+       SELECT run_id FROM cron_runs WHERE cron_id = ?
+       ORDER BY started DESC, run_id DESC LIMIT ?
+     )`).run(run.cron_id, run.cron_id, CRON_RUN_RING);
+    return true;
+}
 export function recordCronRun(run) {
-    return withCanvasWrite((db) => {
-        if (db.prepare('SELECT 1 FROM crons WHERE cron_id = ?').get(run.cron_id) === undefined) {
-            return false;
-        }
-        db.prepare(`INSERT INTO cron_runs (
-         run_id, cron_id, started, finished, duration_ms, exit_code,
-         stdout_head, stderr_head, delivered
-       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(run.run_id, run.cron_id, run.started, run.finished, run.duration_ms, run.exit_code, run.stdout_head, run.stderr_head, run.delivered);
-        db.prepare(`DELETE FROM cron_runs
-       WHERE cron_id = ? AND run_id NOT IN (
-         SELECT run_id FROM cron_runs WHERE cron_id = ?
-         ORDER BY started DESC, run_id DESC LIMIT ?
-       )`).run(run.cron_id, run.cron_id, CRON_RUN_RING);
-        return true;
-    });
+    return withCanvasWrite((db) => recordCronRunLocked(db, run));
 }

package/dist/core/canvas/daemon-owner.js

@@ -62,6 +62,15 @@ function parseClaim(raw) {
         return null;
     return { pid: pid, pid_identity, token };
 }
+/** Bootstrap only `canvas_meta`; daemon startup owns explicit schema migration. */
+function ensureOwnerTable() {
+    openDb().exec(`
+    CREATE TABLE IF NOT EXISTS canvas_meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    )
+  `);
+}
 /** Read the incumbent's exact serialized `value` for `DAEMON_OWNER_META_KEY`
  *  as a plain snapshot — no transaction. `undefined` means the key is
  *  currently absent. */
@@ -95,6 +104,7 @@ export function claimDaemonOwnership(token) {
     }
     const claim = { pid: process.pid, pid_identity: ownIdentity, token };
     const serializedClaim = serializeClaim(claim);
+    ensureOwnerTable();
     for (;;) {
         const snapshot = readSnapshot();
         if (snapshot === undefined) {

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

@@ -1,7 +1,7 @@
 import { DatabaseSync } from 'node:sqlite';
 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
+/** Open (or reuse) the canvas db at the current `CRTR_HOME`, configuring WAL
+ *  but never changing its schema. Keyed by path so tests with distinct homes get
  *  independent handles.
  *
  *  A cache hit trusts the cached handle outright: `crtrd` is this process's

package/dist/core/canvas/db.js

@@ -1,21 +1,6 @@
-// canvas.db — connection management only. Opens (or reuses) the WAL-mode
-// handle, applies pending schema migrations on first open, and serializes
-// writes under one transaction boundary. sqlite in WAL mode so the many
-// concurrent writers a sisyphus-grade swarm produces don't contend on a
-// single locked JSON.
-//
-// Node rows are a rebuildable index over each node's meta.json (the source of
-// truth). The `subscribes_to` edges are the one genuinely-mutable part no meta
-// owns, so the db is authoritative for them.
-//
-// The versioned schema chain itself (`MIGRATIONS`, `migrate()`) lives in
-// `./migrations.js` — see that file's header for how this repo's three
-// migration homes divide. Re-exported here so every existing import of
-// `migrate`/`MIGRATIONS` from this module keeps working.
 import { DatabaseSync } from 'node:sqlite';
 import { appendFileSync } from 'node:fs';
 import { canvasDbPath, ensureHome } from './paths.js';
-import { migrate } from './migrations.js';
 export { migrate, MIGRATIONS } from './migrations.js';
 const handles = new Map();
 // V-2 open-ledger instrumentation
@@ -45,8 +30,8 @@ function recordOpenLedger() {
         /* instrumentation only — never let a ledger write break a db open */
     }
 }
-/** 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
+/** Open (or reuse) the canvas db at the current `CRTR_HOME`, configuring WAL
+ *  but never changing its schema. Keyed by path so tests with distinct homes get
  *  independent handles.
  *
  *  A cache hit trusts the cached handle outright: `crtrd` is this process's
@@ -78,7 +63,6 @@ export function openDb() {
     // 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;');
-    migrate(db);
     handles.set(path, db);
     return db;
 }

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

@@ -0,0 +1,104 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { DeliveryFailure, DeliverySettlement as ProcessDeliverySettlement } from './delivery-contract.js';
+export type DeliveryState = 'armed' | 'pending' | 'handed_off' | 'acknowledged' | 'permanent_failed';
+export type DeliveryDestinationKind = 'node_inbox' | 'external_action';
+export type DeliveryUrgency = 'critical' | 'urgent' | 'normal' | 'deferred';
+export interface ArmedExternalActionInput {
+    destinationId: string;
+    adapter: Record<string, unknown>;
+    idempotencyKey: string;
+}
+export interface DeliveryRecord {
+    deliveryId: string;
+    messageId: string | null;
+    destinationKind: DeliveryDestinationKind;
+    destinationId: string;
+    urgency: DeliveryUrgency;
+    wake: 0 | 1;
+    state: DeliveryState;
+    attempts: number;
+    nextAttemptAt: number | null;
+    claimedAt: number | null;
+    claimOwner: string | null;
+    acknowledgedAt: number | null;
+    failedAt: number | null;
+    lastFailure: DeliveryFailure | null;
+    adapter: Record<string, unknown> | null;
+    effect: Record<string, unknown> | null;
+    idempotencyKey: string | null;
+    canceledAt: number | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface ClaimedNodeMail extends DeliveryRecord {
+    message: {
+        messageId: string;
+        seq: number;
+        operationId: string;
+        createdAt: string;
+        senderNodeId: string | null;
+        senderName: string | null;
+        kind: 'update' | 'urgent' | 'final' | 'message' | 'completed';
+        label: string;
+        bodyRef: string | null;
+        bodyJson: unknown | null;
+        disposition: 'human-answer' | 'human-canceled' | null;
+    };
+    handoff: 'fresh' | 'inherited';
+}
+/** Claim one broker channel. A refreshing or stale broker receives hold and changes nothing. */
+export declare function claimNodeMail(nodeId: string, executionId: string, channel: 'wake' | 'passive', now?: number): {
+    action: 'claimed' | 'hold';
+    deliveries: ClaimedNodeMail[];
+};
+/** Pre-launch wake claim. It uses the same state transition but deliberately does not reject refresh intent. */
+export declare function claimKickoffMail(nodeId: string, executionId: string, now?: number): ClaimedNodeMail[];
+export type DeliverySettlement = {
+    state: 'acknowledged';
+} | {
+    state: 'released';
+} | {
+    state: 'permanent_failed';
+    failure: DeliveryFailure;
+} | {
+    state: 'pending';
+    nextAttemptAt: number;
+    failure: DeliveryFailure;
+};
+/** The one execution/attempt/owner fence for node mail and external actions. */
+export declare function settleDelivery(deliveryId: string, attempts: number, claimOwner: string, settlement: DeliverySettlement | ProcessDeliverySettlement, now?: number): boolean;
+/** Broker acknowledgement additionally checks the live execution/refresh guards before the per-row fence. */
+export declare function acknowledgeNodeMail(nodeId: string, executionId: string, deliveries: Array<{
+    deliveryId: string;
+    attempts: number;
+    disposition: 'acknowledged' | 'released';
+}>, now?: number): {
+    action: 'acknowledged' | 'hold';
+    results: Array<{
+        deliveryId: string;
+        outcome: 'acknowledged' | 'released' | 'stale';
+    }>;
+};
+/** The immutable action document belonging to one external-action obligation. */
+export declare function messageBodyForDelivery(deliveryId: string): unknown | null;
+/** Read the one external-action obligation with this caller-owned identity. */
+export declare function readExternalActionDelivery(idempotencyKey: string): DeliveryRecord | null;
+export declare function dueExternalActionDeliveries(now: number): DeliveryRecord[];
+export declare function claimExternalActionDelivery(deliveryId: string, now: number, claimOwner: string): DeliveryRecord | null;
+export declare function resetHandedOffDeliveries(now: number): number;
+/** Reset mail held by an execution that is no longer this node's one live execution. */
+export declare function resetStaleExecutionMail(now: number): number;
+export declare function hasUnseenWakeMail(nodeId: string): boolean;
+export declare function hasWakeMailSince(nodeId: string, since: number): boolean;
+export declare function acknowledgedNodeMailCount(nodeId: string): number;
+/** Register an outcome's frozen external destination before an outcome message exists. */
+export declare function armExternalActionDelivery(db: DatabaseSync, input: ArmedExternalActionInput, now?: number): void;
+/** Attach a newly written immutable outcome message and make its registered action due. */
+export declare function activateArmedExternalActionDelivery(db: DatabaseSync, input: {
+    idempotencyKey: string;
+    label: string;
+    bodyJson: string;
+    supersede: boolean;
+}, now?: number): boolean;
+/** Create the messaging schema and import every legacy mailbox/action/wait row. The caller owns the encompassing migration transaction. */
+export declare function migrateMessagingState(db: DatabaseSync): void;

package/dist/core/canvas/deliveries.js

@@ -0,0 +1,354 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { openDb, withCanvasWrite } from './db.js';
+import { inboxPath, passivePath } from './paths.js';
+function deliveryFrom(row) {
+    return {
+        deliveryId: row.delivery_id,
+        messageId: row.message_id,
+        destinationKind: row.destination_kind,
+        destinationId: row.destination_id,
+        urgency: row.urgency,
+        wake: row.wake === 1 ? 1 : 0,
+        state: row.state,
+        attempts: row.attempts,
+        nextAttemptAt: row.next_attempt_at,
+        claimedAt: row.claimed_at,
+        claimOwner: row.claim_owner,
+        acknowledgedAt: row.acknowledged_at,
+        failedAt: row.failed_at,
+        lastFailure: row.last_failure_json === null ? null : JSON.parse(row.last_failure_json),
+        adapter: row.adapter_json === null ? null : JSON.parse(row.adapter_json),
+        effect: row.effect_json === null ? null : JSON.parse(row.effect_json),
+        idempotencyKey: row.idempotency_key,
+        canceledAt: row.canceled_at,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function executionIsLive(db, nodeId, executionId, rejectRefresh) {
+    const row = db.prepare(`SELECT 1 FROM nodes n JOIN executions e ON e.node_id = n.node_id
+      WHERE n.node_id = ? AND e.execution_id = ? AND e.state != 'exited'${rejectRefresh ? " AND n.intent IS NOT 'refresh'" : ''}`).get(nodeId, executionId);
+    return row !== undefined;
+}
+function nodeMailRows(db, nodeId, executionId, wake, freshIds) {
+    const rows = db.prepare(`SELECT d.*, m.message_id AS m_message_id, m.seq, m.operation_id, m.created_at AS message_created_at,
+            m.sender_node_id, m.sender_name, m.kind, m.label, m.body_ref, m.body_json, m.disposition,
+            CASE WHEN d.state = 'handed_off' THEN 'inherited' ELSE 'fresh' END AS handoff
+       FROM deliveries d JOIN messages m ON m.message_id = d.message_id
+      WHERE d.destination_kind = 'node_inbox' AND d.destination_id = ? AND d.wake = ?
+        AND d.canceled_at IS NULL
+        AND (d.state = 'pending' OR (d.state = 'handed_off' AND d.claim_owner = ?))
+      ORDER BY m.seq`).all(nodeId, wake, executionId);
+    return rows.map((row) => ({
+        ...deliveryFrom(row),
+        message: {
+            messageId: row['m_message_id'],
+            seq: Number(row['seq']),
+            operationId: row['operation_id'],
+            createdAt: row['message_created_at'],
+            senderNodeId: row['sender_node_id'],
+            senderName: row['sender_name'],
+            kind: row['kind'],
+            label: row['label'],
+            bodyRef: row['body_ref'],
+            bodyJson: row['body_json'] === null ? null : JSON.parse(row['body_json']),
+            disposition: row['disposition'],
+        },
+        handoff: freshIds?.has(row.delivery_id) === true ? 'fresh' : row['handoff'],
+    }));
+}
+/** Claim one broker channel. A refreshing or stale broker receives hold and changes nothing. */
+export function claimNodeMail(nodeId, executionId, channel, now = Date.now()) {
+    return withCanvasWrite((db) => {
+        if (!executionIsLive(db, nodeId, executionId, true))
+            return { action: 'hold', deliveries: [] };
+        const wake = channel === 'wake' ? 1 : 0;
+        const freshIds = new Set(db.prepare(`SELECT delivery_id FROM deliveries
+        WHERE destination_kind = 'node_inbox' AND destination_id = ? AND wake = ? AND state = 'pending' AND canceled_at IS NULL`).all(nodeId, wake).map((row) => row.delivery_id));
+        db.prepare(`UPDATE deliveries SET state = 'handed_off', attempts = attempts + 1, claim_owner = ?, claimed_at = ?, updated_at = ?
+        WHERE destination_kind = 'node_inbox' AND destination_id = ? AND wake = ? AND state = 'pending' AND canceled_at IS NULL`).run(executionId, now, now, nodeId, wake);
+        return { action: 'claimed', deliveries: nodeMailRows(db, nodeId, executionId, wake, freshIds) };
+    });
+}
+/** Pre-launch wake claim. It uses the same state transition but deliberately does not reject refresh intent. */
+export function claimKickoffMail(nodeId, executionId, now = Date.now()) {
+    return withCanvasWrite((db) => {
+        if (!executionIsLive(db, nodeId, executionId, false))
+            throw new Error(`execution ${executionId} is not live for node ${nodeId}`);
+        const freshIds = new Set(db.prepare(`SELECT delivery_id FROM deliveries
+        WHERE destination_kind = 'node_inbox' AND destination_id = ? AND wake = 1 AND state = 'pending' AND canceled_at IS NULL`).all(nodeId).map((row) => row.delivery_id));
+        db.prepare(`UPDATE deliveries SET state = 'handed_off', attempts = attempts + 1, claim_owner = ?, claimed_at = ?, updated_at = ?
+        WHERE destination_kind = 'node_inbox' AND destination_id = ? AND wake = 1 AND state = 'pending' AND canceled_at IS NULL`).run(executionId, now, now, nodeId);
+        return nodeMailRows(db, nodeId, executionId, 1, freshIds);
+    });
+}
+// Convert the existing subprocess contract at the one shared fence. The old names do not escape this module.
+function normalizedSettlement(settlement) {
+    if (settlement.state === 'accepted')
+        return { state: 'acknowledged' };
+    return settlement;
+}
+/** The one execution/attempt/owner fence for node mail and external actions. */
+export function settleDelivery(deliveryId, attempts, claimOwner, settlement, now = Date.now()) {
+    const next = normalizedSettlement(settlement);
+    const failure = next.state === 'pending' || next.state === 'permanent_failed' ? JSON.stringify(next.failure) : null;
+    const state = next.state === 'released' ? 'pending' : next.state;
+    const nextAttemptAt = next.state === 'pending' ? next.nextAttemptAt : state === 'pending' ? now : null;
+    return withCanvasWrite((db) => Number(db.prepare(`UPDATE deliveries
+        SET state = ?, next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL,
+            acknowledged_at = ?, failed_at = ?, last_failure_json = ?, updated_at = ?
+      WHERE delivery_id = ? AND state = 'handed_off' AND attempts = ? AND claim_owner = ?`).run(state, nextAttemptAt, state === 'acknowledged' ? now : null, state === 'permanent_failed' ? now : null, failure, now, deliveryId, attempts, claimOwner).changes) === 1);
+}
+/** Broker acknowledgement additionally checks the live execution/refresh guards before the per-row fence. */
+export function acknowledgeNodeMail(nodeId, executionId, deliveries, now = Date.now()) {
+    return withCanvasWrite((db) => {
+        if (!executionIsLive(db, nodeId, executionId, true))
+            return { action: 'hold', results: [] };
+        const results = deliveries.map((delivery) => {
+            const owned = db.prepare("SELECT 1 FROM deliveries WHERE delivery_id = ? AND destination_kind = 'node_inbox' AND destination_id = ?").get(delivery.deliveryId, nodeId) !== undefined;
+            return {
+                deliveryId: delivery.deliveryId,
+                outcome: owned && settleDelivery(delivery.deliveryId, delivery.attempts, executionId, { state: delivery.disposition }, now)
+                    ? delivery.disposition
+                    : 'stale',
+            };
+        });
+        return { action: 'acknowledged', results };
+    });
+}
+/** The immutable action document belonging to one external-action obligation. */
+export function messageBodyForDelivery(deliveryId) {
+    const row = openDb().prepare(`SELECT m.body_json FROM deliveries d JOIN messages m ON m.message_id = d.message_id
+      WHERE d.delivery_id = ? AND d.destination_kind = 'external_action'`).get(deliveryId);
+    return row === undefined || row.body_json === null ? null : JSON.parse(row.body_json);
+}
+/** Read the one external-action obligation with this caller-owned identity. */
+export function readExternalActionDelivery(idempotencyKey) {
+    const row = openDb().prepare("SELECT * FROM deliveries WHERE destination_kind = 'external_action' AND idempotency_key = ?").get(idempotencyKey);
+    return row === undefined ? null : deliveryFrom(row);
+}
+export function dueExternalActionDeliveries(now) {
+    return openDb().prepare(`SELECT * FROM deliveries
+      WHERE destination_kind = 'external_action' AND state = 'pending' AND canceled_at IS NULL AND next_attempt_at <= ?
+      ORDER BY next_attempt_at, created_at, delivery_id`).all(now).map(deliveryFrom);
+}
+export function claimExternalActionDelivery(deliveryId, now, claimOwner) {
+    return withCanvasWrite((db) => {
+        const result = db.prepare(`UPDATE deliveries SET state = 'handed_off', attempts = attempts + 1, claimed_at = ?, claim_owner = ?, updated_at = ?
+        WHERE delivery_id = ? AND destination_kind = 'external_action' AND state = 'pending' AND canceled_at IS NULL AND next_attempt_at <= ?`).run(now, claimOwner, now, deliveryId, now);
+        if (Number(result.changes) === 0)
+            return null;
+        return deliveryFrom(db.prepare('SELECT * FROM deliveries WHERE delivery_id = ?').get(deliveryId));
+    });
+}
+export function resetHandedOffDeliveries(now) {
+    return withCanvasWrite((db) => Number(db.prepare(`UPDATE deliveries SET state = 'pending', next_attempt_at = CASE WHEN destination_kind = 'external_action' THEN ? ELSE NULL END,
+       claimed_at = NULL, claim_owner = NULL, updated_at = ? WHERE state = 'handed_off'`).run(now, now).changes));
+}
+/** Reset mail held by an execution that is no longer this node's one live execution. */
+export function resetStaleExecutionMail(now) {
+    return withCanvasWrite((db) => Number(db.prepare(`UPDATE deliveries AS d SET state = 'pending', claimed_at = NULL, claim_owner = NULL, updated_at = ?
+      WHERE d.destination_kind = 'node_inbox' AND d.state = 'handed_off'
+        AND NOT EXISTS (
+          SELECT 1 FROM executions e WHERE e.node_id = d.destination_id AND e.execution_id = d.claim_owner AND e.state != 'exited'
+        )`).run(now).changes));
+}
+export function hasUnseenWakeMail(nodeId) {
+    return openDb().prepare(`SELECT 1 FROM deliveries WHERE destination_kind = 'node_inbox' AND destination_id = ? AND wake = 1
+       AND canceled_at IS NULL AND urgency != 'deferred' AND state IN ('pending', 'handed_off') LIMIT 1`).get(nodeId) !== undefined;
+}
+export function hasWakeMailSince(nodeId, since) {
+    return openDb().prepare(`SELECT 1 FROM deliveries WHERE destination_kind = 'node_inbox' AND destination_id = ? AND wake = 1
+       AND urgency != 'deferred' AND created_at >= ? LIMIT 1`).get(nodeId, since) !== undefined;
+}
+export function acknowledgedNodeMailCount(nodeId) {
+    return Number(openDb().prepare("SELECT COUNT(*) AS count FROM deliveries WHERE destination_kind = 'node_inbox' AND destination_id = ? AND acknowledged_at IS NOT NULL").get(nodeId).count);
+}
+/** Register an outcome's frozen external destination before an outcome message exists. */
+export function armExternalActionDelivery(db, input, now = Date.now()) {
+    const deliveryId = newId();
+    const result = db.prepare(`INSERT INTO deliveries
+       (delivery_id, message_id, destination_kind, destination_id, urgency, wake, state, adapter_json, idempotency_key, created_at, updated_at)
+     VALUES (?, NULL, 'external_action', ?, 'normal', 0, 'armed', ?, ?, ?, ?)
+     ON CONFLICT(idempotency_key) WHERE idempotency_key IS NOT NULL DO UPDATE SET
+       destination_id = excluded.destination_id, adapter_json = excluded.adapter_json, updated_at = excluded.updated_at
+     WHERE deliveries.state = 'armed'`).run(deliveryId, input.destinationId, JSON.stringify(input.adapter), input.idempotencyKey, now, now);
+    if (Number(result.changes) === 0)
+        throw new Error(`external action ${input.idempotencyKey} is already active`);
+}
+/** Attach a newly written immutable outcome message and make its registered action due. */
+export function activateArmedExternalActionDelivery(db, input, now = Date.now()) {
+    const row = db.prepare("SELECT state FROM deliveries WHERE destination_kind = 'external_action' AND idempotency_key = ?").get(input.idempotencyKey);
+    if (row === undefined || (!input.supersede && row.state !== 'armed'))
+        return false;
+    let body;
+    try {
+        body = JSON.parse(input.bodyJson);
+    }
+    catch (error) {
+        throw new Error(`external action ${input.idempotencyKey} has invalid outcome document: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const messageId = newId();
+    const seq = Number(db.prepare('SELECT COALESCE(MAX(seq), 0) AS seq FROM messages').get().seq) + 1;
+    db.prepare(`INSERT INTO messages
+       (message_id, seq, operation_id, created_at, sender_node_id, sender_name, kind, label, body_ref, body_json, disposition)
+     VALUES (?, ?, ?, ?, NULL, NULL, 'completed', ?, NULL, ?, NULL)`).run(messageId, seq, newId(), new Date(now).toISOString(), input.label, JSON.stringify(body));
+    if (input.supersede) {
+        db.prepare(`UPDATE deliveries SET message_id = ?, state = 'pending', attempts = 0, next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL,
+         acknowledged_at = NULL, failed_at = NULL, last_failure_json = NULL, updated_at = ?
+       WHERE destination_kind = 'external_action' AND idempotency_key = ?`).run(messageId, now, now, input.idempotencyKey);
+    }
+    else {
+        db.prepare(`UPDATE deliveries SET message_id = ?, state = 'pending', next_attempt_at = ?, updated_at = ?
+       WHERE destination_kind = 'external_action' AND idempotency_key = ? AND state = 'armed'`).run(messageId, now, now, input.idempotencyKey);
+    }
+    return true;
+}
+function newId() {
+    let id;
+    do
+        id = randomBytes(16).toString('hex');
+    while (id === '00000000000000000000000000000000');
+    return id;
+}
+function readJsonLines(path) {
+    if (!existsSync(path))
+        return [];
+    const raw = readFileSync(path, 'utf8');
+    if (raw.trim() === '')
+        return [];
+    return raw.split('\n').filter((line) => line.trim() !== '').map((line, index) => {
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch (error) {
+            throw new Error(`invalid mailbox JSON at ${path}:${index + 1}: ${error.message}`);
+        }
+        if (!/^(?!0{32}$)[0-9a-f]{32}$/.test(entry.entry_id) || !/^(?!0{32}$)[0-9a-f]{32}$/.test(entry.operation_id)) {
+            throw new Error(`invalid mailbox identity at ${path}:${index + 1}`);
+        }
+        if (typeof entry.ts !== 'string' || typeof entry.label !== 'string')
+            throw new Error(`incomplete mailbox entry at ${path}:${index + 1}`);
+        return entry;
+    });
+}
+function readCanceled(path) {
+    if (!existsSync(path))
+        return new Set();
+    return new Set(readFileSync(path, 'utf8').split('\n').map((line) => line.trim()).filter(Boolean));
+}
+/** Create the messaging schema and import every legacy mailbox/action/wait row. The caller owns the encompassing migration transaction. */
+export function migrateMessagingState(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS messages (
+  message_id TEXT PRIMARY KEY,
+  seq INTEGER NOT NULL UNIQUE,
+  operation_id TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  sender_node_id TEXT,
+  sender_name TEXT,
+  kind TEXT NOT NULL CHECK (kind IN ('update', 'urgent', 'final', 'message', 'completed')),
+  label TEXT NOT NULL,
+  body_ref TEXT,
+  body_json TEXT,
+  disposition TEXT CHECK (disposition IS NULL OR disposition IN ('human-answer', 'human-canceled'))
+);
+CREATE TABLE IF NOT EXISTS deliveries (
+  delivery_id TEXT PRIMARY KEY,
+  message_id TEXT REFERENCES messages(message_id),
+  destination_kind TEXT NOT NULL CHECK (destination_kind IN ('node_inbox', 'external_action')),
+  destination_id TEXT NOT NULL,
+  urgency TEXT NOT NULL CHECK (urgency IN ('critical', 'urgent', 'normal', 'deferred')),
+  wake INTEGER NOT NULL CHECK (wake IN (0, 1)),
+  state TEXT NOT NULL CHECK (state IN ('armed', 'pending', 'handed_off', 'acknowledged', 'permanent_failed')),
+  attempts INTEGER NOT NULL DEFAULT 0 CHECK (attempts >= 0),
+  next_attempt_at INTEGER,
+  claimed_at INTEGER,
+  claim_owner TEXT,
+  acknowledged_at INTEGER,
+  failed_at INTEGER,
+  last_failure_json TEXT,
+  adapter_json TEXT,
+  effect_json TEXT,
+  idempotency_key TEXT,
+  canceled_at INTEGER,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  CHECK (state = 'armed' OR message_id IS NOT NULL)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS messages_seq ON messages(seq);
+CREATE INDEX IF NOT EXISTS deliveries_node_inbox ON deliveries(destination_id, wake, state, created_at) WHERE destination_kind = 'node_inbox';
+CREATE INDEX IF NOT EXISTS deliveries_external_due ON deliveries(state, next_attempt_at) WHERE destination_kind = 'external_action';
+CREATE INDEX IF NOT EXISTS deliveries_handed_off ON deliveries(claim_owner) WHERE state = 'handed_off';
+CREATE INDEX IF NOT EXISTS deliveries_message ON deliveries(message_id);
+CREATE UNIQUE INDEX IF NOT EXISTS deliveries_idempotency ON deliveries(idempotency_key) WHERE idempotency_key IS NOT NULL;
+CREATE TABLE IF NOT EXISTS waits (
+  wait_id TEXT PRIMARY KEY,
+  node_id TEXT NOT NULL REFERENCES nodes(node_id) ON DELETE CASCADE,
+  kind TEXT NOT NULL CHECK (kind = 'controller'),
+  target_id TEXT NOT NULL,
+  generation INTEGER NOT NULL,
+  created_at INTEGER NOT NULL,
+  satisfied_at INTEGER
+);
+CREATE UNIQUE INDEX IF NOT EXISTS waits_live ON waits(node_id) WHERE satisfied_at IS NULL;
+CREATE INDEX IF NOT EXISTS waits_node ON waits(node_id);
+`);
+    const mail = [];
+    for (const row of db.prepare('SELECT node_id FROM nodes').all()) {
+        const nodeId = row.node_id;
+        const inbox = readJsonLines(inboxPath(nodeId));
+        const cursor = existsSync(`${inboxPath(nodeId)}.cursor`) ? readFileSync(`${inboxPath(nodeId)}.cursor`, 'utf8').trim() : '';
+        const cursorIndex = inbox.findIndex((entry) => entry.entry_id === cursor);
+        const canceled = readCanceled(`${inboxPath(nodeId)}.canceled`);
+        inbox.forEach((entry, physicalIndex) => mail.push({ nodeId, wake: 1, source: 'inbox', fileRank: 0, physicalIndex, entry, acknowledged: cursorIndex >= 0 && physicalIndex <= cursorIndex, canceled: canceled.has(entry.entry_id), seq: 0 }));
+        for (const [fileRank, path] of [[0, `${passivePath(nodeId)}.draining`], [1, passivePath(nodeId)]]) {
+            readJsonLines(path).forEach((entry, physicalIndex) => mail.push({ nodeId, wake: 0, source: 'passive', fileRank, physicalIndex, entry, acknowledged: false, canceled: false, seq: 0 }));
+        }
+    }
+    mail.sort((a, b) => a.entry.ts.localeCompare(b.entry.ts) || a.nodeId.localeCompare(b.nodeId) || a.fileRank - b.fileRank || a.physicalIndex - b.physicalIndex);
+    mail.forEach((entry, index) => { entry.seq = index + 1; });
+    const groups = new Map();
+    for (const entry of mail) {
+        const key = `${entry.nodeId}\0${entry.source}`;
+        const group = groups.get(key) ?? [];
+        group.push(entry);
+        groups.set(key, group);
+    }
+    for (const group of groups.values()) {
+        const available = group.map((entry) => entry.seq).sort((a, b) => a - b);
+        group.sort((a, b) => a.fileRank - b.fileRank || a.physicalIndex - b.physicalIndex).forEach((entry, index) => { entry.seq = available[index]; });
+    }
+    const insertMessage = db.prepare(`INSERT INTO messages (message_id, seq, operation_id, created_at, sender_node_id, sender_name, kind, label, body_ref, body_json, disposition) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const insertDelivery = db.prepare(`INSERT INTO deliveries (delivery_id, message_id, destination_kind, destination_id, urgency, wake, state, attempts, acknowledged_at, canceled_at, created_at, updated_at) VALUES (?, ?, 'node_inbox', ?, ?, ?, ?, 0, ?, ?, ?, ?)`);
+    for (const imported of mail) {
+        const entry = imported.entry;
+        insertMessage.run(entry.entry_id, imported.seq, entry.operation_id, entry.ts, entry.from, entry.from_name ?? null, entry.kind, entry.label, entry.ref ?? null, entry.data === undefined ? null : JSON.stringify(entry.data), entry.disposition ?? null);
+        const timestamp = Date.parse(entry.ts);
+        const now = Number.isFinite(timestamp) ? timestamp : 0;
+        insertDelivery.run(newId(), entry.entry_id, imported.nodeId, entry.tier, imported.wake, imported.acknowledged ? 'acknowledged' : 'pending', imported.acknowledged ? now : null, imported.canceled ? now : null, now, now);
+    }
+    const actionRows = db.prepare('SELECT * FROM human_action_deliveries').all();
+    for (const row of actionRows) {
+        const messageId = newId();
+        insertMessage.run(messageId, nextSeq(db), newId(), new Date(row.created_at).toISOString(), null, null, 'completed', row.request_id, null, row.completion_json, null);
+        const state = row.state === 'running' ? 'handed_off' : row.state === 'accepted' ? 'acknowledged' : row.state;
+        db.prepare(`INSERT INTO deliveries (delivery_id, message_id, destination_kind, destination_id, urgency, wake, state, attempts, next_attempt_at, claimed_at, claim_owner, acknowledged_at, failed_at, last_failure_json, adapter_json, idempotency_key, created_at, updated_at) VALUES (?, ?, 'external_action', 'human_action', 'normal', 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(newId(), messageId, state, row.attempt, row.next_attempt_at, row.claimed_at, row.claim_owner, row.accepted_at, row.permanent_failed_at, row.last_failure_json, JSON.stringify({ adapter: 'subprocess', argv: JSON.parse(row.argv_json), cwd: row.cwd }), `human-action:${row.request_id}`, row.created_at, row.updated_at);
+    }
+    const outcomeRows = db.prepare('SELECT * FROM node_outcome_deliveries').all();
+    for (const row of outcomeRows) {
+        const messageId = row.document_json === null ? null : newId();
+        if (messageId !== null)
+            insertMessage.run(messageId, nextSeq(db), newId(), new Date(row.created_at).toISOString(), null, null, 'completed', row.node_id, null, row.document_json, null);
+        const state = row.document_json === null ? 'armed' : row.state === 'running' ? 'handed_off' : row.state === 'accepted' ? 'acknowledged' : row.state;
+        db.prepare(`INSERT INTO deliveries (delivery_id, message_id, destination_kind, destination_id, urgency, wake, state, attempts, next_attempt_at, claimed_at, claim_owner, acknowledged_at, failed_at, last_failure_json, adapter_json, idempotency_key, created_at, updated_at) VALUES (?, ?, 'external_action', ?, 'normal', 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(newId(), messageId, row.action_name, state, row.attempt, row.next_attempt_at, row.claimed_at, row.claim_owner, row.accepted_at, row.permanent_failed_at, row.last_failure_json, JSON.stringify({ adapter: 'subprocess', argv: JSON.parse(row.argv_json), cwd: row.cwd, config_origin: row.config_origin, payload: row.payload_json === null ? null : JSON.parse(row.payload_json) }), `node-outcome:${row.node_id}`, row.created_at, row.updated_at);
+    }
+    const waiting = db.prepare('SELECT node_id, waiting_for, waiting_for_generation FROM nodes WHERE waiting_for IS NOT NULL').all();
+    for (const row of waiting)
+        db.prepare("INSERT INTO waits (wait_id, node_id, kind, target_id, generation, created_at, satisfied_at) VALUES (?, ?, 'controller', ?, ?, ?, NULL)").run(newId(), row.node_id, row.waiting_for, row.waiting_for_generation, Date.now());
+}
+function nextSeq(db) {
+    return Number(db.prepare('SELECT COALESCE(MAX(seq), 0) AS seq FROM messages').get().seq) + 1;
+}

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

@@ -0,0 +1,29 @@
+export interface Execution {
+    executionId: string;
+    nodeId: string;
+    daemonEpoch: string | null;
+    pid: number | null;
+    processIdentity: string | null;
+    state: 'launching' | 'running' | 'exited';
+    startedAt: string;
+    endedAt: string | null;
+    exitReason: string | null;
+}
+export declare function liveExecutionForNode(nodeId: string): Execution | null;
+export declare function beginExecution(nodeId: string, input: {
+    daemonEpoch: string | null;
+}): string;
+/** Returns shutdown when a late broker references an execution no longer live. */
+export declare function recordExecutionPid(executionId: string, nodeId: string, pid: number): 'recorded' | 'shutdown';
+export declare function endExecution(executionId: string, input: {
+    reason: string;
+}): boolean;
+export declare function abortExecution(executionId: string, input: {
+    reason: string;
+}): boolean;
+export declare function endLiveExecution(nodeId: string, input: {
+    reason: string;
+}): boolean;
+export declare function migrateLegacyExecutionIdentities(captureIdentity?: (pid: number) => string | undefined): {
+    migrated: string[];
+};