@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/liveness.js

@@ -0,0 +1,396 @@
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { classifyEntry, readRegularFileIfPresent, readTaskMeta } from "./task.js";
+/**
+ * Defaults, in seconds. FM-044 is a calibration starting point, not a
+ * measured optimum, and these are chosen so the PR-009 invariant holds
+ * with room to spare (900 + 15 = 915 < 1200).
+ */
+export const DEFAULT_BASE_INTERVAL_SECONDS = 60;
+export const DEFAULT_POLL_INTERVAL_SECONDS = 15;
+export const DEFAULT_BACKOFF_CAP_SECONDS = 900;
+export const DEFAULT_STALE_THRESHOLD_SECONDS = 1200;
+/**
+ * Environment overrides. The watch command also carries --interval,
+ * --poll and --backoff-cap flags for a single invocation (the M1-P6
+ * harness needs the cadence short); these variables exist because the
+ * guard runs inside spawn, teardown and doctor, which have no watch
+ * flags, and because a fleet's cadence and its freshness threshold have
+ * to agree across all four commands.
+ */
+export const ENV_BASE_INTERVAL = "TIPHYS_WATCH_INTERVAL_SECONDS";
+export const ENV_POLL_INTERVAL = "TIPHYS_WATCH_POLL_SECONDS";
+export const ENV_BACKOFF_CAP = "TIPHYS_WATCH_BACKOFF_CAP_SECONDS";
+export const ENV_STALE_THRESHOLD = "TIPHYS_WATCH_STALE_SECONDS";
+function secondsFromEnv(env, key, fallbackSeconds) {
+    const raw = env[key];
+    if (raw === undefined || raw === "") {
+        return fallbackSeconds * 1000;
+    }
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`${key}="${raw}" is not a positive number of seconds`);
+    }
+    return value * 1000;
+}
+/**
+ * The PR-009 invariant, enforced wherever a cadence is built (at module
+ * load for the process-wide one, and again for every set of watch
+ * flags). The message names both sides because the operator has to know
+ * which of the two to change.
+ */
+export function assertCadenceInvariant(cadence) {
+    const floorMs = cadence.backoffCapMs + cadence.pollIntervalMs;
+    if (cadence.staleThresholdMs > floorMs) {
+        return;
+    }
+    throw new Error(`invalid watcher cadence: stale threshold ${String(cadence.staleThresholdMs)}ms ` +
+        `is not strictly greater than backoff cap ${String(cadence.backoffCapMs)}ms plus ` +
+        `one poll interval ${String(cadence.pollIntervalMs)}ms (${String(floorMs)}ms), so a ` +
+        `watcher idling at maximum backoff would read as stale (PR-009)`);
+}
+/** Build a cadence from environment overrides, validated. */
+export function loadCadence(env) {
+    const cadence = {
+        baseIntervalMs: secondsFromEnv(env, ENV_BASE_INTERVAL, DEFAULT_BASE_INTERVAL_SECONDS),
+        pollIntervalMs: secondsFromEnv(env, ENV_POLL_INTERVAL, DEFAULT_POLL_INTERVAL_SECONDS),
+        backoffCapMs: secondsFromEnv(env, ENV_BACKOFF_CAP, DEFAULT_BACKOFF_CAP_SECONDS),
+        staleThresholdMs: secondsFromEnv(env, ENV_STALE_THRESHOLD, DEFAULT_STALE_THRESHOLD_SECONDS),
+    };
+    assertCadenceInvariant(cadence);
+    return cadence;
+}
+/**
+ * Apply per-invocation overrides (the watch flags) and re-validate, so
+ * a short --backoff-cap or a long one can never quietly break the
+ * invariant the guard depends on.
+ */
+export function withCadenceOverrides(base, overrides) {
+    const cadence = { ...base, ...overrides };
+    assertCadenceInvariant(cadence);
+    return cadence;
+}
+/**
+ * The process-wide cadence. Building it at module load is what makes
+ * criterion 12's second clause real: importing this module under a
+ * configuration that violates the invariant FAILS, with both values in
+ * the message, instead of running on with a guard that cries wolf.
+ */
+export const CADENCE = loadCadence(process.env);
+export function renderBeacon(record) {
+    return `${JSON.stringify(record, null, 2)}\n`;
+}
+/**
+ * Read the beacon, or undefined when it is absent, is not a regular file,
+ * cannot be read, or does not parse. All of those are the same thing to
+ * the guard: no evidence that supervision ran. That is the
+ * fail-toward-warning direction, and for an advisory that never blocks it
+ * is the right one.
+ *
+ * The type probe is INSIDE this reader (CR-520). It is not enough for
+ * judgeBeacon to have lstat'ed the path first: that call establishes
+ * PRESENCE, not TYPE, and this reader has a second caller in
+ * src/watcher.ts (writeBeacon) which does not lstat at all. A probe in
+ * front of one caller protects one caller.
+ */
+export function readBeacon(beaconPath) {
+    const read = readRegularFileIfPresent(beaconPath);
+    if (read.kind !== "read") {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(read.body);
+    }
+    catch {
+        return undefined;
+    }
+    const candidate = parsed;
+    if (typeof candidate.writtenAt !== "string" ||
+        Number.isNaN(Date.parse(candidate.writtenAt)) ||
+        typeof candidate.backoffStreak !== "number" ||
+        typeof candidate.intervalMs !== "number") {
+        return undefined;
+    }
+    return candidate;
+}
+/**
+ * How far a beacon may sit in the FUTURE before it stops counting as
+ * evidence. Nothing legitimate puts it there: writeBeacon stamps the
+ * current time and only ever bumps by a millisecond to keep the advance
+ * strict. A beacon well ahead of the local clock means the clock moved
+ * backwards under a running watcher (an NTP step, a suspend and resume,
+ * a session resumed on another host), and until it is rewritten from the
+ * present it proves nothing about whether supervision is still running.
+ * The allowance absorbs ordinary jitter and the monotonic bump.
+ */
+export const BEACON_FUTURE_TOLERANCE_MS = 5000;
+/**
+ * THE ONE CLASSIFIER OF TASK RECORDS. src/watcher.ts and this module both
+ * call it, and neither has a second opinion about what a task record is.
+ *
+ * This exists because the fix round wrote the same classification twice
+ * with different conditions, and the copies disagreed: one asked whether
+ * the meta path was a regular FILE, the other only that a stat succeeded,
+ * so a meta.json that existed as a directory was surfaced by the watcher
+ * and reported by the guard as nothing in flight, which is a
+ * counterexample to the very property that round declared (delta review
+ * NEW-1, and tuition T-005 on rules that fail to propagate). One property
+ * gets one implementation; two that agree today drift the moment someone
+ * edits one of them.
+ *
+ * The rules, in one place:
+ *
+ * - A TASK IS A DIRECTORY under tasks/. The entry is resolved with stat,
+ *   so a symlink to a real task directory is a task; init's own .gitkeep
+ *   and any other stray file is not, which is checked by TYPE and never
+ *   by name.
+ * - A record that PARSES is authoritative: its status decides open or
+ *   closed (plan constraint C-1).
+ * - THE RECORD IS PROBED BEFORE IT IS READ, AND THE PROBE IS NOT HERE.
+ *   Only a path that resolves to a REGULAR FILE is ever opened; anything
+ *   else that exists there (a directory, a FIFO, a socket, a device node,
+ *   a symlink resolving to any of those, a dangling symlink) is classified
+ *   as a record that cannot be read WITHOUT opening it. That ordering is
+ *   load-bearing: opening a FIFO with no writer blocks in the kernel and
+ *   is not an exception, so a classifier that read first would hang
+ *   instead of classifying, and would take the guard's three callers down
+ *   with it.
+ *
+ *   The ordering is enforced INSIDE readTaskMeta (src/task.ts), not in
+ *   front of the call below. A fix round put it here instead, which
+ *   protected this one call site and left every other caller of
+ *   readTaskMeta exposed; src/teardown.ts is one, and a named pipe at a
+ *   task record hung teardown forever while this classifier reported the
+ *   same file cleanly (CR-520, CR-521). The recorded reason for declining
+ *   to protect the other callers was that it would mean a second reader
+ *   beside readTaskMeta. That reason was wrong: moving the probe INTO
+ *   readTaskMeta is still exactly one implementation of "read a task
+ *   record", and it is the shape now shipped. What this classifier keeps
+ *   is the finer split it genuinely needs, unreadable versus a survey that
+ *   did not complete, computed from the same classifyEntry the reader uses.
+ * - A regular file that does not parse is likewise unreadable: it exists
+ *   and it is not evidence that the task finished.
+ * - NOTHING at the meta.json path is not a record at all: that is the
+ *   normal transient shape of a spawn in progress or a rollback residue.
+ * - Residual, stated rather than papered over: the probe and the read are
+ *   two syscalls, so a path that changes type between them could still be
+ *   opened as something other than a regular file. Nothing in this kernel
+ *   writes that state. The residual is stated once, at classifyEntry.
+ *
+ * Total by construction: it never raises, because one of its two callers
+ * is an advisory that must not be able to take down the command it is
+ * advising. It does not swallow either: what it could not establish comes
+ * back in problems, and both callers are required to act on that.
+ */
+export function surveyTaskRecords(fleet) {
+    const open = [];
+    const unreadable = [];
+    const problems = [];
+    let entries;
+    try {
+        entries = readdirSync(fleet.tasksDir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            // No tasks directory at all. loadFleet refuses a fleet home
+            // missing one, so this is only reachable if it vanished under us,
+            // and an absent directory holds no tasks.
+            return { open, unreadable, problems };
+        }
+        problems.push(`the task directory ${fleet.tasksDir} could not be listed: ${String(error)}`);
+        return { open, unreadable, problems };
+    }
+    for (const id of entries.sort()) {
+        let isTask;
+        try {
+            isTask = statSync(join(fleet.tasksDir, id)).isDirectory();
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                // Removed under us (a concurrent teardown), or a dangling
+                // symlink: no task directory here.
+                continue;
+            }
+            problems.push(`the task entry ${join(fleet.tasksDir, id)} could not be examined: ${String(error)}`);
+            continue;
+        }
+        if (!isTask) {
+            continue;
+        }
+        // PROBE BEFORE READ, through the shared classifier (src/task.ts
+        // classifyEntry) rather than through a copy of it here. This survey
+        // needs a FINER answer than a reader does, because it distinguishes
+        // "there is something unreadable at this record" from "this survey
+        // could not complete", and those go to different counters. It does not
+        // need a second opinion about what is safe to open, and the round that
+        // wrote the probe here rather than in the reader is why six other
+        // paths kept blocking (CR-520).
+        const recordPath = join(fleet.tasksDir, id, "meta.json");
+        const entry = classifyEntry(recordPath);
+        if (entry.kind === "absent") {
+            // No record here at all: a spawn in progress, or a rollback residue.
+            continue;
+        }
+        if (entry.kind === "unexaminable") {
+            problems.push(`the task record ${entry.reason}`);
+            continue;
+        }
+        if (entry.kind === "dangling" || entry.kind === "irregular") {
+            // Present as a link resolving to nothing, or present as something
+            // that is not a file: it exists, and it is not evidence that the
+            // task finished. Classified WITHOUT being opened.
+            unreadable.push(id);
+            continue;
+        }
+        const meta = readTaskMeta(fleet, id);
+        if (meta === undefined) {
+            unreadable.push(id);
+            continue;
+        }
+        if (meta.status === "open") {
+            open.push(id);
+        }
+    }
+    return { open, unreadable, problems };
+}
+/**
+ * THE ONE FRESHNESS THRESHOLD. The configured threshold, raised to the
+ * cadence the WATCHER ITSELF declared in the beacon it wrote plus one
+ * poll interval (CR-503). Every consumer of beacon freshness calls this,
+ * so a single run cannot produce two verdicts about one file.
+ */
+export function effectiveThresholdMs(beacon, cadence) {
+    const declaredFloorMs = beacon === undefined ? 0 : beacon.intervalMs + cadence.pollIntervalMs;
+    return Math.max(cadence.staleThresholdMs, declaredFloorMs);
+}
+export function judgeBeacon(beaconPath, nowMs = Date.now(), cadence = CADENCE) {
+    // Presence and type are two questions and the shared classifier answers
+    // both: absent is the only arm that means "no beacon here". Anything
+    // else present (a dangling symlink per CR-513, a directory, a named
+    // pipe, an entry that cannot even be examined) exists, so it is not
+    // evidence of health, and readBeacon below reduces it to "unreadable"
+    // without opening it.
+    if (classifyEntry(beaconPath).kind === "absent") {
+        return { kind: "absent" };
+    }
+    const beacon = readBeacon(beaconPath);
+    if (beacon === undefined) {
+        return { kind: "unreadable" };
+    }
+    const thresholdMs = effectiveThresholdMs(beacon, cadence);
+    const ageMs = nowMs - Date.parse(beacon.writtenAt);
+    if (ageMs < -BEACON_FUTURE_TOLERANCE_MS) {
+        return { kind: "ahead", aheadMs: -ageMs, thresholdMs };
+    }
+    if (ageMs > thresholdMs) {
+        return { kind: "stale", ageMs, thresholdMs };
+    }
+    return { kind: "fresh", ageMs, thresholdMs };
+}
+/** Counts, for the guard. The classification itself is not repeated. */
+export function surveyTasks(fleet) {
+    const survey = surveyTaskRecords(fleet);
+    return {
+        open: survey.open.length,
+        // A survey that could not complete is counted with the records it
+        // could not read: both mean "work this fleet cannot be shown to be
+        // free of".
+        unreadable: survey.unreadable.length + survey.problems.length,
+    };
+}
+/**
+ * The guard predicate (plan step 2). Total: it never raises, whatever
+ * the filesystem does, because its callers use it as an advisory.
+ *
+ * NO HEALTH FROM AN ABSENCE OF EVIDENCE. "Not stale" is only said when
+ * this function can point at the evidence for it: either nothing is in
+ * flight, or a beacon judged fresh. What counts as work in flight comes
+ * from surveyTaskRecords and what a beacon is evidence of comes from
+ * judgeBeacon; this function decides neither of those questions itself,
+ * so doctor and the guard cannot answer them differently.
+ */
+export function guard(fleet, nowMs = Date.now(), cadence = CADENCE) {
+    const survey = surveyTasks(fleet);
+    const inFlight = survey.open + survey.unreadable;
+    const verdict = judgeBeacon(fleet.beaconPath, nowMs, cadence);
+    const beaconAgeMs = verdict.kind === "fresh" || verdict.kind === "stale" ? verdict.ageMs : undefined;
+    const thresholdSeconds = Math.round((verdict.kind === "absent" || verdict.kind === "unreadable"
+        ? cadence.staleThresholdMs
+        : verdict.thresholdMs) / 1000);
+    const flight = survey.unreadable === 0
+        ? `${String(inFlight)} open task(s)`
+        : `${String(inFlight)} task(s) (${String(survey.unreadable)} with an ` +
+            `unreadable meta.json, which is not evidence they are finished)`;
+    if (inFlight === 0) {
+        return {
+            inFlight,
+            unreadable: survey.unreadable,
+            beaconAgeMs,
+            stale: false,
+            detail: "no open tasks: nothing is in flight to supervise",
+        };
+    }
+    if (verdict.kind === "absent" || verdict.kind === "unreadable") {
+        return {
+            inFlight,
+            unreadable: survey.unreadable,
+            beaconAgeMs,
+            stale: true,
+            detail: `watcher stale: ${flight} in flight and no readable beacon at ` +
+                `${fleet.beaconPath}; start "tiphys watch" or schedule ` +
+                `"tiphys watch --once" at least every ${String(thresholdSeconds)}s`,
+        };
+    }
+    if (verdict.kind === "ahead") {
+        // CR-510: the remediation names the action that actually clears this.
+        // Restarting the watcher does not: writeBeacon keeps a beacon that is
+        // already ahead of the clock ahead of it, one millisecond per
+        // evaluation, so a healthy watcher cannot walk it back.
+        return {
+            inFlight,
+            unreadable: survey.unreadable,
+            beaconAgeMs,
+            stale: true,
+            detail: `watcher stale: ${flight} in flight and the beacon at ${fleet.beaconPath} is ` +
+                `dated ${String(Math.round(verdict.aheadMs / 1000))}s in the FUTURE, so it is ` +
+                `no evidence that supervision ran (the clock moved backwards under it); ` +
+                `remove that file and let the next evaluation write it from the present, ` +
+                `because restarting the watcher alone will not clear it`,
+        };
+    }
+    if (verdict.kind === "stale") {
+        return {
+            inFlight,
+            unreadable: survey.unreadable,
+            beaconAgeMs,
+            stale: true,
+            detail: `watcher stale: ${flight} in flight and ` +
+                `${fleet.beaconPath} is ${String(Math.round(verdict.ageMs / 1000))}s old ` +
+                `(threshold ${String(thresholdSeconds)}s); supervision may have stopped`,
+        };
+    }
+    return {
+        inFlight,
+        unreadable: survey.unreadable,
+        beaconAgeMs,
+        stale: false,
+        detail: `watcher fresh: ${flight} in flight, beacon ` +
+            `${String(Math.round(verdict.ageMs / 1000))}s old`,
+    };
+}
+/**
+ * The one call site shape spawn, teardown and doctor share: evaluate the
+ * guard and, when stale, write exactly one stderr line containing
+ * "watcher stale". It returns the report so a caller can use it, and it
+ * never changes what the caller does next (warn, never block).
+ */
+export function warnIfWatcherStale(fleet, write = (text) => {
+    process.stderr.write(text);
+}) {
+    const report = guard(fleet);
+    if (report.stale) {
+        write(`${report.detail}\n`);
+    }
+    return report;
+}

