@north-light/api 0.3.579 → 0.3.587

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

@@ -0,0 +1,409 @@
+import { type CanvasDb } from './db.js';
+import type { ExitIntent, Lifecycle, Mode, NodeIdentity, NodeMeta, NodeOutcomeKind, NodeRow, NodeStatus, TerminalReason } from './types.js';
+export interface OutcomeDeliveryBinding {
+    actionName: string;
+    argv: string[];
+    cwd: string;
+    configOrigin: string;
+    payload?: unknown;
+}
+export declare function assertRunNotDeleting(db: CanvasDb, runId: string): Promise<void>;
+/** Create a SQL-authoritative node, then ensure its artifact directories exist. */
+export declare function createNode(meta: NodeMeta, opts?: {
+    outcomeDelivery?: OutcomeDeliveryBinding;
+    withinCreate?: (db: CanvasDb, row: NodeMeta) => Promise<void> | void;
+}): Promise<NodeMeta>;
+/** The canonical node record, hydrated from SQL. Null if unknown. */
+export declare function getNode(nodeId: string): Promise<NodeMeta | null>;
+/** The canonical node records for `nodeIds` in the order given, read with their worktrees in one query. Unknown ids are skipped. */
+export declare function getNodes(nodeIds: readonly string[]): Promise<NodeMeta[]>;
+export type CreateRequestState = 'reserved' | 'warm_claimed' | 'complete';
+export interface CreateRequestRecord {
+    requestKey: string;
+    nodeId: string | null;
+    state: CreateRequestState;
+}
+export declare function findCreateRequest(requestKey: string): Promise<CreateRequestRecord | null>;
+/** Reserve an idempotency key before creation. A null node id means the request
+ *  has not yet selected a cold-birth identity or claimed a warm spare. */
+export declare function reserveCreateRequest(requestKey: string): Promise<CreateRequestRecord>;
+/** Delete keys past their recovery window; returns how many were removed. */
+export declare function pruneExpiredCreateRequests(now?: number): Promise<number>;
+/** Bind a reserved key to the node it created (state `complete`). The mapping is
+ *  durable so a retry after a daemon handover returns the original node. */
+export declare function recordCreateRequestNode(requestKey: string, nodeId: string): Promise<void>;
+/** Reserve a cold-birth node id for a key (state stays `reserved`) so a retry
+ *  after a daemon restart resumes the same identity instead of minting another.
+ *  Only the first caller binds: two API processes holding one unbound key race
+ *  here, and each gets back the id the key actually names. */
+export declare function reserveCreateRequestNode(requestKey: string, nodeId: string): Promise<string | null>;
+export declare function completeCreateRequest(requestKey: string, nodeId: string): Promise<void>;
+/** Forget an unserved reservation after a pre-birth failure. A record that
+ *  names a durable node is never removed by this path. */
+export declare function abandonCreateRequest(requestKey: string, nodeId: string | null): Promise<void>;
+export declare function canonicalSessionFile(sessionFile: string): string;
+/** Resolve the crouter node that owns one exact Pi session file. */
+export declare function findNodeBySessionFile(sessionFile: string): Promise<NodeMeta | null>;
+/** The indexed row (from the db) — cheap for queries that don't need full meta. */
+export declare function getRow(nodeId: string): Promise<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): Promise<NodeRow | null>;
+/** Nodes whose persisted spawn deadline has elapsed and that remain live work. */
+export declare function dueNodeDeadlines(nowIso: string): Promise<NodeRow[]>;
+/** Write a claimed warm spare's deadline before it is handed to its caller. */
+export declare function setNodeDeadline(nodeId: string, deadlineAt: string | null): Promise<boolean>;
+/** Shift active/idle profile deadlines by a completed profile pause duration. */
+export declare function shiftProfileNodeDeadlines(profileId: string, pauseDurationMs: number): Promise<number>;
+type NodeUpdate = Partial<Omit<NodeIdentity, 'node_id' | 'pi_session_id' | 'pi_session_file' | 'managed_worktree'>>;
+/** Update node identity/configuration columns. Sessions and worktrees have named stores. */
+export declare function updateNode(nodeId: string, patch: NodeUpdate): Promise<NodeMeta>;
+/** Set a node's status. Atomic single-column write. */
+export declare function setStatus(nodeId: string, status: NodeStatus): Promise<void>;
+/** Set a node's exit intent. Atomic single-column write. */
+export declare function setIntent(nodeId: string, intent: ExitIntent): Promise<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;
+    terminal_reason?: TerminalReason | null;
+}, opts?: {
+    fromStatuses?: readonly NodeStatus[];
+    requireNoFinalReport?: boolean;
+    /** Present ⇒ latch an outcome and make an armed delivery pending atomically. */
+    outcome?: {
+        kind: NodeOutcomeKind;
+        reason: TerminalReason;
+        detailJson: string | null;
+        at: string;
+        /** Replace a prior outcome after a run resumes or when its final is committed. */
+        supersede?: boolean;
+        /** Action-independent document composed before the conditional latch. */
+        documentJson?: string | null;
+    };
+}): Promise<number>;
+/** Read a node's committed-final latch pointer. Pure read, no side effect. */
+export declare function getFinalReport(nodeId: string): Promise<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): Promise<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
+ *  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;
+}): Promise<void>;
+export declare function recordLaunch(nodeId: string, at: string): Promise<void>;
+export declare function recordSettledTurn(nodeId: string, at: string): Promise<void>;
+export declare function setFrozen(nodeId: string, at: string): Promise<void>;
+export declare function clearFrozen(nodeId: string): Promise<void>;
+export declare function recordRespawnAttempt(nodeId: string, attempt: {
+    failures: number;
+    notBefore: string | null;
+}): Promise<void>;
+export declare function listNodesByProfile(profileId: string): Promise<NodeMeta[]>;
+/** Browse's first frame: select only fields its rows/tree use. Keep the fault and
+ * turn columns for rowFrom's live fault/streaming semantics, but never hydrate
+ * outcomes, placement, metadata or the (often large) telemetry activity text. */
+export declare function browseNodes(): Promise<NodeRow[]>;
+/** All rows, optionally filtered by status and terminal execution traces. Unclaimed warm spares are excluded. */
+export declare function updateNodeTelemetry(nodeId: string, telemetry: {
+    tokensIn: number;
+    contextTokens: number | null;
+    lastActivity: string | null;
+    updatedAt: string;
+}): Promise<void>;
+export interface GraphNodeRow {
+    node_id: string;
+    name: string;
+    description: string | null;
+    cycles: number | null;
+    kind: string;
+    status: NodeStatus;
+    frozen_at: string | null;
+    pi_pid: number | null;
+    telemetry_context_tokens: number | null;
+    telemetry_last_activity: string | null;
+    fault: NodeRow['fault'];
+    streaming: boolean;
+}
+/** Stored fields the attach graph displays, plus the two live execution cues it
+ * needs. This keeps the interactive graph off the full node-summary projection
+ * and its unused runtime, outcome, and placement fields. */
+export declare function graphNodes(): Promise<GraphNodeRow[]>;
+export interface ListNodesFilter {
+    status?: NodeStatus | NodeStatus[];
+    withRecordedPid?: boolean;
+    withRecordedPidOrFrozen?: boolean;
+    /** Only the navigable nodes below this node (excluding it), resolved by one recursive query. */
+    under?: string;
+    /** With `under`: the node itself plus every node below it, human ask nodes included (the scope `node inspect list --under` shows). */
+    underInclusive?: boolean;
+    lifecycle?: string;
+    kind?: string;
+    mode?: string;
+    profileId?: string;
+    profilePrefix?: string;
+    parent?: string;
+    topLevel?: boolean;
+    /** Only nodes whose manager has no node row. */
+    hanging?: boolean;
+}
+export declare function listNodes(filter?: ListNodesFilter): Promise<NodeRow[]>;
+/** Placement-only terminal rows for the daemon's residue pass. These columns
+ * preserve lastActivityMs's timestamp inputs and the teardown event fields;
+ * unlike node_rows, the nodes table needs no execution/session/fault joins. */
+export type TerminalPlacementResidue = Pick<NodeRow, 'node_id' | 'created' | 'launched_at' | 'last_settled_at' | 'finalized_at' | 'outcome_at' | 'last_activity_at' | 'pane' | 'window' | 'tmux_session'>;
+export declare const terminalPlacementResidueSql = "SELECT\n      node_id, created, launched_at, last_settled_at, finalized_at,\n      outcome_at, last_activity_at, pane, \"window\", tmux_session\n    FROM nodes\n    WHERE node_id NOT IN (SELECT node_id FROM warm_pool)\n      AND status IN ('done', 'canceled', 'dead')\n      AND (pane IS NOT NULL OR \"window\" IS NOT NULL OR tmux_session IS NOT NULL)\n    ORDER BY created";
+export declare function listTerminalPlacementResidue(): Promise<TerminalPlacementResidue[]>;
+/** The daemon's complete supervision set. Live rows participate regardless of
+ * PID; terminal rows participate only while they retain a PID or freeze mark. */
+export declare const nodesForSupervisionSql = "WITH candidates AS MATERIALIZED (\n    SELECT node_id FROM nodes WHERE status IN ('active', 'idle')\n    UNION\n    SELECT node_id FROM nodes\n      WHERE frozen_at IS NOT NULL AND status IN ('done', 'canceled', 'dead')\n    UNION\n    SELECT node_id FROM executions\n      WHERE state != 'exited' AND state = 'running' AND pid IS NOT NULL\n  )\n  SELECT v.* FROM candidates c CROSS JOIN node_rows v\n  WHERE v.node_id = c.node_id\n    AND v.node_id NOT IN (SELECT node_id FROM warm_pool)\n    AND v.kind != 'human'\n    AND (v.status IN ('active', 'idle') OR (v.status IN ('done', 'canceled', 'dead') AND (v.pi_pid IS NOT NULL OR v.frozen_at IS NOT NULL)))\n  ORDER BY v.created";
+export declare function listNodesForSupervision(): Promise<NodeRow[]>;
+/** A parked resident the runtime may reopen when wake mail reaches it: `done` +
+ *  `intent='parked'`, resident, no final latch, and not being deleted. Finalized,
+ *  canceled, dead, terminal-lifecycle and deleting nodes are never reopened by mail.
+ *  The SQL form of `isParkedResident` (runtime/lifecycle.ts), which must change with it; `n` is a `nodes` row. */
+export declare const PARKED_RESIDENT_SQL: (n: string) => string;
+/** A node the runtime can still bring back to life, so its cwd must keep existing: a live row
+ *  (`active`/`idle`), a parked resident the lifecycle tick reopens when wake mail arrives
+ *  (`PARKED_RESIDENT_SQL`), or a terminal row with no final latch that still carries a frozen
+ *  mark, which the tick thaws (`node-lifecycle/tick.ts` `classifyRow`). `n` is a `nodes` row. */
+export declare const RESUMABLE_NODE_SQL: (n: string) => string;
+/** Every resumable node (`RESUMABLE_NODE_SQL`) other than `ownerId`, with the cwd it will run in. */
+export declare function resumableNodeCwds(ownerId: string): Promise<Array<{
+    node_id: string;
+    cwd: string;
+}>>;
+/** Parked residents with unseen wake mail (`UNSEEN_WAKE_MAIL_SQL`), which nothing else
+ *  launches: the lifecycle tick reopens them. Each parked resident seeks its own mail
+ *  through `deliveries_destination`. */
+export declare function listParkedResidentsWithWakeMail(): Promise<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): Promise<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): Promise<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(): Promise<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): Promise<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 daemon's row query
+ *  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. */
+export declare function claimWarmSpare(recipeKey: string, created: string, opts?: {
+    deadlineAt?: string;
+    outcomeDelivery?: OutcomeDeliveryBinding;
+    requestKey?: string;
+}): Promise<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): Promise<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): Promise<string[]>;
+/** One lean roster row: only the `nodes` columns needed by the roster. 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;
+    description: string | null;
+}
+/** Every node's lean roster row, oldest first — a single scan indexed by
+ *  `idx_nodes_created`, with no per-row hydration or N+1 query. */
+export declare function rosterNodes(): Promise<RosterRow[]>;
+/** 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): Promise<NodeRow[]>;
+export * from './tree.js';
+/** 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';
+};
+/** 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, frozen_at) and either runs `body` (a write) or short-circuits
+ *  with a `'terminal'`/`'missing'` outcome — the read takes the node row
+ *  `FOR UPDATE` and holds it through `body`'s write in the same transaction, so
+ *  a concurrent finish/cancel/finalization/deletion either commits entirely
+ *  before this reads (observed here, `body` never runs) or waits on the row
+ *  until `body` commits — 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.
+ *
+ *  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;
+    frozen_at: string | null;
+}) => boolean, body: () => Promise<T> | T): Promise<TerminalGuardResult<T>>;
+/** 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;
+}
+/** Whether a row may be removed by an automatic collection sweep. */
+export declare function isCollectible(row: NodeRow, opts?: {
+    pastTtl?: boolean;
+}): Promise<boolean>;
+/** {@link deleteNode}'s result: whether it actually deleted the node. */
+export interface DeleteNodeResult {
+    deleted: boolean;
+}
+/** A node's files, located while its row still names its app. */
+export interface NodeFiles {
+    nodeId: string;
+    app: string | null;
+}
+export declare function nodeFiles(nodeId: string): Promise<NodeFiles>;
+/** Remove every directory a deleted node owned. A conversation another node
+ *  still references keeps its file, and so its conversations directory. */
+export declare function removeNodeFiles(files: NodeFiles): Promise<void>;
+/** Delete ONE node with what it owns ({@link deleteNodeWithOwned}) 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`. 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): Promise<DeleteNodeResult>;
+/** Hard-delete a validated set of nodes in one row transaction, then remove
+ *  their directories. The caller must tear down engines and viewers first. */
+export declare function deleteNodes(nodeIds: readonly string[]): Promise<string[]>;
+/** Retention sweep: remove TERMINAL nodes (status dead | done | canceled) whose
+ *  last activity ({@link lastActivityMs}) is older than `ttlDays`, bounding the
+ *  otherwise-unbounded growth of node rows + dirs. Only {@link isCollectible}
+ *  rows qualify, and never one `held` claims. Each node is deleted with what it
+ *  owns ({@link deleteNodeWithOwned}); 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 and that nothing will bring back: no live
+ *  `pi_pid`, not sleeping until a wake (`idle-release`), no unseen wake mail,
+ *  not frozen, not in respawn backoff, not an app run, not held, and never the CALLER
+ *  ($CRTR_NODE_ID). Without the flag, active | idle are NEVER touched.
+ *
+ *  Each node's rows change in its own transaction. 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;
+    held: (nodeId: string) => Promise<boolean>;
+    dryRun?: boolean;
+    includeStale?: boolean;
+    removeDirs?: (dirs: string[]) => void;
+}): Promise<PruneResult>;
+/** A node's most recent activity (epoch ms): the latest of its lifecycle
+ *  timestamps (created, launched, settled, finalized, outcome, last run event)
+ *  and the mtime of `job/telemetry.json`, which every turn_end rewrites. 0 when
+ *  none is readable. The single clock every retention decision uses. Never throws. */
+export declare function lastActivityMs(row: Pick<NodeRow, 'node_id' | 'created' | 'launched_at' | 'last_settled_at' | 'finalized_at' | 'outcome_at' | 'last_activity_at'>): number;
+/** Count-based retention sweep: keep every row that is not collectible or that
+ *  `held` claims, plus the most recently active collectible rows up to
+ *  `maxNodes` in total, so the real retained floor is `max(maxNodes,
+ *  retainedCount)`. Bounds the growth the TTL sweep can't (a canvas that never
+ *  crosses the TTL still grows without limit). Recency is {@link lastActivityMs}.
+ *
+ *  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;
+    held: (nodeId: string) => Promise<boolean>;
+    dryRun?: boolean;
+}): Promise<PruneResult>;