approval-md 0.3.0 → 0.4.1

package/dist/src/core/log-lock.d.ts

@@ -0,0 +1,435 @@
+/**
+ * The holder of `<log>.lock`, and the one way a lock left by a writer that died
+ * holding it is taken back (APRV-479).
+ *
+ * ## The defect this exists for
+ *
+ * `core/log.ts` serializes every append with a lockfile created `wx` and never
+ * stolen, because silently breaking somebody else's lock is how two writers
+ * come to share a `seq`. A writer that dies while it holds the lock never
+ * removes it: a harness hook killed by SIGTERM with no listener registered (the
+ * default disposition), any verb killed by SIGKILL, a Hermes gateway restart in
+ * the middle of an append. Every later writer, the daemon included, then waits
+ * its two seconds and refuses `lock-timeout`, and the tenant's gate stays
+ * wedged until a human removes the file.
+ *
+ * ## The rule every decision here follows
+ *
+ * A wrong reclaim (two writers under one lock, a forked chain) is far worse than
+ * a missed one (a wedge a human clears with one command). So a holder is LIVE
+ * unless this process can prove it gone, and a lock is taken back only by a
+ * writer that has already waited out its whole lock timeout.
+ *
+ * ## What this module does
+ *
+ * 1. **The lockfile names its holder.** {@link createLockFile} writes one JSON
+ *    line into the file it creates: pid, host, boot, on Linux the pid and time
+ *    namespaces and the process start time, when the lock was taken, which kind
+ *    of holder (`append` | `hold`), and a nonce. An older writer's lockfile is
+ *    empty.
+ * 2. **Only a regular file that parses strictly is judged.** Every read opens
+ *    without blocking and without following links, and reads only a regular
+ *    file of at most 4 KiB. Anything else at the lock's path (a FIFO, a link, a
+ *    directory, an oversized or malformed file, a record of another version) is
+ *    not this writer's to judge: it is LIVE.
+ * 3. **The judgement ({@link judgeHolder}).** Gone only when the holder is in
+ *    this process's own pid namespace and boot, and provably not running:
+ *    - Linux: `/proc` is this namespace's (`/proc/self` names this pid), the
+ *      record's boot id and pid-namespace inode equal this process's, and then
+ *      `kill(pid, 0)` answers ESRCH with `/proc/<pid>` absent or a zombie, or
+ *      `/proc/<pid>/stat` names a process whose start time (read in the same
+ *      time namespace) is not the holder's;
+ *    - elsewhere (macOS): the same hostname, boot readings within
+ *      {@link BOOT_SLACK_S} seconds, and `kill(pid, 0)` answering ESRCH.
+ *
+ *    Everything else is LIVE: EPERM, another namespace or boot or host, a
+ *    `/proc` entry that cannot be read.
+ * 4. **A lockfile with no holder record** (empty: an older version's, or a
+ *    writer killed between the create and the write) is gone only once its
+ *    mtime is {@link LEGACY_LOCK_RECLAIM_AGE_MS} old AND this writer watched
+ *    that very file (inode, mtime, size) unchanged through its own wait.
+ * 5. **The reclaim ({@link reclaimStaleLock}) is two atomic steps, and nothing
+ *    else is written.** The taker's own complete lockfile is written first,
+ *    under `<lock>.take.<pid>.<nonce>`, so whoever finds a claim beside the
+ *    lock also finds its taker and can judge it (`approval log unlock` refuses
+ *    while one is seen running). Then the claim: `link(2)` of the lock's path to a name
+ *    derived from the judged record, `<lock>.stale.<pid>.<created ms>`, which
+ *    fails EEXIST for every other reclaimer of the same lockfile, and which is
+ *    then read back to prove it names the very file that was judged (inode,
+ *    mtime, bytes). Then the take: this writer's own lockfile is `rename(2)`d
+ *    over the lock's path, once the claim and the lock's path are read again
+ *    and are still the judged file. The lock's
+ *    path is never empty, so no ordinary `wx` create slips in, and between the
+ *    claim and the take nothing in the protocol can change it: the holder is
+ *    dead, every other writer's create fails EEXIST, and every other
+ *    reclaimer's claim fails EEXIST. (A bare `rename` of the lockfile aside
+ *    cannot be made safe: a reclaimer that judged the dead lock and stalled
+ *    would later move whatever live lock had replaced it.)
+ * 6. **The reclaim is in the log first.** The reclaimer appends
+ *    `audit.lock_reclaimed` as the first record under the lock it took
+ *    (`core/log.ts`), carrying the strictly parsed pid, op and `created` and
+ *    nothing else from the file, and only then unlinks the stale name.
+ * 7. **A termination signal does not leave a lock behind.**
+ *    {@link guardTerminationWhileLocked} is installed before a lockfile is
+ *    created, and before a reclaim's claim, and held until the lock is removed: for SIGTERM, SIGINT and SIGHUP with
+ *    no listener, a listener that re-raises the signal with its default
+ *    disposition once the lock is released, so the process still dies of it.
+ *    SIGKILL cannot be caught, which is what 1 to 6 are for.
+ *
+ * Never reclaimed automatically, whatever the holder: a lock beside a
+ * `log sync` snapshot (a sync killed part way may have left the working log at
+ * its committed bytes), and a lock beside a log that does not exist. A lock from
+ * another container or boot is never reclaimed automatically either; the
+ * refusal names the pid and the human verb, `approval log unlock --pid <n>`
+ * ({@link takeLockForUnlock}).
+ */
+/** The holder record's format version. A reader treats any other as not its to judge. */
+export declare const LOCK_HOLDER_VERSION = 1;
+/**
+ * How old an empty lockfile (no holder record) must be before it is reclaimed.
+ * An append holds the lock for milliseconds, and the longest holder in this
+ * runtime (`approval log sync`) for seconds.
+ */
+export declare const LEGACY_LOCK_RECLAIM_AGE_MS: number;
+/**
+ * How long a writer must have watched an empty lockfile unchanged (the same
+ * inode, mtime and size since the first refusal of its wait) before it may take
+ * it as `legacy-aged`. A writer of this version fills its record within
+ * microseconds of its create, so an empty file that stays empty across a retry
+ * interval is not one; an mtime alone can read old through a stepped clock or
+ * a file server's lagging one (APRV-479 R3-8).
+ */
+export declare const LEGACY_LOCK_WATCH_MS = 20;
+/**
+ * Off Linux, how far apart two boot readings (`now - uptime`, in seconds) may
+ * be and still count as one boot. A wall-clock step moves the reading, so a
+ * larger gap is "another boot, or a stepped clock": live, never gone.
+ */
+export declare const BOOT_SLACK_S = 60;
+/**
+ * `created` exactly as `Date#toISOString` writes it AND a real instant: the
+ * string must survive a round trip, which `2026-02-30T00:00:00.000Z` (a shape
+ * match that V8 rolls over to March 2nd) does not.
+ */
+export declare function isCanonicalTimestamp(value: string): boolean;
+/** `append`: one record. `hold`: a whole operation under `withAppendLock`. */
+export type LockOp = "append" | "hold";
+/** Who a process is, as far as a liveness judgement can use it. */
+export interface HolderIdentity {
+    pid: number;
+    host: string;
+    /** Linux: `/proc/sys/kernel/random/boot_id`. Elsewhere: `~<boot epoch seconds>`. */
+    boot: string;
+    /** Linux only: `/proc/self/ns/pid`. */
+    pidns?: string;
+    /** Linux only: field 22 of `/proc/self/stat` (clock ticks after boot, in this time namespace). */
+    start?: string;
+    /** Linux only, where the kernel has time namespaces: `/proc/self/ns/time`. */
+    timens?: string;
+}
+/** What a lockfile written by this version holds, one JSON line. */
+export interface LockHolder extends HolderIdentity {
+    v: typeof LOCK_HOLDER_VERSION;
+    /** When the lock was taken, as `Date#toISOString` writes it. */
+    created: string;
+    op: LockOp;
+    /** Random, so two lockfiles are never byte-identical. */
+    nonce: string;
+}
+/**
+ * Why a lock was taken over: the `audit.lock_reclaimed` payload's closed
+ * `reason` set. `holder-dead` and `legacy-aged` are a writer's proof;
+ * `operator-cleared` is a person's assertion (`approval log unlock`), never a
+ * proof, and only a `human:` actor carries it.
+ */
+export type LockReclaimReason = "holder-dead" | "legacy-aged" | "operator-cleared";
+/**
+ * The judgement on one holder record. `running` (on a live verdict): this
+ * process saw the holder itself running (Linux: its start time; elsewhere: its
+ * pid, on this host, in this boot). A live verdict without it is a holder this
+ * process cannot check, which a human may clear with `approval log unlock`.
+ */
+export type HolderVerdict = {
+    state: "gone";
+    why: string;
+} | {
+    state: "live";
+    why: string;
+    running: boolean;
+};
+/** This process, as a holder record describes it. */
+export interface SelfIdentity {
+    pid: number;
+    host: string;
+    boot: string | undefined;
+    pidns: string | undefined;
+    start: string | undefined;
+    timens?: string | undefined;
+    linux: boolean;
+    /**
+     * Linux: whether `/proc` is this process's own pid namespace's procfs
+     * (`/proc/self` names `process.pid`). `false` means no pid read from it can be
+     * trusted, and every holder is live. Absent is taken as `true` (tests).
+     */
+    procIsOwn?: boolean;
+}
+/** What `/proc/<pid>/stat` said. */
+export type ProcStatRead = {
+    kind: "stat";
+    state: string;
+    start: string;
+}
+/** ENOENT or ESRCH: no entry this process can see. */
+ | {
+    kind: "absent";
+}
+/** Anything else (EACCES, EPERM, an unparseable line): nothing can be concluded. */
+ | {
+    kind: "unreadable";
+    why: string;
+};
+/** `kill(pid, 0)`: `ok` (exists), `ESRCH` (no such process), `EPERM` (exists, another user's), `other`. */
+export type SignalZero = "ok" | "ESRCH" | "EPERM" | "other";
+/** What a liveness judgement may ask of the operating system. Injected by tests. */
+export interface LivenessProbe {
+    /** Linux: `/proc/<pid>/stat`, as read by this process. */
+    linuxStat(pid: number): ProcStatRead;
+    signalZero(pid: number): SignalZero;
+}
+/**
+ * Parse `/proc/<pid>/stat`: the command name is parenthesized and may contain
+ * spaces and parentheses, so the fields are counted from the LAST `)`. After it,
+ * index 0 is field 3 (state) and index 19 is field 22 (starttime).
+ */
+export declare function parseProcStat(text: string): {
+    state: string;
+    start: string;
+} | null;
+/** The real probe: `/proc` and `kill(pid, 0)`. */
+export declare const NODE_LIVENESS_PROBE: LivenessProbe;
+/**
+ * Is `/proc` this process's own pid namespace's procfs? `/proc/self` resolves
+ * to the reader's pid as THAT procfs numbers it, so it names `process.pid` only
+ * when the procfs belongs to the namespace `process.pid` was issued in, or when
+ * the pid happens to be the same number in both (APRV-479 R3-9). So the
+ * `NSpid:` line of `/proc/self/status` must also hold exactly one field, this
+ * pid: it lists the pid in every namespace from the procfs's own down to the
+ * reader's, and one field means they are the same namespace. A kernel without
+ * the line (before 4.1) proves nothing, and every holder is then live.
+ */
+export declare function procIsOwnNamespace(read?: (path: string) => string, pid?: number, status?: (path: string) => string): boolean;
+/** This process's identity, read once: none of it changes while the process lives. */
+export declare function selfIdentity(): SelfIdentity;
+/** The record this process writes into a lockfile it creates now. */
+export declare function holderRecord(op: LockOp, now?: Date): LockHolder;
+/**
+ * What a lockfile's bytes say: a strictly parsed v1 record, `legacy` (empty or
+ * whitespace only: no holder record at all), or `unknown` (anything else: a
+ * malformed record, another version, text that is not JSON), which is never
+ * judged.
+ */
+export declare function parseHolder(bytes: Buffer | string): {
+    kind: "v1";
+    holder: LockHolder;
+} | {
+    kind: "legacy";
+} | {
+    kind: "unknown";
+};
+/**
+ * Is the process that wrote `holder` provably gone? Pure: the identity of the
+ * reader and the operating system's answers are parameters. "Live" means "not
+ * provably gone". The holder's boot and pid namespace are established before
+ * any pid is looked up, because a pid means nothing outside the namespace it
+ * was issued in.
+ */
+export declare function judgeHolder(holder: HolderIdentity, self: SelfIdentity, probe: LivenessProbe): HolderVerdict;
+/**
+ * Replace the liveness judgement (tests only: the pin that a live holder's
+ * lock survives only because of the check). `null` restores the real one.
+ */
+export declare function setLockLivenessForTests(judge: ((holder: HolderIdentity) => HolderVerdict) | null): void;
+/** Where a test may act inside the lock's protocol. Nothing in `src/` sets one. */
+export type LockStep = "after-open" | "judged" | "claimed" | "before-take";
+/** Run `seam` at each named step (tests only: a stall, a signal, a planted file). `null` removes it. */
+export declare function setLockSeamForTests(seam: ((step: LockStep) => void) | null): void;
+/** The lock this process created or took: enough to release only that one. */
+export interface OwnLock {
+    path: string;
+    ino: bigint;
+    bytes: Buffer;
+}
+/**
+ * Create `path` with `wx` and write this process's holder record into it.
+ * Throws what `openSync` throws, so `EEXIST` means another writer holds it. A
+ * record that cannot be written leaves an empty lockfile, which is still a lock.
+ * The caller installs the signal guard BEFORE calling this.
+ */
+export declare function createLockFile(path: string, op: LockOp): OwnLock;
+/**
+ * Remove the lock this process holds, and only it: anything else at the path
+ * (another inode, other bytes) is left where it is.
+ */
+export declare function releaseLockFile(own: OwnLock): void;
+/** What an `audit.lock_reclaimed` record says, and the stale name to unlink once it is in the log. */
+export interface ReclaimNote {
+    /** The lockfile's base name. */
+    lockfile: string;
+    reason: LockReclaimReason;
+    /**
+     * From a v1 record only: the strictly parsed pid, op and `created`. `created`
+     * is `null` when it is not plausible ({@link plausibleCreated}).
+     */
+    holder?: {
+        pid: number;
+        op: LockOp;
+        created: string | null;
+    };
+    /**
+     * How long the lock had been held, from `created` (or an empty lockfile's
+     * mtime), by this process's clock. Absent exactly when `created` is `null`.
+     */
+    age_ms?: number;
+    /** The claim name, removed after the record lands. Never recorded. */
+    stale: string;
+    /** One line for a person. Never recorded. */
+    why: string;
+}
+/** How far before the log's last record a holder's `created` may lie and still be recorded. */
+export declare const CREATED_BEFORE_LAST_RECORD_MS: number;
+/** How far past this process's clock a holder's `created` may lie and still be recorded. */
+export declare const CREATED_AFTER_NOW_MS: number;
+/**
+ * The record of a reclaim carries a holder's `created` (and the age derived
+ * from it) only when it is plausible: no earlier than the log's last record's
+ * `ts` minus {@link CREATED_BEFORE_LAST_RECORD_MS}, and no later than now plus
+ * {@link CREATED_AFTER_NOW_MS}. Anything else is a value the file chose (any
+ * canonical instant parses, year 0000 and 9999 included), so the record says
+ * `created: null` and carries no age. With no last record to measure from, no
+ * `created` is plausible. (APRV-479 R3-7, the stricter rule.)
+ */
+export declare function plausibleCreated(note: ReclaimNote, lastTs: number | null, now: number): ReclaimNote;
+/** What the writer knows about the log before it claims: whether it could record a reclaim at all, and its last record's time. */
+export type RecordContext = {
+    ok: true;
+    lastTs: number | null;
+} | {
+    ok: false;
+    why: string;
+};
+/** What {@link reclaimStaleLock} found and did. */
+export type ReclaimOutcome = 
+/** This process now holds the lock and must record `note` first. */
+{
+    kind: "taken";
+    own: OwnLock;
+    releaseGuard: () => void;
+    note: ReclaimNote;
+}
+/** The lock moved, or another writer is reclaiming it: wait again. */
+ | {
+    kind: "retry";
+    why: string;
+}
+/** The lock stays where it is; `why` names its holder and the human command. */
+ | {
+    kind: "kept";
+    why: string;
+};
+/** The human verb, as a refusal names it. */
+export declare function unlockCommand(pid: number | null): string;
+/** A lockfile as a writer saw it at the first refusal of its wait (R3-8). */
+export interface LockObservation {
+    ino: bigint;
+    mtimeNs: bigint;
+    size: bigint;
+    /** When it was seen, by this process's clock. */
+    at: number;
+}
+/** What is at `<logPath>.lock` now, without opening it: a regular file's identity, or `null`. */
+export declare function observeLock(logPath: string, now?: number): LockObservation | null;
+/** Options for {@link reclaimStaleLock}. */
+export interface ReclaimOptions {
+    now?: number;
+    /** The writer's own write-boundary check of the record it would append: a reclaim it would refuse is not made. */
+    recordValid?: (note: ReclaimNote) => boolean;
+    /**
+     * The lockfile as this writer saw it at the first refusal of this wait
+     * ({@link observeLock}). An empty lockfile is taken only when it is that
+     * same file, watched for at least {@link LEGACY_LOCK_WATCH_MS}.
+     */
+    watched?: LockObservation | null;
+    /**
+     * Can this writer append at all right now (its daemon stamp, the log's
+     * tail), and when was the log's last record? Asked before the claim, so a
+     * reclaim whose record would be refused is never made; the last record's
+     * time bounds the `created` the record may carry ({@link plausibleCreated}).
+     * Absent: appendable, with no last record to measure from.
+     */
+    recordContext?: () => RecordContext;
+}
+/**
+ * Judge `<logPath>.lock` once and, when its holder is provably gone, take it:
+ * claim, prove the claim, take. Called by a writer only after its whole lock
+ * timeout has passed. Nothing is written but the stale name (the claim) and
+ * this writer's own lockfile.
+ */
+export declare function reclaimStaleLock(logPath: string, op: LockOp, options?: ReclaimOptions): ReclaimOutcome;
+/** The stale name of a reclaim whose record is now in the log. */
+export declare function finishReclaim(note: ReclaimNote): void;
+/** What {@link takeLockForUnlock} found and did. */
+export type UnlockOutcome = {
+    kind: "taken";
+    own: OwnLock;
+    releaseGuard: () => void;
+    note: ReclaimNote;
+} | {
+    kind: "none";
+} | {
+    kind: "refused";
+    why: string;
+};
+/**
+ * `approval log unlock --pid <n|none>`: a human's take of a lock no writer
+ * reclaims (another container, another boot, a pid that cannot be checked, a
+ * claim whose reclaimer died, a planted stale name). The human asserts that no
+ * writer is running; this refuses only what it can see is wrong: a `--pid`
+ * that is not the record's, a holder it sees running, a lock beside a sync
+ * snapshot, and anything at the lock's path that is not a lockfile (which `rm`
+ * removes). It takes the lock with the same claim and take as a writer's
+ * reclaim, so the record of it (reason `operator-cleared`) is the first under
+ * the lock it takes.
+ */
+export declare function takeLockForUnlock(logPath: string, expected: number | null, lastTs?: number | null, now?: number): UnlockOutcome;
+/**
+ * Hold SIGTERM, SIGINT and SIGHUP from just before a lockfile is created until
+ * just after it is removed, for each signal nobody listens for (the default
+ * disposition would kill the process with the lockfile in place). Returns the
+ * release.
+ *
+ * Node shows a caught signal to JavaScript only when the event loop turns, and
+ * removing the last listener before that turn drops it. So after the release:
+ * a verb that returns or awaits dies of the signal at its next turn;
+ * `approval run` awaits {@link yieldToTerminationSignals} before it spawns, so
+ * a stop request during its append ends it first; and a synchronous wait calls
+ * {@link settleTerminationGuards} before it blocks, so the wait runs under the
+ * default disposition, at the price of losing a signal that landed in the
+ * append's own milliseconds. A create that fails EEXIST releases and settles at
+ * once, so a lock wait runs unguarded (a signal there kills at once, holding
+ * nothing).
+ *
+ * Windows has no such signals to hold; there this is a no-op.
+ */
+export declare function guardTerminationWhileLocked(): () => void;
+/**
+ * Synchronous code about to block (an `Atomics.wait` poll, a `spawnSync`) calls
+ * this first: when no lock is held, the guard is removed now, so the block is
+ * not run with termination signals held. No-op while a lock is held.
+ */
+export declare function settleTerminationGuards(): void;
+/**
+ * Turn the event loop past a poll phase, so a termination signal a released
+ * lock's guard caught is dispatched now and the process dies of it here,
+ * before the caller starts whatever it was about to start.
+ */
+export declare function yieldToTerminationSignals(): Promise<void>;