package/dist/src/lock.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Lease-based session lock (kernel plan v1, M1-P3 step 1; DR-0007; plan
+ * constraint C-2). One orchestrator per fleet: the lock file at
+ * state/orchestrator.lock holds a JSON lease {holderId, hostname,
+ * acquiredAt, expiresAt, durationSeconds, token} where holderId is an
+ * opaque value generated at acquire. Liveness is lease freshness only:
+ * this module never probes any running program in any way (FM-053), and
+ * the death of a holder is deliberately invisible to the lease (an
+ * unexpired lease excludes even when its holder is gone; recovery is the
+ * explicit --take-over after expiry).
+ *
+ * Mutation contract (EXT-F-01, adopted verbatim from the plan):
+ * - Every mutation (acquire, renew, release, takeover) goes through the
+ *   ONE shared atomic mutation primitive, applyLeaseMutation. A mutation
+ *   is decided against an observed lease state and applied only if the
+ *   file still holds exactly that state; the application is confirmed by
+ *   re-reading the unique per-mutation token it wrote. A confirmation
+ *   showing another writer's token means the mutation lost and returns
+ *   failure without retry. Ownership is not valid until the primitive
+ *   completes.
+ * - Renew fails on an expired lease and succeeds only while holderId
+ *   matches and expiresAt is in the future.
+ * - Takeover succeeds only if the observed lease is still the lease being
+ *   replaced (compare-and-swap over the lease file content) and
+ *   serializes with renew, release, and competing takeovers.
+ *
+ * Serialization mechanism: mutations are serialized through a claim file
+ * beside the lock (<lock>.mutex, created O_EXCL; FM-022's
+ * serialize-through-a-claim pattern), and inside that claim the primitive
+ * re-reads the lock, byte-compares it with the observed state, applies
+ * via O_EXCL create (absent lock, PR-006) or write-temp-then-rename, and
+ * confirms by re-reading its own token (FM-022 write-then-verify). No
+ * steal protocol exists on purpose (FM-058): a claim file left behind by
+ * a crashed mutation makes later mutations fail loudly after a bounded
+ * wait, naming the file for manual removal; the critical section is a
+ * few file operations, so this window is tiny.
+ *
+ * What the token confirmation is and is NOT (corrected per D-2; the
+ * previous wording here claimed a second safety net that does not
+ * exist). The confirmation read asserts only "my bytes are in the file
+ * now". That is last-writer-wins: it catches an intruder who applied
+ * AFTER this mutation, and it does NOT catch one who applied before and
+ * merely lost the race to write last. The O_EXCL claim file is
+ * therefore the sole serializer, and it is advisory: no handle is held
+ * on it and nothing checks ownership when it is unlinked. The apply is
+ * preceded by a second read-and-compare (stillMatches) so that a lost
+ * claim degrades to a clean loss instead of a double win, but that
+ * narrows the window rather than closing it. Deleting a live claim file
+ * can still produce two holders; that is why the CLI's remedy text now
+ * says so instead of inviting it.
+ *
+ * Exclusion domain (PR-201, DR-0007 stated honestly): the lease excludes
+ * within one filesystem and one clock, the fleet home the lock file lives
+ * in. Mutations of the lock file made outside this module (manual edits)
+ * are not covered by the contract.
+ *
+ * CROSS-ENVIRONMENT EXCLUSION IS A SECOND LAYER ABOVE THIS ONE (M4-P21),
+ * and it is OFF unless the fleet home declares it. When the fleet's own
+ * `package.json` carries `tiphys.sharedExclusion`, every mutation below
+ * first asks `src/exclusion.ts` for a verdict from the shared register on
+ * the fleet's git remote, and only a won verdict reaches the local lease.
+ * With the field ABSENT, `readSharedExclusion` returns before spawning
+ * anything and every path in this module behaves exactly as it did, which
+ * is the property M4-P21 criterion 1 asserts. The refusal never touches the
+ * lock file, which is what makes the fail-closed behaviour on an
+ * unreachable register observable (criterion 7): no local lease appears.
+ *
+ * Renewal discipline (PR-203): the default lease lasts 900 seconds and
+ * the holder renews at or before half-life (renewByMs). Holdership on
+ * mutating kernel commands (spawn, teardown) is verified against the
+ * lease by M1-P4.
+ */
+export declare const DEFAULT_LEASE_DURATION_SECONDS = 900;
+export interface Lease {
+    holderId: string;
+    hostname: string;
+    acquiredAt: string;
+    expiresAt: string;
+    durationSeconds: number;
+    /** Unique per-mutation witness written by the mutation that produced this content. */
+    token: string;
+}
+export type ObservedLease = {
+    kind: "absent";
+} | {
+    kind: "present";
+    raw: string;
+    lease: Lease | undefined;
+};
+/**
+ * What the shared exclusion layer decided. Present only when the fleet home
+ * declares the layer; the CLI prints `line` verbatim, and `line` always
+ * names which of the two staleness bases reached the verdict, which is
+ * M4-P21 criterion 6.
+ *
+ * THE VERDICT IS CARRIED AS TEXT ON PURPOSE, not as a discriminated field.
+ * The C-2 structural inspection over this file (test/lock.test.ts:534,
+ * M1-P3 criterion 10) forbids a whole vocabulary of process-probing words
+ * from `src/lock.ts`, and it is a blunt case-insensitive grep, which is the
+ * property that makes it hard to defeat by accident. Naming the field after
+ * that vocabulary would have reddened it for a reason that has nothing to do
+ * with C-2, and widening the grep to let this through would weaken a guard
+ * this module is the whole reason for. The classification itself lives in
+ * `src/exclusion.ts`, which no such grep covers, and any caller needing it
+ * as a value reads it there.
+ */
+export interface SharedNote {
+    line: string;
+    envId: string;
+}
+export type LeaseOutcome = {
+    ok: true;
+    lease: Lease;
+    shared?: SharedNote;
+} | {
+    ok: true;
+    lease: null;
+    shared?: SharedNote;
+} | {
+    ok: false;
+    reason: string;
+    shared?: SharedNote;
+    /**
+     * True when the operation failed because a mutation claim file
+     * was still present after the bounded wait (CR-204). A stale
+     * claim is NOT an active lease: reporting it as "lock held"
+     * sends an operator hunting for a holder that does not exist.
+     * Every lease operation (acquire, renew, release) sets this, and
+     * the CLI consumes it to emit the claim-file remedy.
+     */
+    claimTimeout?: boolean;
+};
+export declare function renderLease(lease: Lease): string;
+/**
+ * Read the current lock file state: absent, or present with raw bytes.
+ *
+ * THE ENTRY TYPE IS ESTABLISHED BEFORE THE OPEN (T-008's shape in shipped
+ * code). A bare `readFileSync` here blocked FOREVER with zero output on a
+ * named pipe at the lease path, and took `lock status`, `lock acquire`,
+ * `lock renew` and `lock release` with it, while `tiphys doctor` returned in
+ * the same second against the same FIFO with "is a named pipe, not a regular
+ * file, so it was not opened". Two readers of one path, one of which
+ * established the type; this is now the same reader.
+ *
+ * A refusal THROWS rather than returning a fourth `ObservedLease` variant.
+ * The function already threw on every non-ENOENT error, so the contract its
+ * callers were written against is unchanged, and bin/tiphys.ts turns the
+ * throw into one diagnostic line and a nonzero exit.
+ */
+export declare function observeLease(lockPath: string): ObservedLease;
+/**
+ * THE ONE EXPIRY COMPARISON IN THE KERNEL (M4-P17 criterion 2).
+ *
+ * `isExpired` below needs a whole `Lease`, and doctor's lock check does not
+ * have one: it reads the lease file defensively and holds only `holderId` and
+ * `expiresAt`, because a lease file that fails `parseLease` must still produce
+ * a diagnosis rather than nothing. Before this phase that forced doctor to
+ * carry its own `Date.parse(...) <= Date.now()`, which is a SECOND comparison
+ * of the same property, free to drift from this one. The boundary is where
+ * that drift shows: `<=` makes expiry INCLUSIVE, so a lease whose `expiresAt`
+ * is exactly the current millisecond is expired, and a second copy written
+ * with `<` disagrees for exactly one millisecond and agrees everywhere else.
+ * A disagreement that narrow is not something a reviewer finds by reading.
+ *
+ * So the comparison lives here once and both callers reach it.
+ */
+export declare function expiryHasPassed(expiresAt: string, nowMs: number): boolean;
+export declare function isExpired(lease: Lease, nowMs: number): boolean;
+/** The renew-by deadline (half-life of the current term), for holders. */
+export declare function renewByMs(lease: Lease): number;
+export type MutationResult = {
+    won: true;
+} | {
+    won: false;
+    reason: string;
+    claimTimeout?: boolean;
+};
+/**
+ * The single staging path a lease rename goes through (CR-202). One
+ * fixed name is safe because staging only ever happens inside the
+ * mutation claim, and it makes strand cleanup deterministic.
+ */
+export declare function stagePathFor(lockPath: string): string;
+/**
+ * The one shared atomic mutation primitive (EXT-F-01). Applies next (new
+ * file content, or null to remove the lock) only if the lock file still
+ * holds exactly the observed state, and confirms the application by
+ * re-reading the mutation's own token. Loses without retry otherwise.
+ */
+export declare function applyLeaseMutation(lockPath: string, observed: ObservedLease, next: string | null, token: string): Promise<MutationResult>;
+export interface AcquireOptions {
+    takeover?: boolean;
+    durationSeconds?: number;
+    nowMs?: number;
+    /**
+     * The fleet home this lock belongs to. Derived from lockPath when absent;
+     * named explicitly only by callers whose lock path is not the fleet's
+     * canonical one.
+     */
+    fleetRoot?: string;
+    /**
+     * Staging seam for deterministic race witnesses: the decision is made
+     * against this pre-observed state instead of a fresh read, and the
+     * primitive then refuses if the file moved on. Normal callers omit it.
+     */
+    observed?: ObservedLease;
+}
+/**
+ * Acquire the lease, or take over an expired one when takeover is set.
+ * Refusals (lock held, expired without takeover, unexpired takeover)
+ * never mutate the file; only won mutations do.
+ */
+export declare function acquireLease(lockPath: string, options?: AcquireOptions): Promise<LeaseOutcome>;
+export interface RenewOptions {
+    durationSeconds?: number;
+    nowMs?: number;
+    /** See AcquireOptions.fleetRoot. */
+    fleetRoot?: string;
+    /** Staging seam for deterministic race witnesses; see AcquireOptions. */
+    observed?: ObservedLease;
+}
+/**
+ * Renew the lease held by holderId. Fails on an expired lease even when
+ * holderId matches (EXT-F-01: a paused holder whose lease expired cannot
+ * renew), fails on a holder mismatch, and never mutates the file on any
+ * failure. The new expiry strictly increases (a renew that does not
+ * extend the lease would be useless).
+ */
+export declare function renewLease(lockPath: string, holderId: string, options?: RenewOptions): Promise<LeaseOutcome>;
+export interface ReleaseOptions {
+    /** Staging seam for deterministic race witnesses; see AcquireOptions. */
+    observed?: ObservedLease;
+    /** See AcquireOptions.fleetRoot. */
+    fleetRoot?: string;
+    /** Decision clock, for the shared layer. Defaults to Date.now(). */
+    nowMs?: number;
+}
+/**
+ * Release the lease held by holderId. Expiry does not block a release
+ * (an expired former holder may clean up its own lease), but a holder
+ * mismatch refuses, so a losing holder can never remove the winner's
+ * lease; and the compare-and-swap in the primitive means a release
+ * staged before a takeover completes loses to it.
+ */
+export declare function releaseLease(lockPath: string, holderId: string, options?: ReleaseOptions): Promise<LeaseOutcome>;
+export type LeaseStatus = {
+    state: "free";
+} | {
+    state: "held" | "expired";
+    lease: Lease;
+} | {
+    state: "corrupt";
+    detail: string;
+};
+/** Report the lock state; reading only, never mutating (always safe). */
+export declare function leaseStatus(lockPath: string, nowMs?: number): LeaseStatus;