@crouton-kit/crouter 0.3.33 → 0.3.34

package/dist/core/canvas/triggers.js

@@ -0,0 +1,320 @@
+// triggers.ts — the TRIGGERS table data-access layer (canvas.db, migration v9).
+//
+// One-module-per-table (the focuses.ts precedent, and the now-deleted
+// wakeups.ts before it): ALL SQL that touches the `triggers` table lives HERE
+// and nowhere else. A TRIGGER is one durable row generalizing the old
+// per-kind wakeup row: trigger → action. It
+// decides WHEN to fire (trigger_type: at/every/when/until) and the row
+// separately says WHAT enacts (action: msg/new) and HOW (action_mode:
+// inbox_message/fresh_revive/deadline_message/node_birth). See the
+// node-trigger-grammar spec for the full model.
+//
+// Two anchors, two reap rules, carried forward unchanged from the wakeups
+// design:
+//   - node_id  → the target AND the node-anchored cancel anchor; carries the
+//     `ON DELETE CASCADE` FK, so a pruned node's node-anchored triggers are
+//     reaped for free in pruneNodes' DELETE FROM nodes. NULL = canvas-detached
+//     (a deferred/recurring node_birth).
+//   - owner_id → the armer; a PLAIN indexed column with NO FK, so a crashed-
+//     then-pruned armer's detached trigger is NOT cascade-dropped. Reaped only
+//     by the explicit cancelTriggersFor DELETE on deliberate close.
+//
+// Each function is a single-statement query mirroring the canvas.ts atomic-
+// setter pattern — no read-modify-write, serialized by WAL. The data-access
+// layer OWNS payload serialization: armTrigger JSON.stringifies the typed
+// per-action_mode union on write; dueClockTriggers/listTriggers/duePredicate-
+// Triggers JSON.parse it back on read, so callers consume `payload.body` /
+// `payload as SpawnChildOpts` directly.
+//
+// `trigger_id` is CALLER-SUPPLIED (the command surface mints the id): the
+// canvas layer never imports newNodeId from runtime/nodes.ts — that would
+// force a canvas → runtime → canvas import cycle.
+//
+// Predicate (`--when`) primitives below (duePredicateTriggers through
+// resetPredicateLease) are DAO-only plumbing for Phase 3's daemon-owned
+// evaluator — nothing in the current command surface or daemon arms or
+// evaluates a `trigger_type='when'` row yet.
+import { openDb } from './db.js';
+import { killProcessGroup } from './pid.js';
+/** A thrown integrity-backstop error from armTrigger. `code` is mapped by the
+ *  command surface to a rendered error block — armTrigger carries integrity
+ *  backstops only (empty body / recur-on-deadline / unknown action_mode);
+ *  target-resolvability + recoverable-state + per-owner cap checks live in the
+ *  surface, so a non-surface armer could insert a dangling trigger — every
+ *  armer MUST route through the surface. */
+export class TriggerArmError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'TriggerArmError';
+    }
+}
+/** Hydrate a raw row into a Trigger, JSON.parsing `payload` back into the typed
+ *  per-action_mode union (NULL column → null). */
+function triggerFrom(r) {
+    const raw = r['payload'];
+    return {
+        trigger_id: r['trigger_id'],
+        owner_id: r['owner_id'],
+        node_id: r['node_id'] ?? null,
+        action: r['action'],
+        action_mode: r['action_mode'],
+        trigger_type: r['trigger_type'],
+        fire_at: r['fire_at'] ?? null,
+        recur: r['recur'] ?? null,
+        payload: raw == null ? null : JSON.parse(raw),
+        when_script: r['when_script'] ?? null,
+        eval_every: r['eval_every'] ?? null,
+        next_eval_at: r['next_eval_at'] ?? null,
+        timeout_at: r['timeout_at'] ?? null,
+        eval_state: r['eval_state'],
+        eval_started_at: r['eval_started_at'] ?? null,
+        eval_pid: r['eval_pid'] ?? null,
+        eval_lease_owner: r['eval_lease_owner'] ?? null,
+        last_eval_at: r['last_eval_at'] ?? null,
+        last_exit: r['last_exit'] ?? null,
+        last_stderr: r['last_stderr'] ?? null,
+        created: r['created'],
+    };
+}
+// ---------------------------------------------------------------------------
+// Writes — each a single-statement INSERT/UPDATE/DELETE.
+// ---------------------------------------------------------------------------
+/** INSERT one trigger row from the pinned spec, returning its (caller-supplied)
+ *  `trigger_id`. JSON.stringifies the typed `payload` union into the TEXT
+ *  column and stamps `created`.
+ *
+ *  Deadline upsert (≤1 deadline per node): for `action_mode === 'deadline_message'`
+ *  the node's existing deadline is canceled first, then the new one inserted —
+ *  the partial unique index `idx_triggers_deadline` is the schema-level
+ *  backstop.
+ *
+ *  Integrity backstops (throw TriggerArmError):
+ *   - empty/whitespace payload `body` for inbox_message/deadline_message → `empty_body`
+ *     (a `trigger_type='when'` inbox_message may omit body entirely instead —
+ *     that is the stdout-as-body case, not a violation).
+ *   - non-NULL `recur` on a deadline_message                              → `deadline_cannot_recur`.
+ *   - unknown `action_mode`                                               → `bad_action_mode`. */
+export function armTrigger(spec) {
+    const { action_mode } = spec;
+    if (action_mode !== 'inbox_message' &&
+        action_mode !== 'fresh_revive' &&
+        action_mode !== 'deadline_message' &&
+        action_mode !== 'node_birth') {
+        throw new TriggerArmError('bad_action_mode', `unknown trigger action_mode: ${String(action_mode)}`);
+    }
+    if (action_mode === 'inbox_message' || action_mode === 'deadline_message') {
+        const body = spec.payload?.body;
+        // A predicate (`trigger_type='when'`) inbox_message may omit body entirely:
+        // the daemon fills it from captured stdout when the predicate exits 0 (spec's
+        // stdout-as-body rule). Every other inbox_message/deadline_message row
+        // (now/clock/deadline) still requires a non-empty body — there is no other
+        // source to fill it from at fire time.
+        const bodyFromStdout = action_mode === 'inbox_message' && spec.trigger_type === 'when' && body === undefined;
+        if (!bodyFromStdout && (typeof body !== 'string' || body.trim() === '')) {
+            throw new TriggerArmError('empty_body', `a ${action_mode} trigger requires a non-empty payload body.`);
+        }
+    }
+    if (action_mode === 'deadline_message' && spec.recur != null) {
+        throw new TriggerArmError('deadline_cannot_recur', 'a deadline trigger cannot recur.');
+    }
+    if (action_mode === 'deadline_message' && spec.node_id != null) {
+        cancelDeadlinesFor(spec.node_id);
+    }
+    const payloadText = spec.payload == null ? null : JSON.stringify(spec.payload);
+    openDb()
+        .prepare(`INSERT INTO triggers (
+         trigger_id, owner_id, node_id, action, action_mode, trigger_type,
+         fire_at, recur, payload, when_script, eval_every, next_eval_at,
+         timeout_at, created
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(spec.trigger_id, spec.owner_id, spec.node_id ?? null, spec.action, spec.action_mode, spec.trigger_type, spec.fire_at ?? null, spec.recur ?? null, payloadText, spec.when_script ?? null, spec.eval_every ?? null, spec.next_eval_at ?? null, spec.timeout_at ?? null, new Date().toISOString());
+    return spec.trigger_id;
+}
+/** UPDATE the next fire time — clock recurrence advancement (the daemon settles
+ *  a recurring row to its next slot BEFORE enacting, crash-safe). */
+export function advanceTrigger(trigger_id, nextFireIso) {
+    openDb().prepare('UPDATE triggers SET fire_at = ? WHERE trigger_id = ?').run(nextFireIso, trigger_id);
+}
+/** DELETE one trigger by id — one-shot consumption (the daemon settles a
+ *  one-shot row BEFORE enacting, crash-safe). */
+/** Deletes the row and reports whether it actually removed a LIVE one (vs a
+ *  no-op on an already-gone trigger) — callers racing another consumer of the
+ *  same trigger (e.g. predicate-eval.ts's close handler racing a wall-clock
+ *  reaper's kill) use the return value to no-op instead of double-enacting. */
+export function consumeTrigger(trigger_id) {
+    return openDb().prepare('DELETE FROM triggers WHERE trigger_id = ?').run(trigger_id).changes > 0;
+}
+/** Kill any in-flight predicate process group for rows about to be deleted —
+ *  spec's "trigger cancellation always kills any in-flight predicate process
+ *  group" (§Deterministic removal). Selects eval_state/eval_pid for the same
+ *  WHERE clause the delete uses, signals any 'running' row's process group,
+ *  then deletes. The single seam every cancel/reap path (explicit `node
+ *  triggers cancel`, node close/reap via cancelTriggersFor, finalize via
+ *  cancelSelfAlarms) shares, so none of them need their own kill logic. */
+function reapInFlightThenDelete(whereSql, params) {
+    const db = openDb();
+    const rows = db
+        .prepare(`SELECT eval_state, eval_pid FROM triggers WHERE ${whereSql}`)
+        .all(...params);
+    for (const r of rows) {
+        if (r.eval_state === 'running' && r.eval_pid != null)
+            killProcessGroup(r.eval_pid);
+    }
+    db.prepare(`DELETE FROM triggers WHERE ${whereSql}`).run(...params);
+}
+/** DELETE one trigger by id — the explicit user/surface cancel. Idempotent:
+ *  0 rows ⇒ no error. Kills any in-flight predicate process group for this
+ *  trigger before deleting. */
+export function cancelTrigger(trigger_id) {
+    reapInFlightThenDelete('trigger_id = ?', [trigger_id]);
+}
+/** DELETE every trigger anchored to this node AND every detached trigger it
+ *  ARMED — deliberate close/reap. Hooked at transition('cancel'). */
+export function cancelTriggersFor(node_id) {
+    reapInFlightThenDelete('node_id = ? OR owner_id = ?', [node_id, node_id]);
+}
+/** DELETE this node's one-shot self-alarms (recur IS NULL); node-anchored
+ *  recurring triggers SURVIVE — finalize is the instance finishing, not a
+ *  teardown of standing schedules. Hooked at transition('finalize'). */
+export function cancelSelfAlarms(node_id) {
+    reapInFlightThenDelete('node_id = ? AND recur IS NULL', [node_id]);
+}
+/** DELETE this node's pending deadline(s) — cancel-on-wake. Hooked at
+ *  reviveNode, so the deadline always belongs to the dormancy left. */
+export function cancelDeadlinesFor(node_id) {
+    openDb()
+        .prepare("DELETE FROM triggers WHERE node_id = ? AND action_mode = 'deadline_message'")
+        .run(node_id);
+}
+// ---------------------------------------------------------------------------
+// Reads — clock triggers.
+// ---------------------------------------------------------------------------
+/** The daemon's per-tick due query for CLOCK triggers only (`at`/`every`/
+ *  `until` — predicate `when` triggers fire via next_eval_at, see
+ *  duePredicateTriggers): every row whose fire_at has arrived, in fire_at
+ *  order, with `payload` parsed into the typed union. Returns exactly ONE row
+ *  per recurring trigger regardless of missed slots — coalescing is structural. */
+export function dueClockTriggers(nowIso) {
+    return openDb()
+        .prepare(`SELECT * FROM triggers
+         WHERE trigger_type IN ('at', 'every', 'until') AND fire_at <= ?
+         ORDER BY fire_at`)
+        .all(nowIso).map(triggerFrom);
+}
+/** List triggers for a scope (node / owner / subtree / due / canvas), `payload`
+ *  parsed as in dueClockTriggers. The subtree variant binds the id set with `?`
+ *  placeholders (mirroring listNodes — the codebase's one safe dynamic-IN
+ *  spot); ids are NEVER string-concatenated. The `due` scope is clock-only,
+ *  matching dueClockTriggers' filter. */
+export function listTriggers(scope) {
+    const db = openDb();
+    let rows;
+    if ('node' in scope) {
+        rows = db
+            .prepare('SELECT * FROM triggers WHERE node_id = ? ORDER BY fire_at')
+            .all(scope.node);
+    }
+    else if ('owner' in scope) {
+        rows = db
+            .prepare('SELECT * FROM triggers WHERE owner_id = ? ORDER BY fire_at')
+            .all(scope.owner);
+    }
+    else if ('subtree' in scope) {
+        if (scope.subtree.length === 0)
+            return [];
+        const placeholders = scope.subtree.map(() => '?').join(',');
+        rows = db
+            .prepare(`SELECT * FROM triggers WHERE node_id IN (${placeholders}) ORDER BY fire_at`)
+            .all(...scope.subtree);
+    }
+    else if ('due' in scope) {
+        rows = db
+            .prepare(`SELECT * FROM triggers WHERE trigger_type IN ('at', 'every', 'until') AND fire_at <= ? ORDER BY fire_at`)
+            .all(scope.due);
+    }
+    else {
+        rows = db.prepare('SELECT * FROM triggers ORDER BY fire_at').all();
+    }
+    return rows.map(triggerFrom);
+}
+/** True if the node has ANY pending self-anchored trigger (of any type).
+ *  Consumed by the stop-guard self-wake seam so a no-child poll node releases
+ *  dormant after arming instead of being nagged to finish. */
+export function hasPendingSelfTrigger(node_id) {
+    return (openDb().prepare('SELECT 1 FROM triggers WHERE node_id = ? LIMIT 1').get(node_id) !== undefined);
+}
+// ---------------------------------------------------------------------------
+// Predicate (`--when`) primitives — Phase 3 daemon-evaluator plumbing.
+// Nothing in this phase arms a `trigger_type='when'` row; these exist so the
+// daemon's evaluator can be built directly against this DAO without another
+// storage-layer pass.
+// ---------------------------------------------------------------------------
+/** Predicate triggers due for evaluation: idle, `next_eval_at` arrived,
+ *  deterministic order (`next_eval_at`, then `created`, then `trigger_id` —
+ *  spec §Daemon behavior step 3). Capacity enforcement (max concurrent
+ *  canvas-wide / per-owner) is the daemon's job, not this query's. */
+export function duePredicateTriggers(nowIso) {
+    return openDb()
+        .prepare(`SELECT * FROM triggers
+         WHERE trigger_type = 'when' AND eval_state = 'idle' AND next_eval_at <= ?
+         ORDER BY next_eval_at, created, trigger_id`)
+        .all(nowIso).map(triggerFrom);
+}
+/** Atomically acquire the idle lease for one predicate evaluation: flips
+ *  `eval_state` to 'running' and records lease/pid metadata, but ONLY if the
+ *  row is still idle (the `WHERE eval_state = 'idle'` guard is the atomicity —
+ *  two daemons racing the same row can't both win). Returns whether THIS call
+ *  acquired it. */
+export function acquirePredicateLease(trigger_id, leaseOwner, pid, startedAtIso) {
+    const res = openDb()
+        .prepare(`UPDATE triggers
+       SET eval_state = 'running', eval_started_at = ?, eval_pid = ?, eval_lease_owner = ?
+       WHERE trigger_id = ? AND eval_state = 'idle'`)
+        .run(startedAtIso, pid, leaseOwner, trigger_id);
+    return Number(res.changes) > 0;
+}
+/** Record a non-firing predicate evaluation result (exit non-zero, or a
+ *  per-eval timeout): releases the lease back to idle and schedules the next
+ *  check. Exit-0 (fire) is NOT recorded here — the spec's settle-before-enact
+ *  rule means a firing predicate is consumed (consumeTrigger) then enacted,
+ *  never left as an idle row. */
+export function recordPredicateEvalResult(trigger_id, result) {
+    openDb()
+        .prepare(`UPDATE triggers
+       SET eval_state = 'idle', eval_started_at = NULL, eval_pid = NULL, eval_lease_owner = NULL,
+           last_eval_at = ?, last_exit = ?, last_stderr = ?, next_eval_at = ?
+       WHERE trigger_id = ?`)
+        .run(result.completedAtIso, result.exitCode, result.stderrTail, result.nextEvalAtIso, trigger_id);
+}
+/** Every predicate trigger currently marked 'running' — the daemon's stale-
+ *  lease recovery scan on restart checks each recorded `eval_pid` for
+ *  liveness and calls resetPredicateLease for any that's gone. */
+export function runningPredicateTriggers() {
+    return openDb()
+        .prepare(`SELECT * FROM triggers WHERE trigger_type = 'when' AND eval_state = 'running'`)
+        .all().map(triggerFrom);
+}
+/** Reset a predicate trigger's lease back to idle without recording a result —
+ *  stale-lease recovery for a row whose recorded eval_pid is no longer alive
+ *  (the prior daemon instance died mid-evaluation). */
+export function resetPredicateLease(trigger_id) {
+    openDb()
+        .prepare(`UPDATE triggers
+       SET eval_state = 'idle', eval_started_at = NULL, eval_pid = NULL, eval_lease_owner = NULL
+       WHERE trigger_id = ?`)
+        .run(trigger_id);
+}
+/** Predicate triggers whose WALL-CLOCK timeout has arrived, regardless of
+ *  eval_state (an in-flight evaluation past its own trigger's timeout_at is
+ *  still reaped — the caller kills the process group itself since this is a
+ *  read, not a mutation). Spec §Predicate triggers: "Wall-clock timeout_at
+ *  reached: consume and notify owner." */
+export function duePredicateTimeouts(nowIso) {
+    return openDb()
+        .prepare(`SELECT * FROM triggers
+         WHERE trigger_type = 'when' AND timeout_at IS NOT NULL AND timeout_at <= ?
+         ORDER BY timeout_at, created, trigger_id`)
+        .all(nowIso).map(triggerFrom);
+}

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

@@ -206,66 +206,148 @@ export interface SubscriptionRef {
     active: boolean;
     created: string;
 }
-/** The four firing actions a wakeup can carry (design §4):
- *  - bare     → revive the target node directly (resume:false), no inbox entry.
- *  - noted    → deliver a note to the target's inbox (normal tier).
- *  - deadline → deliver a timeout note to the target's inbox (urgent tier); ≤1 per node.
- *  - spawn    → spawnChild a fresh node from a stored recipe (detached, node_id NULL). */
-export type WakeKind = 'bare' | 'noted' | 'deadline' | 'spawn';
-/** payload for a `bare` wake — `null`, or a label carried only for list rendering. */
-export interface BareWakePayload {
+/** What a trigger enacts when it fires: append/revive an existing node, or
+ *  birth a new one. Orthogonal to HOW it enacts (action_mode) and WHEN it
+ *  fires (trigger_type) — see the node-trigger-grammar spec's §Model. */
+export type TriggerAction = 'msg' | 'new';
+/** HOW a trigger enacts (spec §Model):
+ *  - inbox_message    → append a message to the target's inbox (action='msg').
+ *  - fresh_revive     → revive the target with no inbox entry (action='msg').
+ *  - deadline_message → append an urgent timeout message; ≤1 per node (action='msg').
+ *  - node_birth       → spawnChild a fresh node from a stored recipe (action='new'). */
+export type TriggerActionMode = 'inbox_message' | 'fresh_revive' | 'deadline_message' | 'node_birth';
+/** WHEN a trigger fires:
+ *  - at    → one future clock instant (fire_at).
+ *  - every → recurring clock cadence (fire_at advances by recur).
+ *  - until → a deadline backstop (fire_at; deadline_message only).
+ *  - when  → a daemon-evaluated predicate, polled every eval_every until exit 0
+ *            or wall-clock timeout_at (driven by next_eval_at, not fire_at). */
+export type TriggerType = 'at' | 'every' | 'when' | 'until';
+/** payload for action_mode='fresh_revive' — `null`, or a label carried only for
+ *  `node triggers list` rendering. */
+export interface FreshRevivePayload {
     label?: string;
 }
-/** payload for a `noted` wake — a non-empty note body + a ≤120-char first-line label. */
-export interface NotedWakePayload {
-    body: string;
+/** payload for action_mode='inbox_message' — a non-empty message body + a
+ *  ≤120-char first-line label. `tier` mirrors feed/inbox.ts's InboxTier
+ *  ('critical'|'urgent'|'normal'|'deferred'); inlined rather than imported to
+ *  avoid a canvas→feed value coupling. Absent tier ⇒ daemon enacts at 'normal'.
+ *  `body` is optional ONLY for a `trigger_type='when'` row armed with no inline
+ *  body: the spec's stdout-as-body rule means the daemon fills it from the
+ *  predicate's captured stdout when it fires. Every non-predicate inbox_message
+ *  row (now/clock) still requires a non-empty body — armTrigger enforces this
+ *  per trigger_type, not this type alone. */
+export interface InboxMessagePayload {
+    body?: string;
     label: string;
+    tier?: 'critical' | 'urgent' | 'normal' | 'deferred';
 }
-/** payload for a `deadline` wake — a non-empty timeout note + the machine-readable
- *  `timeout` mirror. The VISIBLE timeout signal rides the RENDERED label/body, not
- *  this flag (inbox digests never surface arbitrary data keys). ≤1 per node. */
-export interface DeadlineWakePayload {
+/** payload for action_mode='deadline_message' — a non-empty timeout note + the
+ *  machine-readable `timeout` mirror. The VISIBLE timeout signal rides the
+ *  RENDERED label/body, not this flag (inbox digests never surface arbitrary
+ *  data keys). ≤1 per node (enforced by the partial unique index on node_id
+ *  WHERE action_mode='deadline_message'). */
+export interface DeadlineMessagePayload {
     body: string;
     timeout: true;
     label: string;
 }
-/** The parsed per-kind payload union (Maj-1): the data-access layer JSON.stringifies
- *  this on write and JSON.parses it back on read, so callers consume `payload.body`
- *  / `payload as SpawnChildOpts` directly with no re-parse. A `spawn` payload is a
- *  SpawnChildOpts recipe with `parent` resolved to a NON-NULL armer id at arm time. */
-export type WakePayload = null | BareWakePayload | NotedWakePayload | DeadlineWakePayload | SpawnChildOpts;
-/** A wakeup row as stored in the `wakeups` table (canvas.db, migration v7). One row =
- *  "do <kind> at fire_at [every recur]". `node_id` is the revive TARGET + node-anchored
- *  cancel anchor (NULL = canvas-detached); `owner_id` is the ARMER (set on every row).
- *  `payload` is the PARSED per-kind union, never the raw JSON string (Maj-1). */
-export interface Wakeup {
-    /** Stable id (caller-supplied at arm time, minted as `wk-${newNodeId()}`). */
-    wakeup_id: string;
-    /** Revive target + node-anchored cancel anchor; NULL = canvas-detached (spawn). */
-    node_id: string | null;
-    /** The node that armed this wake; set on EVERY row. == node_id for a self-alarm. */
+/** The parsed per-action_mode payload union: the data-access layer
+ *  JSON.stringifies this on write and JSON.parses it back on read, so callers
+ *  consume `payload.body` / `payload as SpawnChildOpts` directly with no
+ *  re-parse. The discriminator is the row's OWN `action_mode` column, never
+ *  inferred from payload shape (spec §Data model). A node_birth payload is a
+ *  SpawnChildOpts recipe with `parent` resolved to a NON-NULL armer id at arm
+ *  time. */
+export type TriggerPayload = null | FreshRevivePayload | InboxMessagePayload | DeadlineMessagePayload | SpawnChildOpts;
+/** A predicate trigger's in-flight evaluation state — a trigger has at most one
+ *  evaluation running at a time (spec §Lease / in-flight contract). */
+export type TriggerEvalState = 'idle' | 'running';
+/** A trigger row as stored in the `triggers` table (canvas.db, migration v9).
+ *  One row = "enact <action>/<action_mode> on <trigger_type> [at fire_at |
+ *  polling next_eval_at]". `node_id` is the TARGET + node-anchored cancel
+ *  anchor (NULL = canvas-detached, e.g. a deferred/recurring node_birth);
+ *  `owner_id` is the ARMER, set on every row. `payload` is the PARSED
+ *  per-action_mode union, never the raw JSON string. Predicate-only fields
+ *  (`when_script` through `last_stderr`) are null/idle on every clock trigger. */
+export interface Trigger {
+    /** Stable id (caller-supplied at arm time; preserved from the legacy
+     *  `wakeup_id` for rows migrated from the v7 `wakeups` table). */
+    trigger_id: string;
+    /** The node that armed this trigger; set on EVERY row. == node_id for a
+     *  self-targeted trigger. */
     owner_id: string;
-    /** Next absolute fire time, ISO 8601 UTC; lexicographic <= compare. */
-    fire_at: string;
-    kind: WakeKind;
-    /** NULL = one-shot/adaptive; else the recur JSON the daemon advances. */
+    /** Revive/message/spawn-detach target + node-anchored cancel anchor; NULL =
+     *  canvas-detached (a deferred/recurring node_birth). */
+    node_id: string | null;
+    action: TriggerAction;
+    action_mode: TriggerActionMode;
+    trigger_type: TriggerType;
+    /** Next absolute clock fire time, ISO 8601 UTC; NULL for a predicate trigger
+     *  (which fires via next_eval_at instead). */
+    fire_at: string | null;
+    /** NULL = one-shot/adaptive clock trigger; else the recur JSON the daemon
+     *  advances (interval or cron). A predicate `--every` reuses this same shape
+     *  to express EVALUATION cadence, not a recurring action. */
     recur: string | null;
-    /** Parsed per-kind payload (NULL for a bare one-shot with no label). */
-    payload: WakePayload;
+    payload: TriggerPayload;
+    /** Predicate source for trigger_type='when'; NULL otherwise. */
+    when_script: string | null;
+    /** Predicate evaluation cadence (recur-shaped JSON); NULL otherwise. */
+    eval_every: string | null;
+    /** Next predicate evaluation instant; set to arm time when a predicate
+     *  trigger is armed so the first evaluation is deterministic. NULL for a
+     *  clock trigger. */
+    next_eval_at: string | null;
+    /** Wall-clock predicate expiry; NULL for a clock trigger. */
+    timeout_at: string | null;
+    eval_state: TriggerEvalState;
+    eval_started_at: string | null;
+    eval_pid: number | null;
+    eval_lease_owner: string | null;
+    last_eval_at: string | null;
+    last_exit: number | null;
+    last_stderr: string | null;
     /** ISO 8601, audit/order. */
     created: string;
 }
-/** The arm-a-wake spec (the pinned shared contract). `wakeup_id` is CALLER-SUPPLIED —
- *  the canvas layer never mints ids (importing newNodeId from runtime/nodes.ts would
- *  force a canvas → runtime → canvas cycle, Min-1); the command surface mints
- *  `wk-${newNodeId()}` and passes it in. `owner_id` is required on every row;
- *  `node_id` is NULL for a detached wake (deferred spawn / spawn-cron). */
-export interface ArmWakeSpec {
-    wakeup_id: string;
+/** The arm-a-trigger spec. `trigger_id` is CALLER-SUPPLIED — the canvas layer
+ *  never mints ids (importing newNodeId from runtime/nodes.ts would force a
+ *  canvas → runtime → canvas cycle); the command surface mints the id and
+ *  passes it in. `owner_id` is required on every row; `node_id` is NULL for a
+ *  detached trigger (deferred/recurring node_birth). Predicate fields
+ *  (`when_script` through `timeout_at`) are set together for trigger_type='when'
+ *  and left absent otherwise. */
+export interface ArmTriggerSpec {
+    trigger_id: string;
     node_id?: string | null;
     owner_id: string;
-    fire_at: string;
-    kind: WakeKind;
+    action: TriggerAction;
+    action_mode: TriggerActionMode;
+    trigger_type: TriggerType;
+    fire_at?: string | null;
     recur?: string | null;
-    payload?: WakePayload;
+    payload?: TriggerPayload;
+    when_script?: string | null;
+    eval_every?: string | null;
+    next_eval_at?: string | null;
+    timeout_at?: string | null;
 }
+/** Which triggers a listTriggers call returns. Distinguished by which key is
+ *  present (mirrors listNodes' filter shape):
+ *   - { node }    — triggers anchored to this node (node_id = ?).
+ *   - { owner }   — triggers this node ARMED (owner_id = ?); the per-owner cap count.
+ *   - { subtree } — triggers anchored to any node in this id set (node_id IN (…)).
+ *   - { due }     — CLOCK triggers whose fire_at <= this ISO instant.
+ *   - { canvas }  — every trigger on the canvas. */
+export type TriggerScope = {
+    node: string;
+} | {
+    owner: string;
+} | {
+    subtree: string[];
+} | {
+    due: string;
+} | {
+    canvas: true;
+};

package/dist/core/command.js

@@ -367,16 +367,25 @@ export async function runCli(root, argv) {
     }
     const { node, path, remaining } = walk(root, tokens);
     try {
+        // A root/branch node's `remaining` is only non-empty because walk hit
+        // -h/--help or an unmatched child name (a leaf always consumes the rest
+        // of the path itself). So a non-help leading token here is always the
+        // latter: reject it as an unknown path before rendering any help, even
+        // when a -h/--help token also appears later in `remaining` — otherwise a
+        // removed/misspelled subcommand followed by -h would render the parent's
+        // help and exit 0 instead of failing.
+        if ((node.kind === 'root' || node.kind === 'branch')
+            && remaining.length > 0
+            && remaining[0] !== '-h' && remaining[0] !== '--help') {
+            throw unknownPathError(node, path, remaining[0]);
+        }
         // Help anywhere in remaining tokens → print node help and exit
         if (helpRequested(remaining)) {
             process.stdout.write(renderNode(node) + '\n');
             process.exit(ExitCode.SUCCESS);
         }
-        // Bare branch or bare root (no -h, but no leaf selected) → help surface
+        // Bare branch or bare root (no -h, remaining fully consumed) → help surface
         if (node.kind === 'root' || node.kind === 'branch') {
-            if (remaining.length > 0) {
-                throw unknownPathError(node, path, remaining[0]);
-            }
             process.stdout.write(renderNode(node) + '\n');
             process.exit(ExitCode.SUCCESS);
         }