tickmarkr 2.6.6 → 2.6.8

package/dist/run/beat-lifecycle.d.ts

@@ -0,0 +1,239 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+import { type SupervisionArm, type SupervisionTier } from "./supervision.js";
+/** start's whole budget — launch, read-back and any overrun — before it must refuse and roll back. */
+export declare const BEAT_STARTUP_CEILING_MS = 60000;
+/** The generation a started child carries; it lets the child act under its launcher's claim only. */
+export declare const BEAT_GENERATION_ENV = "TICKMARKR_BEAT_GENERATION";
+export interface ProcessIdentity {
+    birth: string;
+    command: string;
+    cwd: string;
+    pgid: number;
+}
+/** `UNKNOWN — <why>` is UNKNOWN that names its cause (Darwin's lsof missing or unusable): never life, never death. */
+export type IdentityRead = ProcessIdentity | "DEAD" | "UNKNOWN" | `UNKNOWN — ${string}`;
+/** The host the production reader inspects through; Darwin (and every non-Linux host) reads cwd only via lsof. */
+export interface IdentityHost {
+    platform?: NodeJS.Platform;
+    lsof?: string;
+}
+/** Every boundary the lifecycle crosses, injectable so failures are exercised where they really occur. */
+export interface BeatLifecycleDeps {
+    /** Command prefix that re-executes this same CLI (node, its flags, the entry the launcher ran). */
+    cli: readonly string[];
+    spawn: (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+    kill: (pid: number, signal: NodeJS.Signals) => void;
+    identity: (pid: number) => IdentityRead;
+    openLog: (path: string) => number;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    env: NodeJS.ProcessEnv;
+}
+export declare function defaultBeatDeps(host?: IdentityHost): BeatLifecycleDeps;
+/** A named, nonzero refusal: dispatch renders the message and exits 1. `notice` is a reclaim it must not lose. */
+export declare class BeatRefusal extends Error {
+    readonly notice?: string | undefined;
+    constructor(message: string, notice?: string | undefined);
+}
+/**
+ * The live process behind a pid: birth (lstart), full argv, cwd and process group. A missing process is
+ * DEAD only when the kernel says so (ESRCH or a zombie) — also when it exits between ps and the cwd read;
+ * anything unreadable is UNKNOWN, never DEAD. Linux reads cwd from /proc and never needs lsof; every other
+ * host reads it through lsof, so a missing or unusable lsof beside a LIVE pid is UNKNOWN that names lsof.
+ */
+export declare function readProcessIdentity(pid: number, host?: IdentityHost): IdentityRead;
+export declare const beatClaimPath: (repoRoot: string, tier: SupervisionTier) => string;
+export declare const beatOwnerPath: (repoRoot: string, tier: SupervisionTier) => string;
+export declare const beatLogPath: (repoRoot: string, tier: SupervisionTier) => string;
+/**
+ * The exact generation start launched. pid/birth/command/pgid are absent only while it is launching;
+ * priorArmId/priorArmEpoch name the (already fenced) arm on disk at launch, which the child's own arm then
+ * replaces; armEpoch is bound from the exact child's checked beat, and ownership is the COMPLETE durable arm
+ * generation (armId AND armEpoch) — a same-id arm with another epoch is a replacement.
+ */
+export interface BeatOwner {
+    tier: SupervisionTier;
+    seat: string;
+    generation: string;
+    armId: string;
+    cwd: string;
+    startedAt: string;
+    armEpoch?: string;
+    priorArmId?: string;
+    priorArmEpoch?: string;
+    pid?: number;
+    birth?: string;
+    command?: string;
+    pgid?: number;
+}
+type Read<T> = T | "NONE" | "UNREADABLE";
+export declare function readBeatOwner(repoRoot: string, tier: SupervisionTier): Read<BeatOwner>;
+/** Runs `mutate` as ONE claimed act (claimedAct); `check` is the act's own barrier (owner generation, records). */
+export type ClaimGuard = <T>(mutate: () => T, check?: () => void) => T;
+/** Outside any claim (a direct call): the barrier, then the mutation. */
+export declare const unclaimed: ClaimGuard;
+/**
+ * Atomic first-writer-wins claim. A held claim is BUSY unless `reclaim` (every claimant passes its boundaries) confirms
+ * DEAD every pid parsed from the claim's own bytes — its holder and any launched writer publishing under it
+ * (reclaimDeadClaim): then exactly those bytes are removed (takeClaim) and the claim is taken; the returned notice says
+ * so (on a refusal, `BeatRefusal.notice` does). A live, reused or unreadable holder or publisher is never taken over.
+ * A linked claim is SETTLED (returned) only when no claim removal is under way and it is still the canonical claim: a
+ * removal's put-back may replace a claim linked into its gap, so until that removal ends the claim holds nothing — the
+ * claimant withdraws exactly its own linked bytes (takeClaim) and refuses BUSY, so no caller, a long-lived bridge
+ * included, is left holding a live claim nobody acts under; its next attempt links afresh. When another live taker
+ * holds or has moved aside those very bytes (a mistaken death proof included), the withdrawal cannot land then; once
+ * this attempt refuses, its token is no longer in use, so the bytes are this process's STRAND wherever they are
+ * (strandOf), proven from the bytes alone: every later attempt in this process withdraws them from the claim path
+ * first (withdrawStrand) and discards them from a killed taker's lock instead of restoring them (recoverLock) — so
+ * recovery never waits for the caller to exit.
+ */
+export declare function acquireBeatClaim(repoRoot: string, tier: SupervisionTier, token: string, reclaim?: BeatLifecycleDeps): string | undefined;
+/** The ONE finite contention policy shared by every waiting claimant: loop ticks, legacy one-shots and stop. */
+export declare const BEAT_CLAIM_WAIT: {
+    readonly tries: 20;
+    readonly intervalMs: 250;
+};
+export interface ClaimWait {
+    tries?: number;
+    intervalMs?: number;
+    sleep: (ms: number) => Promise<void>;
+}
+/**
+ * Release removes exactly the bytes that name this token (takeClaim), after any claimed act under them — a launched
+ * writer's included — has finished: a replacement found at any instant is left in place. However it ends, the token is
+ * then no longer in use: bytes under it that a live taker kept or moved aside are this process's strand (strandOf),
+ * withdrawn or discarded by its next attempt. `told` gets the notice of a dead taker's lock recovered on the way.
+ */
+export declare function releaseBeatClaim(repoRoot: string, tier: SupervisionTier, token: string, told?: (notice: string) => void): void;
+/**
+ * Run ONE supervision.ts writer (stand-down, arm or beat) under a claim without letting it touch the tier: it writes
+ * into a STAGED copy of the tier's records (arm, clear-duty latch, beat, stand-down marker), then every record it
+ * changed is committed by one rename — a discharged latch by one removal — as ONE claimed act each (`guard`), in the
+ * writers' own order (arm, raised latch, beat, marker, discharged latch). Compare-and-commit: inside each act, after
+ * the caller's own barrier (its owner generation) and before the final claim check, every record must still be
+ * exactly what this write was staged from (or what it committed itself) — a record replaced meanwhile, the owner by
+ * the caller's barrier, refuses with nothing further committed. A claim lost, or a record or owner replaced, before
+ * the first commit therefore lands nothing; one lost between two commits lands nothing further; either refuses. What a
+ * failing writer published before its failure is committed the same way, then the failure is rethrown.
+ * ponytail: staging stands in for a commit guard supervision.ts's atomic writers do not take; a writer killed mid-write
+ * leaves an inert `<tier>.stage.<pid>.<uuid>` directory (no reader lists it), which the next start, stop or legacy
+ * write removes once that pid is confirmed dead (acquireBeatClaim).
+ */
+export declare function supervised<T>(repoRoot: string, tier: SupervisionTier, guard: ClaimGuard, write: (root: string) => T): T;
+/**
+ * A legacy writer: the launch generation it carries (if any), its seat, the arm a running loop holds, the
+ * boundaries its checks read through, and where the notice of a dead claim it reclaimed goes.
+ */
+export interface LegacyWriter {
+    generation?: string;
+    seat: string;
+    settled?: boolean;
+    arm?: SupervisionArm;
+    deps: BeatLifecycleDeps;
+    noticed?: (notice: string) => void;
+}
+/**
+ * The recheck a legacy write calls immediately before it mutates; `arm` is the arm the writer itself holds, and
+ * `created` says this writer published that arm under this claim a moment ago (an owned re-arm).
+ */
+export type LegacyRecheck = (arm?: SupervisionArm, created?: boolean) => void;
+/**
+ * Run one legacy write (one-shot tick, new arm, EVERY loop tick, stand-down) under the tier claim. A launched
+ * child acts under its launcher's claim (underLaunchClaim) while that claim is still held for its generation, names
+ * this child as its publisher and its launcher is not confirmed dead; afterwards it takes the tier claim itself like
+ * every other writer. `act` receives the recheck it must call before it writes (the tier's ownership still admits
+ * this writer, then the claim still names this holder) and the guard every supervision write it makes commits under
+ * (supervised): each commit is one claimed act whose barrier re-runs that same ownership check. A claim held by
+ * anyone else is waited out under BEAT_CLAIM_WAIT (20 attempts 250 ms apart, absent `waits` fields default to it)
+ * and then refuses BUSY with nothing written; invalid tries/interval refuse before any claim or write. Like start
+ * and stop, the writer reclaims a claim whose recorded pids are all confirmed dead (`noticed` receives the notice): a
+ * legacy --loop writer killed inside its claimed tick never strands the --stand-down migration step, and a live
+ * writer's claim is never taken. Under its own claim, the release that follows `act` is the claim's last check: a claim
+ * lost by then refuses, never reports success. Under the launcher's claim no release follows and nothing is checked
+ * after the last act — each act verified the claim last — so the launcher's release after its read-back never ends
+ * the loop it launched. A dead or abandoned generation recorded for this writer's seat is retired first (retireDead).
+ */
+export declare function withLegacyClaim<T>(repoRoot: string, tier: SupervisionTier, writer: LegacyWriter, act: (recheck: LegacyRecheck, held: ClaimGuard) => T | Promise<T>, waits?: ClaimWait): Promise<T>;
+/** The ownership a legacy writer needs before each mutation: its own COMPLETE launched generation, or no owner at all. */
+export declare function assertLegacyOwnership(repoRoot: string, tier: SupervisionTier, writer: LegacyWriter, arm?: SupervisionArm, created?: boolean, held?: BeatOwner, claimed?: ClaimGuard): BeatOwner | undefined;
+/**
+ * ONE RULE: every legacy write is preceded by the shared complete owned-generation check of the CURRENT owner
+ * record and durable arm against the EXACT generation this writer holds — token, seat, pid (once settled), armId
+ * and armEpoch. `held` is the owner this claim's previous check validated and `arm` the arm the writer holds (a
+ * loop's own arm; before the launcher binds the epoch that arm is the evidence). The first check of a claim by a
+ * writer holding neither takes the generation on record; from then on the held generation changes in exactly
+ * two verified ways, and any other change — also one between this check's own reads — refuses with no write:
+ *  (i) the writer's OWN re-arm (`created`: it published `arm` under this claim after the complete check): the
+ *      arm on disk must be exactly that arm and the owner exactly the owner checked before the arm write; only
+ *      then is the owner rebound to the arm (same token, seat, process), and the complete check runs AGAIN as
+ *      the new generation before the beat. After any mismatch the owner is never rewritten.
+ * (ii) the launcher completing an UNBOUND owner for this writer (launcherBound) — never adopted from disk.
+ * Once `settled` (past its first beat) the record must name its pid: a launch that refused without proving it
+ * could signal its child leaves no pid behind, and that child retires itself.
+ */
+export declare function assertOwnedGeneration(repoRoot: string, tier: SupervisionTier, writer: LegacyWriter & {
+    generation: string;
+}, arm?: SupervisionArm | undefined, created?: boolean, held?: BeatOwner, claimed?: ClaimGuard, pid?: number): BeatOwner;
+export type CheckedBeat = {
+    kind: "EMPTY";
+} | {
+    kind: "DISARMED";
+    seat?: string;
+} | {
+    kind: "OWN-LIVE";
+    owner: BeatOwner & {
+        pid: number;
+    };
+    advancing: boolean;
+} | {
+    kind: "OWN-DEAD";
+    owner: BeatOwner & {
+        pid: number;
+    };
+} | {
+    kind: "ABANDONED";
+    owner: BeatOwner;
+    reason: string;
+} | {
+    kind: "FOREIGN";
+    reason: string;
+    migrate?: string;
+} | {
+    kind: "PID-REUSED";
+    owner: BeatOwner & {
+        pid: number;
+    };
+} | {
+    kind: "UNKNOWN";
+    reason: string;
+};
+/**
+ * The checked state of one tier, read-only: no claim, no write, no signal. Every authoritative record —
+ * owner, marker, beat and durable arm — is validated before any outcome is selected, and ownership binds to
+ * this repository's canonical root, the recorded seat and the recorded arm before the process is consulted.
+ * An UNBOUND owner (no pid, or no arm epoch) is a launch in progress only while a claim is held: a launch publishes and
+ * binds only under its own claim. So when the caller holds the tier claim (`held`), or no claim exists before and after
+ * the owner is read (status), an unbound owner with no live recorded process is ABANDONED — its launcher died — and
+ * the next start, stop or legacy write retires it (retireDead); a live recorded process keeps it UNKNOWN.
+ */
+export declare function inspectBeat(repoRoot: string, tier: SupervisionTier, seat: string | undefined, deps: BeatLifecycleDeps, held?: boolean): CheckedBeat;
+/**
+ * Status: the recorded liveness, rendered without writing; healthy states exit 0, the rest nonzero. It is observation
+ * only: a claim whose recorded pids are all dead, what a killed taker or writer left, or — read in the process that
+ * stranded it (a bridge) — that process's own strand (strandOf), is REPORTED (nonzero) with the pids and the exact
+ * command that recovers it — never recovered here, and no file is touched.
+ */
+export declare function beatStatus(repoRoot: string, tier: SupervisionTier, seat: string | undefined, deps: BeatLifecycleDeps): {
+    out: string;
+    code: number;
+};
+/** start: one claim (a single attempt), one child; exit zero only after this exact child's own advancing beat reads back. */
+export declare function startBeat(repoRoot: string, tier: SupervisionTier, seat: string, deps: BeatLifecycleDeps): Promise<string>;
+/**
+ * stop: retire only the recorded generation, signalling its exact pid, then read back DISARMED. A loop tick
+ * holding the claim is waited out under BEAT_CLAIM_WAIT; a claim whose recorded pids are all confirmed dead is
+ * reclaimed. Every stand-down commit (supervised), signal and removal is one claimed act under stop's claim (`held`)
+ * with the owner generation it acts on re-verified inside it.
+ */
+export declare function stopBeat(repoRoot: string, tier: SupervisionTier, seat: string, deps: BeatLifecycleDeps): Promise<string>;
+export {};