@north-light/api 0.3.580 → 0.3.588

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

@@ -0,0 +1,322 @@
+import { type CanvasDb } from './db.js';
+export type CronScope = 'profile' | 'global';
+export type CronOverlap = 'skip' | 'queue' | 'replace';
+export type CronOnOutput = 'silent' | 'on-failure' | 'always' | 'on-change';
+export type CronState = 'active' | 'paused';
+export type CronRunState = 'idle' | 'running';
+/** The decoded delivery target of a stored cron sink. */
+export type ParsedCronSink = {
+    kind: 'node';
+    node: string;
+} | {
+    kind: 'spawn';
+    spawn: string;
+} | {
+    kind: 'human';
+} | null;
+/** A hydrated `crons` row. */
+export interface Cron {
+    cron_id: string;
+    name: string;
+    created_by: string | null;
+    grantee: string;
+    /** The user the app acts for (the cron principal's `sub`). */
+    sub: string;
+    /** The grant the cron runs under; null only for `app:terminal` with no issuer, or a migrated row with no grant. */
+    grant_id: string | null;
+    /** Scopes the cron is bounded to; null for person-armed terminal crons and crons armed from an exec execution (the grant's whole current set is the ceiling). */
+    scopes: string[] | null;
+    /** Armed by a `POST /v1/exec` process: every node it births checks model sign-in first. */
+    armed_from_exec: boolean;
+    /** The canvas run of the arming node (confinement; `run.cancel` later). Not the per-fire execution id. */
+    origin_run_id: string | null;
+    /** The running fire's execution id (`CRTR_RUN_ID`) while leased; null when idle. */
+    run_execution_id: string | null;
+    /** Frozen from the creating node; never recomputed from a later node state. */
+    isolated: boolean;
+    command: string;
+    fire_at: string;
+    recur: string | null;
+    tz: string | null;
+    expires_at: string | null;
+    anchor_node: string | null;
+    cancel_on_wake: boolean;
+    cwd: string;
+    env_json: string | null;
+    profile: string | null;
+    scope: CronScope;
+    run_timeout_s: number;
+    overlap: CronOverlap;
+    on_output: CronOnOutput;
+    /** Sink JSON: `{node}` | `{spawn,kind,...}` | `{human}` (stored raw). */
+    sink: string;
+    tier: string;
+    last_output_hash: string | null;
+    /** True while the row is PARKED by the exit-75 owed-gate disposition: the
+     *  last scheduled run declared "owed but not currently eligible", so the
+     *  occurrence was not spent. A poke re-dues the row now; otherwise a
+     *  recurring row re-checks at its already-advanced natural slot and a held
+     *  one-shot waits at its backstop `fire_at` (expires_at, else far future).
+     *  Deliberately NOT part of the due query — a held row is non-due by
+     *  `fire_at`, not by a new predicate. */
+    held: boolean;
+    /** UTC ISO of the last `POST /v1/crons/poke` receipt, written to EVERY row
+     *  on poke. Settlement compares a 75-exiting run's start against it: a poke
+     *  that arrived mid-run re-dues instead of parking (the in-flight gate check
+     *  could not have seen the eligibility change). */
+    last_poke_at: string | null;
+    state: CronState;
+    run_state: CronRunState;
+    run_pid: number | null;
+    /** `capturePidIdentities` fingerprint of `run_pid`, taken at lease
+     *  acquisition. NULL on a pre-v23 row or when the capture failed — either
+     *  way `killLeasedCronRun` refuses to signal. */
+    run_pid_identity: string | null;
+    run_started_at: string | null;
+    run_lease_owner: string | null;
+    /** True when the in-flight lease belongs to an OUT-OF-BAND run (`cron run`)
+     *  rather than a scheduled fire. The overlap pass excludes such rows: a
+     *  manual verification must neither eat a real occurrence (`skip`) nor be
+     *  killed by one (`replace`). */
+    run_out_of_band: boolean;
+    created: string;
+    updated: string;
+}
+/** The pinned arm-time spec — every stored column except the runtime lease
+ *  fields, which always start idle. */
+export interface ArmCronSpec {
+    cron_id: string;
+    name: string;
+    created_by: string | null;
+    grantee?: string;
+    sub?: string;
+    grant_id?: string | null;
+    scopes?: readonly string[] | null;
+    origin_run_id?: string | null;
+    armed_from_exec?: boolean;
+    isolated?: boolean;
+    command: string;
+    fire_at: string;
+    recur: string | null;
+    tz: string | null;
+    expires_at: string | null;
+    anchor_node: string | null;
+    cancel_on_wake: boolean;
+    cwd: string;
+    env_json: string | null;
+    profile: string | null;
+    scope: CronScope;
+    run_timeout_s: number;
+    overlap: CronOverlap;
+    on_output: CronOnOutput;
+    sink: string;
+    tier: string;
+}
+/** One settled `cron_runs` record, written after the subprocess closes. */
+export interface CronRunRecord {
+    run_id: string;
+    cron_id: string;
+    started: string;
+    finished: string;
+    duration_ms: number;
+    /** -1 = timeout kill (schema contract); otherwise the observed exit code,
+     *  null when no exit was observed (process error). */
+    exit_code: number | null;
+    stdout_head: string | null;
+    stderr_head: string | null;
+    delivered: string | null;
+}
+/** Ring bound for `cron_runs`: recordCronRun prunes each cron's history to
+ *  its most recent this-many rows. */
+export declare const CRON_RUN_RING = 20;
+/** Decode the stored cron sink JSON. A malformed or unrecognised value has no sink. */
+export declare function parseCronSink(sinkJson: string): ParsedCronSink;
+/** Render a stored cron sink as the arm-time CLI spec, or null when it has no destination. */
+export declare function cronSinkDisplay(sinkJson: string): string | null;
+/** Signal only a run whose current pid identity matches its lease. A daemon
+ *  replacement can leave a pid number that the kernel later reuses. */
+export declare function stopLeasedCronRun(c: Cron, signal?: 'SIGTERM' | 'SIGKILL'): Promise<boolean>;
+/** Start the signal inside the canvas write boundary; log a launcher refusal.
+ *  Recovery uses the awaitable form so it cannot settle while the run lives. */
+export declare function killLeasedCronRun(c: Cron, signal?: 'SIGTERM' | 'SIGKILL'): boolean;
+/** Positive proof that `run_pid` is STILL the process this lease launched:
+ *  a stored identity exists, the `ps` probe succeeded, the pid has a row, and
+ *  its current identity matches. Anything else — including "we could not tell"
+ *  — is `false`, which is what makes `killLeasedCronRun` fail closed. */
+export declare function verifyLeasedCronRun(c: Cron): boolean;
+/** INSERT one cron row from the pinned arm spec, returning its (caller-
+ *  supplied) `cron_id` plus the ids of any deadline it displaced. Stamps
+ *  `created`/`updated`; lease fields start idle.
+ *
+ *  ONE DEADLINE PER ANCHOR: a `cancel_on_wake` arm REPLACES the anchor's
+ *  pending cancel-on-wake cron rather than stacking a second one — re-arming a
+ *  bounded wait moves the deadline. This is the invariant the dropped
+ *  `triggers` partial unique index carried, and `idx_crons_deadline`
+ *  (`crons(anchor_node) WHERE cancel_on_wake = 1`) is still its structural
+ *  backstop; the displace-then-insert runs inside ONE transaction that first
+ *  locks the anchor node row, so two concurrent arms replace one another in
+ *  sequence. Only the anchor's own cancel-on-wake
+ *  rows are displaced — a standing declarative cron on the same anchor is
+ *  untouched. Any displaced in-flight run's process group is killed first (the
+ *  cancelCron discipline). */
+export declare function armCron(spec: ArmCronSpec): Promise<{
+    cron_id: string;
+    replaced: string[];
+}>;
+/** SELECT one cron by id. */
+export declare function getCron(cron_id: string): Promise<Cron | null>;
+/** List crons for a scope, next-fire order. `{profile}` = that profile's
+ *  profile-scoped rows; `{global:true}` = global-scoped rows only;
+ *  `{all:true}` = every cron on the canvas. */
+export declare function listCrons(scope: {
+    profile: string;
+} | {
+    global: true;
+} | {
+    all: true;
+}): Promise<Cron[]>;
+/** DELETE one cron — the explicit user/surface cancel. Idempotent: an absent
+ *  row is a no-op `false`. Kills any in-flight run process group before
+ *  deleting unless the daemon has proved the caller is that exact run; then
+ *  the process must finish and deliver its already-produced output. The lease
+ *  acquisition still linearizes before this selection (the run is observed
+ *  and killed) or after the delete (and loses the lease). The FK cascade reaps
+ *  the cron's run history with it. */
+export declare function cancelCron(cron_id: string, options?: {
+    preserveRunningProcess?: boolean;
+}): Promise<boolean>;
+/** Cron ids a hard profile deletion will remove: matching execution profile,
+ *  plus every row anchored to a node being deleted. */
+export declare function cronIdsForProfileDeletion(profileId: string, anchorNodeIds: readonly string[]): Promise<string[]>;
+/** Kill any leased matching/anchored runs, then delete their rows together. */
+export declare function deleteCronsForProfile(profileId: string, anchorNodeIds: readonly string[]): Promise<string[]>;
+/** Cron ids whose snapshotted profile will be detached. */
+export declare function cronIdsForProfileDetach(profileId: string): Promise<string[]>;
+/** Preserve matching crons while removing their deleted profile dependency. */
+export declare function globalizeCronsForProfile(profileId: string): Promise<string[]>;
+/** DELETE one cron by id — one-shot consumption after its run settles.
+ *  Returns whether a live row was removed, so a consumer racing an explicit
+ *  cancel can no-op instead of double-settling. */
+export declare function consumeCron(cron_id: string): Promise<boolean>;
+/** UPDATE `state` (active|paused). Returns whether a row changed — pausing an
+ *  already-paused cron (or a gone one) reports `false`. Pausing does NOT kill
+ *  an in-flight run: the run settles normally, the row just stops being due. */
+export declare function setCronState(cron_id: string, state: CronState): Promise<boolean>;
+/** UPDATE `last_output_hash` — the on-change disposition's memory of the
+ *  previous run's stdout. Written after EVERY settled run of an on-change
+ *  cron, delivered or not. */
+export declare function setCronLastOutputHash(cron_id: string, hash: string): Promise<void>;
+/** True when a cron can still wake this node. An active deadline is a wake
+ * source by its anchor; output delivery is a wake source by its decoded node
+ * sink. Scheduled rows must remain active and unexpired, while a leased run
+ * remains eligible through settlement even if it has since been paused or
+ * expired. */
+export declare function hasPendingCronWake(nodeId: string): Promise<boolean>;
+/** DELETE every cancel-on-wake cron anchored to this node — the deadline rule.
+ *  A real wake consumes the wait at its delivery boundary or, as a dormant
+ *  fallback, in reviveNode; recovery replacement and a viewer attach are not
+ *  wakes and leave the deadline armed. Terminal
+ *  lifecycle transitions also clear the wait. Standing declarative crons are
+ *  untouched. Kills an in-flight run process group first (the cancelCron
+ *  discipline), under one canvas write boundary. Returns the removed crons. A wake must
+ *  go through `consumeDeadlineOnWake` (feed/messages.ts), which also tells the
+ *  node; ending a node calls this directly because nobody is left to tell. */
+export declare function cancelCronsOnWake(anchor_node: string): Promise<Cron[]>;
+/** UPDATE the next fire time — recurrence advancement. The daemon settles a
+ *  recurring row to its next slot BEFORE enacting the run (crash-safe). */
+export declare function advanceCron(cron_id: string, nextFireIso: string): Promise<void>;
+/** The daemon's per-tick due query: active, idle, fire_at arrived, in
+ *  deterministic order. The idle-only filter IS the default `overlap='skip'`
+ *  behavior — a row whose previous run is still leased is simply not due.
+ *  Returns exactly ONE row per cron regardless of missed slots — coalescing
+ *  is structural (fire_at holds a single next occurrence). */
+export declare function dueClockCrons(nowIso: string): Promise<Cron[]>;
+/** Atomically acquire the idle run lease: flips `run_state` to 'running' and
+ *  records lease/pid metadata, but ONLY if the row is still idle (the
+ *  `WHERE run_state = 'idle'` guard is the atomicity). Returns whether THIS
+ *  call acquired it.
+ *
+ *  The pid is recorded WITH its launch-time identity fingerprint, captured here
+ *  from the just-spawned child: that fingerprint is what later authorizes any
+ *  signal against this pid (`killLeasedCronRun`). A failed capture stores NULL,
+ *  which costs the row its kill rights rather than licensing a blind kill.
+ *
+ *  `outOfBand` stamps the lease as a `cron run` (manual verification) so the
+ *  overlap pass leaves it alone — see `dueOverlapCrons`. */
+export declare function acquireCronRunLease(cron_id: string, leaseOwner: string, startedAtIso: string, outOfBand: boolean, executionId?: string | null): Promise<boolean>;
+/** Attach the launcher's pid only to the run that claimed this lease. */
+export declare function attachCronRunPid(cron_id: string, leaseOwner: string, startedAtIso: string, pid: number): Promise<boolean>;
+/** What a settling run does with the row's `held` state, applied in the SAME
+ *  UPDATE that releases the lease — one write boundary, so no tick can observe
+ *  `run_state='idle'` with the held transition not yet applied.
+ *    clear — an ordinary scheduled disposition settlement (success, real
+ *            failure): the gate resolved, so a parked row unparks.
+ *    park  — the exit-75 owed-gate disposition: held=1. A one-shot also moves
+ *            `fire_at` to its backstop (`fireAt`); a recurring row keeps its
+ *            pre-run-advanced natural slot.
+ *    redue — a poke arrived while this gate check was in flight (start <
+ *            last_poke_at): fire_at=now, held=0 — re-check next tick.
+ *  Omitted entirely = leave `held` untouched (a replaced run, an out-of-band
+ *  run, an unobserved crashed run — the gate is still unresolved). */
+export type HeldSettle = {
+    kind: 'clear';
+} | {
+    kind: 'park';
+    fireAt?: string;
+} | {
+    kind: 'redue';
+    nowIso: string;
+};
+/** Release the run lease back to idle (run settled, or stale-lease recovery
+ *  for a dead pid) — only while the row still holds run `runId`, so a settlement of
+ *  an old run cannot clear a newer run's lease. Applies the settlement's `held` disposition in the same
+ *  statement. */
+export declare function releaseCronRunLease(cron_id: string, runId: string, held?: HeldSettle): Promise<void>;
+/** Persist a run identity on a running row that has none, but only while it is still the same run (same start and lease owner).
+ *  Recovery calls this under its claim so every later write and release names one stored run. Returns whether it was stored. */
+export declare function adoptCronRunId(c: Cron, runId: string): Promise<boolean>;
+/** The daemon-level eligibility poke (`POST /v1/crons/poke`): "something
+ *  changed; re-check now". One write boundary, two statements:
+ *    1. stamp `last_poke_at` on EVERY row — this is what reaches a gate check
+ *       in flight right now, which statement 2 deliberately skips: its exit-75
+ *       settlement sees the stamp and re-dues itself (the F2 branch in
+ *       cron-run.ts);
+ *    2. re-due every held active IDLE row now (fire_at=now, held=0). A leased
+ *       row is excluded: its running gate check settles against the stamp —
+ *       75 re-dues, and success means the gate resolved and the occurrence
+ *       fired, poke satisfied. Unparking mid-run would overwrite the row's
+ *       pre-advanced backstop slot with `now`, so a PASSING gate would fire a
+ *       second time on the next tick.
+ *  Paused rows are not unparked — pause is user-owned and freezes everything;
+ *  a paused held row keeps its state and unparks via a later poke/backstop
+ *  after resume (it still receives the stamp, harmlessly). Returns the
+ *  unparked count. Idempotent and free when nothing is held. */
+export declare function pokeHeldCrons(nowIso: string, grantee?: string | null): Promise<number>;
+/** Recurring crons whose NEXT fire has arrived while their previous run is
+ *  still leased — the overlap-policy pass. One-shots never appear here (a
+ *  one-shot has exactly one fire, already consumed by its running lease).
+ *
+ *  An OUT-OF-BAND lease (`cron run`) is excluded: overlap policy arbitrates
+ *  between a SCHEDULED fire and the scheduled run already in flight. A manual
+ *  verification is neither, so letting it participate would either advance
+ *  `fire_at` past a genuine occurrence (`skip`) or SIGTERM the invoker's own
+ *  run (`replace`). Such a row simply is not due for overlap; the real
+ *  occurrence stays past-due and fires the moment the manual lease releases. */
+export declare function dueOverlapCrons(nowIso: string): Promise<Cron[]>;
+/** Crons whose clock bound (`expires_at`) has passed — the daemon deletes
+ *  these each tick. Idle rows only: an expired row whose run is still in
+ *  flight is picked up on a later tick, after the run settles. */
+export declare function expiredIdleCrons(nowIso: string): Promise<Cron[]>;
+/** The run-log ring for one cron, most recent first. */
+export declare function listCronRuns(cron_id: string): Promise<CronRunRecord[]>;
+/** Every cron currently marked 'running' — the daemon's stale-lease recovery
+ *  scan checks each recorded `run_pid` for liveness. */
+export declare function runningCrons(): Promise<Cron[]>;
+/** INSERT one settled run record, then prune that cron's history down to the
+ *  most recent CRON_RUN_RING rows — one canvas write boundary, so the ring
+ *  bound holds atomically with the insert. Returns whether the record was
+ *  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: CanvasDb, run: CronRunRecord): Promise<boolean>;
+export declare function recordCronRun(run: CronRunRecord): Promise<boolean>;