@north-light/crouter 0.3.154

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

@@ -0,0 +1,358 @@
+import type { NodeMeta, NodeIdentity, NodeRow, NodeStatus, ExitIntent, SubscriptionRef, Mode, Lifecycle } from './types.js';
+/** 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 declare function createNode(meta: NodeMeta): NodeMeta;
+/** The canonical node record: durable identity (meta.json) ∪ authoritative
+ *  runtime (the row). Null if unknown. */
+export declare function getNode(nodeId: string): NodeMeta | null;
+/** The indexed row (from the db) — cheap for queries that don't need full meta. */
+export declare function getRow(nodeId: string): NodeRow | null;
+/** 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 declare function getRowByPane(pane: string): NodeRow | 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 declare function updateNode(nodeId: string, patch: Partial<NodeIdentity>): NodeMeta;
+/** Set a node's status. Atomic single-column write. */
+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;
+/** 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 declare function setPresence(nodeId: string, presence: {
+    tmux_session?: string | null;
+    window?: string | null;
+    pane?: string | null;
+}): void;
+/** Record the live pi pid (daemon liveness signal) PLUS its launch-time
+ *  identity fingerprint, in one atomic write (crouter#98 review finding 1):
+ *  `capturePidIdentities([pid])` is a signal-0-adjacent `ps -p <pid>` probe
+ *  taken RIGHT NOW, while `pid` is the process we just spawned/bound and
+ *  therefore definitely still exists — this is the LAUNCH-time baseline
+ *  `headlessBrokerHost.teardown()` later compares against before signaling
+ *  anything. A failed probe (rare — `ps` itself misbehaving) or a probe that
+ *  finds no row for `pid` (raced away in the instant between spawn and this
+ *  call) both write `NULL`: no baseline recorded, so the teardown guard fails
+ *  open exactly like a node booted before this column existed — never a false
+ *  identity that could itself cause a false mismatch later. */
+export declare function recordPid(nodeId: string, pid: number): void;
+/** Clear the pi pid (window-backed relaunch, before the fresh pi re-records it)
+ *  AND its recorded launch-time identity — the two are written together by
+ *  `recordPid` and must be cleared together, or a subsequent relaunch that
+ *  reuses the pid namespace could compare its own fresh pid against a STALE
+ *  identity left over from the pid this row held before. */
+export declare function clearPid(nodeId: string): void;
+/** ONE-TIME completion of the boot-scoped-identity format migration, run once
+ *  at daemon startup (the natural boot-reconciliation chokepoint, right after
+ *  `reconcileBootLiveness`). It closes the gap the `identitiesMatch` legacy
+ *  lane only TOLERATES: a broker that survives an in-place crouter upgrade
+ *  keeps its old `lstart#ticks` row indefinitely (`recordPid` only fires on
+ *  launch/revive/session_start), so the cross-boot ticks-collision exposure the
+ *  boot-scoped base was added to close never provably shuts for those rows.
+ *
+ *  For every row whose RECORDED identity is legacy-format while this platform
+ *  now composes new-format (a readable kernel boot_id):
+ *   - if the recorded pid's CURRENT live identity matches the recorded one via
+ *     the migration lane (same live process, `identitiesMatch` true) AND that
+ *     current identity is itself boot-scoped — re-record it with the new
+ *     composer, completing the migration in place;
+ *   - otherwise (pid gone, probe failed, reused — no match, or no readable
+ *     boot_id for it) — leave the row untouched for the normal liveness
+ *     handling that already runs each tick.
+ *
+ *  After this runs once, the legacy compare lane only ever engages for
+ *  genuinely no-boot_id platforms. NOT a per-caller reconciliation layer — a
+ *  single startup sweep. `captureIdentity` is injectable for unit tests.
+ *
+ *  GATED on proven same-boot provenance by its caller (daemon startup runs it
+ *  only when `reconcileBootLiveness` returned `sameBootProven` — see
+ *  `bootProvenSame`). This is what makes a bare ticks match safe to bless as a
+ *  current-boot identity: without that proof an equal-ticks collision with an
+ *  unrelated process from a DIFFERENT boot could be rewritten as
+ *  `<currentBootId>#<ticks>`, permanently baptizing a stranger.
+ *
+ *  Not transactional by design: it never HOLDS the write lock across the (slow,
+ *  per-row) `ps` probe. Each re-record is a compare-and-swap single-row UPDATE
+ *  constrained by ALL three snapshotted values (`node_id`, `pi_pid`,
+ *  `pi_pid_identity`), counted only when a row actually changed. So if the old
+ *  broker exits and a concurrent revive atomically records a fresh
+ *  `(pi_pid, pi_pid_identity)` between this sweep's probe and its update, the
+ *  CAS matches zero rows and the migration is skipped rather than clobbering
+ *  the newer identity with the stale one. */
+export declare function migrateLegacyPidIdentities(captureIdentity?: (pid: number) => string | undefined): {
+    migrated: string[];
+};
+/** All rows, optionally filtered by status. Unclaimed warm spares are excluded. */
+export declare function listNodes(filter?: {
+    status?: NodeStatus | NodeStatus[];
+}): NodeRow[];
+/** Mark an already-spawned node as an unclaimed spare for `recipeKey`. Hides it
+ *  from every listing until it is claimed. */
+export declare function registerWarmSpare(nodeId: string, recipeKey: string): void;
+/** Take a parked spare OUT of the pool without claiming it — the reaper's
+ *  first move. Returns false when the marker was already gone (a concurrent
+ *  claim won it), which is the reaper's signal to leave that node alone: it is
+ *  somebody's live conversation now, not a spare. Deleting the marker under the
+ *  write lock is exactly what `claimWarmSpare` does, so the two can never both
+ *  succeed on the same node. */
+export declare function unregisterWarmSpare(nodeId: string): boolean;
+/** One parked spare, joined to the node row a claim/reap needs to judge it. */
+export interface WarmSpareRow {
+    node_id: string;
+    recipe_key: string;
+    /** Mint time — the claim order and the TTL clock. */
+    created: string;
+    status: NodeStatus;
+    pi_pid: number | null;
+    pi_pid_identity: string | null;
+}
+/** Every parked spare, oldest first — what the reaper (`runtime/warm-pool.ts`
+ *  `reapStaleSpares`) sweeps. Deliberately NOT filtered by liveness: judging a
+ *  spare is the caller's job. */
+export declare function listWarmSpares(): WarmSpareRow[];
+/** True while `nodeId` is an UNCLAIMED spare — nobody owns this conversation
+ *  yet. `registerWarmSpare` runs the instant the row exists and BEFORE the
+ *  broker launch, and a claim deletes the marker atomically, so this is a
+ *  reliable read from inside the booting engine (the context-intro extension
+ *  asks it at `session_start` to withhold bearings that would otherwise assert
+ *  the spare's placeholder persona instead of its eventual claimant's). */
+export declare function isWarmSpare(nodeId: string): boolean;
+/** Hand out the oldest CLAIMABLE spare matching `recipeKey`, or null when the
+ *  pool has none. The select+delete run inside ONE canvas write-lock
+ *  transaction, so two concurrent creates can never be handed the same spare.
+ *  A spare whose broker is gone is skipped here and reaped by
+ *  `reapStaleSpares` — nothing ever resumes a spare (the recovery sweep reads
+ *  `listNodes`, which hides them), so a dead spare is garbage, not a parked one.
+ *
+ *  The claim also restamps the row's `created` to `created` — birth time is a
+ *  spare's MINT time, and consumers sort conversations on it, so an hour-old
+ *  spare must not sort as an hour-old conversation. This is the one sanctioned
+ *  write of `created` after birth (`upsertRow` deliberately never touches it);
+ *  the caller mirrors the same stamp into meta.json. */
+export declare function claimWarmSpare(recipeKey: string, created: string): string | null;
+/** How many CLAIMABLE spares are parked for `recipeKey` (the depth check a
+ *  refill reads before minting). Uses the same liveness test as the claim, so a
+ *  spare the claim would skip can never hold the pool at depth 1 and starve
+ *  every later create of a warm start. */
+export declare function warmSpareCount(recipeKey: string): number;
+/** Direct children of `id`, oldest first — an indexed point query
+ *  (`idx_nodes_parent`) instead of a full-table `listNodes()` scan. */
+export declare function childrenOf(id: string): string[];
+/** One lean roster row: only the `nodes` columns already native to the row
+ *  (no meta.json read). Backs `GET /v1/canvas/roster` — the recurring attach /
+ *  browser topology poll, distinct from the enriched per-row
+ *  `dashboardRowsAll`+`enrichRows` snapshot (`GET /v1/canvas/snapshot`). */
+export interface RosterRow {
+    node_id: string;
+    name: string;
+    kind: string;
+    mode: Mode;
+    lifecycle: Lifecycle;
+    status: NodeStatus;
+    cwd: string;
+    host_kind: 'tmux' | 'broker' | null;
+    parent: string | null;
+    created: string;
+}
+/** Every node's lean roster row, oldest first — a single scan indexed by
+ *  `idx_nodes_created`. No per-row `getNode`/meta.json read, no N+1. */
+export declare function rosterNodes(): RosterRow[];
+/** One `subscribes_to` edge, both endpoints — the roster's topology half. */
+export interface RosterEdge {
+    from_id: string;
+    to_id: string;
+    active: boolean;
+    created: string;
+}
+/** Every `subscribes_to` edge (passive + multiple preserved, never collapsed) —
+ *  a single scan indexed by `idx_edges_from`/`idx_edges_to` (composite
+ *  `(type, from_id|to_id)`, so a bare `type` predicate still uses one of
+ *  them). Paired with `rosterNodes()` as the roster's exactly-two-query
+ *  contract. */
+export declare function rosterEdges(): RosterEdge[];
+/** Resumable ROOT conversations pinned to `cwd`, most-recently-created first.
+ *  A "root" is the top of a spine (`parent IS NULL`) that is a real
+ *  conversation (not a `kind:'human'` ask) and still resumable (`active`/`idle`,
+ *  never a `done`/`dead`/`canceled` node). This backs the front-door
+ *  `crtr -c`/`-r` resume: cwd is the key (the Claude-Code mental model — "my
+ *  last session HERE"), so it never teleports across projects. */
+export declare function listResumableRoots(cwd: string): NodeRow[];
+/** Record `A subscribes_to B` — A receives B's output. active=true wakes A on
+ *  emit; passive accumulates pointers without a wake. Mutable; callable by anyone. */
+export declare function subscribe(subscriber: string, publisher: string, active?: boolean): void;
+/** Drop a subscription edge. */
+export declare function unsubscribe(subscriber: string, publisher: string): void;
+/** Flip an existing subscription's wake behavior. */
+export declare function setSubscriptionActive(subscriber: string, publisher: string, active: boolean): void;
+/** Record the audit-only `child spawned_by parent` edge. */
+export declare function recordSpawn(child: string, parent: string): void;
+/** Who subscribes to `publisher` — the targets a push fans out to. */
+export declare function subscribersOf(publisher: string): SubscriptionRef[];
+/** Who `subscriber` subscribes to — its reports / the nodes feeding it. */
+export declare function subscriptionsOf(subscriber: string): SubscriptionRef[];
+/** 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. */
+export declare function view(root: string): string[];
+/** Stop-guard primitive: does this node hold an *active* subscription to a node
+ *  that's still live (active|idle) — i.e. something that can actually wake it?
+ *  If so, stopping is a legitimate await; if not, it must finish or escalate. */
+export declare function hasActiveLiveSubscription(nodeId: string): boolean;
+/** Whether a node explicitly awaits a controller that can still deliver. A
+ * parent relationship never implies this wait; the node must declare it. */
+export declare function hasLiveMessageWait(nodeId: string): boolean;
+/** Settle an explicit message wait before appending the qualifying delivery.
+ * This ordering makes the delivery's one wake observe cleared durable state. */
+export declare function setMessageWait(nodeId: string, controller: string): void;
+/** Append a qualifying delivery and settle its matching wait while holding the
+ * canvas write lock. A concurrent `node wait controller` runs before or after this whole
+ * boundary, never between the durable inbox append and its compare-and-clear. */
+export declare function deliverAndSettleMessageWait<T>(nodeId: string, from: string | null, deliver: () => T): T;
+/** Write one controller-death notice and settle only the still-current dead
+ * wait. The check, notice append, and clear share one canvas write boundary. */
+export declare function settleDeadMessageWait<T>(nodeId: string, controller: string, deliver: () => T): T | null;
+/** The outcome of {@link withFreshTerminalGuard} — exactly one of three
+ *  tagged states, never conflated:
+ *  - `'ran'`: the fresh read found a live, non-terminal row and `body` (the
+ *    guarded write) executed; its result is carried back.
+ *  - `'terminal'`: the row exists but is already terminal by `isTerminal`'s
+ *    predicate — `body` never ran. The snapshot (`status`, `final_report`) is
+ *    reported for the caller's error message.
+ *  - `'missing'`: no row for `nodeId` at all (deleted between the caller's
+ *    own selection/validation and this guard's fresh read) — `body` never ran.
+ *    A missing target is NOT a terminal target: it carries no `status`/
+ *    `final_report` to report, and every caller must fail loud with its own
+ *    not-found contract rather than treat it as either a successful run or a
+ *    terminal rejection. */
+export type TerminalGuardResult<T> = {
+    kind: 'ran';
+    result: T;
+} | {
+    kind: 'terminal';
+    status: NodeStatus;
+    final_report: string | null;
+} | {
+    kind: 'missing';
+};
+/** #343: close the TOCTOU between checking a target has a natural cycle ahead
+ *  of it and the write that depends on that (for example, a deferred inbox
+ *  append). Fresh-reads `nodeId`'s
+ *  (status, final_report) and either runs `body` (a write) or short-circuits
+ *  with a `'terminal'`/`'missing'` outcome — the read and `body`'s write share
+ *  ONE canvas write-lock boundary (`withCanvasWrite`'s `BEGIN IMMEDIATE`), so
+ *  a concurrent finish/cancel/finalization/deletion either commits entirely
+ *  before this reads (observed here, `body` never runs) or entirely after
+ *  (`body` completes uncontested) — never in the gap a separate check-then-
+ *  write left open. Pass the shared `hasNoNaturalCycle` predicate rather than
+ *  a bespoke one so the two never drift.
+ *
+ *  #343 review (Major): a dangling `nodeId` — the row deleted after the
+ *  caller's own selection but before this guard's fresh read — MUST NEVER run
+ *  `body`. Reporting `'missing'` distinctly from `'terminal'` (rather than
+ *  folding it into either the terminal branch or a fabricated "safe" empty
+ *  snapshot) keeps the two failure shapes from being conflated: a terminal
+ *  target has a real `status`/`final_report` to report and its own
+ *  `deferred_no_natural_cycle`-style rejection, while a missing target has
+ *  nothing to report and belongs to the caller's own not-found contract. */
+export declare function withFreshTerminalGuard<T>(nodeId: string, isTerminal: (row: {
+    status: NodeStatus;
+    final_report: string | null;
+}) => boolean, body: () => T): TerminalGuardResult<T>;
+/** 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 `spawned_by` (fallback: `parent` for legacy metas). */
+export declare function rebuildIndex(): void;
+/** A node selected for pruning (or that would be, under --dry-run). */
+export interface PrunedNode {
+    node_id: string;
+    status: NodeStatus;
+    created: string;
+}
+export interface PruneResult {
+    /** The nodes pruned (or, under dryRun, the nodes that WOULD be pruned). */
+    pruned: PrunedNode[];
+    dryRun: boolean;
+}
+/** {@link deleteNode}'s result: whether it actually deleted the node. */
+export interface DeleteNodeResult {
+    deleted: boolean;
+}
+/** Hard-delete ONE node: drop its row (the edges→nodes FK, ON DELETE CASCADE,
+ *  GCs its edges) and remove its on-disk `nodes/<id>/` dir. The single-node
+ *  analogue of {@link pruneNodes}, for IMMEDIATE reaping — e.g. an empty node the
+ *  user closed or detached from. An open managed worktree is never deleted: its
+ *  node retains the ownership needed for `node worktree close`. Nor is a node
+ *  with a LIVE (`armed`/`pending`) follow-up human-work receipt — its report payload
+ *  is still needed for delivery (integrated-review Major-2). Pure persisted-
+ *  state removal: the caller MUST have already torn down the broker engine +
+ *  viewer (this does not signal any process). The node row and its FK-coupled
+ *  state are removed in one canvas write boundary. Best-effort dir removal
+ *  follows the commit. */
+export declare function deleteNode(nodeId: string): DeleteNodeResult;
+/** Retention sweep: remove TERMINAL nodes (status dead | done | canceled) whose
+ *  `created` is older than `ttlDays`, bounding the otherwise-unbounded growth of
+ *  node rows + dirs. Open managed-worktree nodes are retained so their checkout
+ *  remains owned until `node worktree close`. 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.
+ *
+ *  With `includeStale`, ALSO prunes nominally-live (active | idle) nodes past the
+ *  TTL whose process is provably gone — `pi_pid` is NULL or no longer alive. This
+ *  reaps stale roots (a bare `crtr` whose pi died without the row transitioning),
+ *  which the daemon's supervision never reconciled. A genuinely-running node keeps
+ *  a live `pi_pid`, so it is protected, as is the CALLER ($CRTR_NODE_ID). Without
+ *  the flag, active | idle are NEVER touched (the daemon's domain).
+ *
+ *  Row deletes run in ONE transaction, so the sweep is all-or-nothing. 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 declare function pruneNodes(opts: {
+    ttlDays: number;
+    dryRun?: boolean;
+    includeStale?: boolean;
+}): PruneResult;
+/** Count-based retention sweep: retain the `maxNodes` MOST-RECENTLY-ACTIVE
+ *  nodes plus every protected node, so the real retained floor is
+ *  `max(maxNodes, protectedCount)`. Bounds the otherwise-unbounded growth the
+ *  TTL sweep can't (a canvas that never crosses the TTL still grows without
+ *  limit).
+ *
+ *  Protected (never a prune candidate, regardless of recency rank): any
+ *  non-terminal node — status active|idle — REGARDLESS of `pi_pid` liveness,
+ *  a node with an open managed worktree, and a node with a LIVE
+ *  (`armed`/`pending`) follow-up human-work receipt. A crashed-but-non-terminal row
+ *  (dead pid, status still active/idle) must survive for daemon crash-recovery
+ *  to resume, an open worktree must retain its node ownership until
+ *  `node worktree close`, and a live consult receipt's report payload is still
+ *  needed for delivery (integrated-review Major-2); none of the three is
+ *  eligible for count-based pruning. The caller ($CRTR_NODE_ID) is also always
+ *  protected.
+ *
+ *  Algorithm: order ALL nodes by recency DESC (telemetry.json mtime, falling back
+ *  to `created`); `target = max(maxNodes, protectedCount)`; delete every node
+ *  ranked beyond `target` (0-indexed rank >= target) that is NOT protected and
+ *  NOT the caller. Retained = all protected + the newest terminal nodes up to
+ *  `target`.
+ *
+ *  Mirrors {@link pruneNodes} exactly for the delete (shared `deletePrunedNodes`:
+ *  transactioned row sweep + FK edge cascade + best-effort dir removal). `dryRun`
+ *  reports the candidate set and deletes NOTHING. */
+export declare function pruneToLimit(opts: {
+    maxNodes: number;
+    dryRun?: boolean;
+}): PruneResult;