@tiphys/kernel 0.0.0 → 0.1.0

package/dist/src/version.d.ts

@@ -0,0 +1,3 @@
+export declare function readOwnVersion(): string;
+/** The version subcommand: print the package.json version, exit 0. */
+export declare function printVersion(): number;

package/dist/src/version.js

@@ -0,0 +1,38 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Locate this package's own package.json by walking up from the running
+ * module's directory. The walk is depth-independent on purpose: the same
+ * source runs from src/ (native type stripping) and from dist/src/
+ * (compiled output), which sit at different depths below the package root.
+ */
+function findOwnPackageJson() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        const candidate = join(dir, "package.json");
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new Error("package.json not found above " + import.meta.url);
+        }
+        dir = parent;
+    }
+}
+export function readOwnVersion() {
+    const raw = readFileSync(findOwnPackageJson(), "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        typeof parsed.version !== "string") {
+        throw new Error("package.json has no string version field");
+    }
+    return parsed.version;
+}
+/** The version subcommand: print the package.json version, exit 0. */
+export function printVersion() {
+    process.stdout.write(`${readOwnVersion()}\n`);
+    return 0;
+}

package/dist/src/watcher.d.ts

@@ -0,0 +1,275 @@
+import type { Fleet } from "./fleet.ts";
+import type { WatchCadence } from "./liveness.ts";
+/**
+ * The watcher (kernel plan v1, M1-P5 step 1; R-078, R-079; DR-0007;
+ * plan constraints C-1, C-2 and C-3).
+ *
+ * ONE CORE, TWO ENTRY MODES (DR-0007). Resident mode (tiphys watch) is a
+ * plain foreground process the caller owns. Single-pass mode (tiphys
+ * watch --once) performs exactly one evaluation of the same wake sources
+ * and exits, for external triggers on reclaimable substrates. Both modes
+ * run the same evaluation function over the same on-disk state; there is
+ * no adapter and no second implementation.
+ *
+ * C-3, and why there is nothing here to guard: the kernel never runs a
+ * watcher outside the caller's own foreground process. No flag exists
+ * that would make it outlive its caller, this module launches no child
+ * process of any kind, and arming is explicit: the operator starts it
+ * and the beacon is what proves it ran (FM-054, where about 30 minutes
+ * of supervision were lost to a shell that helpfully moved one out of
+ * sight).
+ *
+ * C-2: nothing here has any notion of a running program. Wake sources
+ * are FILES, currency comes from files, and the only clock question ever
+ * asked is "is this timestamp older than that one".
+ *
+ * C-1: task currency is read from tasks/<id>/meta.json status and the
+ * turn-end file, never from a log tail. state/last-wake.json is written
+ * and never read back by any code path in this kernel; deleting it or
+ * filling it with garbage changes no decision this module makes.
+ *
+ * REASON LINES (grammar harvested from firstmate, FM-002):
+ *
+ *   signal <task-id> turn-end   a turn-end file appeared for an open task
+ *   stale <task-id> deadline    an open task passed its executor.json
+ *                               deadline with no turn-end (PR-207)
+ *   check <name>                a one-shot check was requested through
+ *                               state/check-request
+ *   heartbeat <n>               the nth heartbeat since the last reset
+ *
+ * A wake is ONE line on stdout and then exit 0. The watcher surfaces
+ * wakes and never classifies, triages or absorbs them (FM-057:
+ * firstmate's absorb-triage grew to most of its 1126 lines because its
+ * completion signals were weak; a proposal to add classification here is
+ * a signal-design red flag, not a feature request).
+ *
+ * THE STALE ENUMERATION, and why it has exactly two entries in M1. The
+ * plan's grammar is "stale <what>" for "an open task whose worktree or
+ * meta is in a contradictory state, enumerated in the module docs", and
+ * PR-207 names the first entry:
+ *
+ *   stale <task-id> deadline   the executor record's deadline passed and
+ *                              no turn-end arrived (PR-207)
+ *   stale <task-id> meta       tasks/<id>/meta.json EXISTS and does not
+ *                              parse, so this module cannot establish
+ *                              whether the task is open (fix round,
+ *                              second reviewer finding 2)
+ *
+ * The second entry is the plan's own "meta is in a contradictory state"
+ * clause, not an invention: a record that exists and cannot be read is
+ * the one case where staying quiet would mean asserting "nothing to
+ * supervise here" from evidence this module does not have. A task
+ * directory with NO meta.json at all is a different thing (a spawn in
+ * progress or a rollback residue) and is not surfaced.
+ *
+ * Tuition T-002 asked for "task open, no turn-end, worktree dirty" as a
+ * wake condition; the declared-deadline half of that is what this module
+ * detects, from file evidence alone, and it is witnessed against a spawn
+ * that was genuinely stopped mid-payload rather than against a
+ * hand-built file state. The deadline-less half is not invented here,
+ * because the plan's own not-proven list states that abandonment of a
+ * task launched WITHOUT a deadline is not auto-detected in M1.
+ *
+ * WHAT AN EVALUATION IS, and why it matters for the beacon (PR-206,
+ * PR-009). An EVALUATION is a pass over the wake sources that also
+ * rewrites state/watcher.beacon: it happens when a resident watcher
+ * starts, on every heartbeat tick, whenever a wake is surfaced, and on
+ * every watch --once pass including a no-wake one. Between heartbeats a
+ * resident watcher SCANS its wake sources every poll interval (and
+ * immediately on a filesystem change); a scan that surfaces nothing
+ * writes nothing. That is what makes the beacon mean "supervision
+ * executed on schedule" rather than "a process is alive", and it is what
+ * puts the oldest healthy beacon age at one backoff cap plus one poll
+ * interval, which is the bound the guard's threshold has to clear
+ * (PR-009, enforced in src/liveness.ts).
+ *
+ * CADENCE LIVES ON DISK (FM-006, FM-045), never in process memory, so a
+ * resident restart and a single pass share one schedule:
+ * state/watcher.cadence.json holds {lastHeartbeatAt, backoffStreak}. On
+ * a virgin fleet the first evaluation initializes it to the current time
+ * and surfaces no heartbeat; the first heartbeat falls due one base
+ * interval later (PR-205).
+ *
+ * Turn-end currency (PR-204). A turn-end wake is surfaced at most once
+ * across both modes. state/watcher.seen.json records, per task, the
+ * identity of the last surfaced turn-end (size, modification time and a
+ * content signature, FM-005). The record is advanced under a claim file,
+ * written stage-then-rename and confirmed by reading it back, which is
+ * the discipline src/lock.ts established (it is mirrored rather than
+ * reused: the lock's primitive is lease-shaped and src/lock.ts is not in
+ * this phase's edit scope). The wake is appended to state/last-wake.json
+ * BEFORE the seen record advances (enqueue-before-suppress, FM-046: a
+ * stop between the two duplicates a wake rather than dropping it). Two
+ * passes racing on the same turn-end therefore resolve to exactly one
+ * surfacing; the loser reports no-wake.
+ *
+ * NO HEALTH FROM AN ABSENCE OF EVIDENCE (fix round, the property both
+ * reviewers' blocking findings share). Silence from this module means
+ * "there is nothing to surface", and it may only be said about states
+ * this module has POSITIVELY ESTABLISHED. Wherever it cannot establish
+ * one, the output is the loud one, never the quiet one:
+ *
+ *   - a seen-state claim it could not take within the bounded wait is a
+ *     STUCK CLAIM, not ordinary contention: nonzero exit, one reason
+ *     line naming the file, and NO beacon write, so the guard sees
+ *     supervision stop. This is src/lock.ts's rule, adopted verbatim
+ *     rather than reinvented (see the note below).
+ *   - a meta.json that exists and does not parse is surfaced as
+ *     "stale <task-id> meta" rather than skipped.
+ *   - any other raise ends the pass loudly (see the classification
+ *     below).
+ *
+ * WHERE THE STUCK-CLAIM RULE COMES FROM, recorded because it should have
+ * reached this module the first time and did not: src/lock.ts's
+ * applyLeaseMutation has used the identical O_EXCL claim-file pattern
+ * since M1-P3, and its module doc (src/lock.ts, "No steal protocol
+ * exists on purpose (FM-058)") states the rule this module now follows:
+ * a claim file left behind by a mutation that stopped makes later
+ * mutations FAIL LOUDLY after a bounded wait, naming the file for manual
+ * removal, and no code ever breaks someone else's claim. That behavior
+ * was established by M1-P3's CR-204 after the U-2 race investigation
+ * (delivery/verification/u2-race-flake-investigation.md,
+ * delivery/review/clean-room-m1-p3.md). The first draft of this module
+ * copied the mechanism and dropped the loudness, which the second
+ * M1-P5 reviewer reproduced as a permanent, silent loss of every future
+ * turn-end wake. Anyone adding a third claim-file user should read
+ * src/lock.ts first.
+ *
+ * HOW A RAISED ERROR IS CLASSIFIED, decided once and applied
+ * structurally, because this module does filesystem work in a loop and
+ * the previous phase's two worst defects were raises walking past
+ * handlers that only understood returned failures (M1-P4 F-1 and F-2):
+ *
+ *   - A file that is ABSENT is not an error. Task directories appear and
+ *     vanish under a concurrent teardown, so every read of task state
+ *     goes through a helper that turns ENOENT into "not there" and
+ *     rethrows everything else.
+ *   - Any OTHER raise ends the pass with a reason line and a nonzero
+ *     exit. The watcher stops loudly instead of looping blind: a stopped
+ *     watcher stops advancing the beacon, and the liveness guard then
+ *     tells the operator on the next spawn, teardown or doctor.
+ *   - The whole pass is wrapped by runStep (src/task.ts), so this holds
+ *     for every site in it without depending on remembering it at each.
+ */
+/** Exit code of a --once pass that found nothing actionable. */
+export declare const NO_WAKE_EXIT = 3;
+/** Wake-source and cadence state files, all under the fleet's state/. */
+export declare const CADENCE_STATE_FILE: string;
+export declare const SEEN_STATE_FILE: string;
+export declare const LAST_WAKE_FILE: string;
+export declare const CHECK_REQUEST_FILE: string;
+export declare function cadencePath(fleet: Fleet): string;
+export declare function seenPath(fleet: Fleet): string;
+export declare function lastWakePath(fleet: Fleet): string;
+export declare function checkRequestPath(fleet: Fleet): string;
+/** Identity of a turn-end file (FM-005), the seen-state's unit. */
+export interface SignalIdentity {
+    size: number;
+    mtimeMs: number;
+    signature: string;
+}
+export type SeenState = Record<string, SignalIdentity>;
+export declare function sameIdentity(a: SignalIdentity, b: SignalIdentity): boolean;
+export declare function readSeenState(fleet: Fleet): SeenState;
+/** Cadence state (JSON per DR-0006, plan decision D-3). */
+export interface CadenceState {
+    lastHeartbeatAt: string;
+    backoffStreak: number;
+}
+export declare function readCadenceState(fleet: Fleet): CadenceState | undefined;
+export declare function writeCadenceState(fleet: Fleet, state: CadenceState): void;
+/** The doubling heartbeat interval, capped (FM-044). */
+export declare function intervalMsFor(streak: number, cadence: WatchCadence): number;
+/** When the next heartbeat falls due, from on-disk state alone. */
+export declare function nextHeartbeatDueMs(state: CadenceState, cadence: WatchCadence): number;
+/**
+ * Rewrite the beacon. The timestamp STRICTLY increases even when two
+ * evaluations land in the same millisecond, because criterion 8 turns on
+ * a no-wake pass advancing it and "advanced" has to mean something a
+ * reader can compare.
+ */
+export declare function writeBeacon(fleet: Fleet, nowMs: number, streak: number, cadence: WatchCadence): number;
+/** A surfaced wake, or the heartbeat that stands in for one. */
+export type Wake = {
+    kind: "signal";
+    taskId: string;
+    event: "turn-end";
+    identity: SignalIdentity;
+} | {
+    kind: "stale";
+    taskId: string;
+    what: "deadline" | "meta";
+} | {
+    kind: "check";
+    name: string;
+};
+export declare function wakeLine(wake: Wake): string;
+export declare function heartbeatLine(n: number): string;
+export type ScanResult = {
+    ok: true;
+    wake: Wake | undefined;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Scan, with the module's raise classification applied structurally. */
+export declare function scanWakeSources(fleet: Fleet, nowMs: number): ScanResult;
+export type SurfaceResult = {
+    kind: "surfaced";
+    line: string;
+} | {
+    kind: "lost";
+} | {
+    kind: "stuck";
+    reason: string;
+};
+/**
+ * Surface a wake: make it durable, suppress repeats where the plan says
+ * repeats are wrong, and return the line to print. "lost" means another
+ * pass owns this wake and this one must report no-wake; "stuck" means
+ * this pass could not establish anything and must say so out loud.
+ */
+export declare function surfaceWake(fleet: Fleet, wake: Wake, nowMs: number): Promise<SurfaceResult>;
+export interface WatchOptions {
+    cadence: WatchCadence;
+    /**
+     * Resident mode only: exit with a heartbeat line after this many
+     * heartbeats HAVE TICKED IN THIS RUN. It is a bound on the run, not a
+     * position in the schedule, so a bounded run behaves the same way on a
+     * fleet that has been supervised for hours as on a virgin one. The
+     * schedule itself stays on disk (FM-006), which is why the number the
+     * line reports is the cadence ordinal and can be larger than this
+     * bound.
+     */
+    maxHeartbeats: number | undefined;
+    /** Injectable clock; tests use the real one, this is for determinism. */
+    now?: () => number;
+}
+export interface PassOutcome {
+    code: number;
+    /** stdout line, without its newline; empty means print nothing. */
+    line: string;
+    /** stderr reason for a nonzero, non-no-wake outcome. */
+    reason?: string;
+}
+/**
+ * A heartbeat evaluation: advance the streak, record it, rewrite the
+ * beacon. Returns the heartbeat ordinal since the last cadence reset,
+ * which is the n in "heartbeat <n>".
+ */
+export declare function heartbeatTick(fleet: Fleet, state: CadenceState, cadence: WatchCadence, nowMs: number): number;
+/**
+ * Single-pass mode: exactly one evaluation, then exit. A heartbeat that
+ * is due is surfaced (this pass may be the only supervision this fleet
+ * gets), and a pass with nothing actionable prints nothing and exits
+ * with the documented no-wake code. The beacon is rewritten either way
+ * (PR-206).
+ */
+export declare function runOnce(fleet: Fleet, options: WatchOptions): Promise<PassOutcome>;
+/**
+ * Resident mode: a plain foreground loop the caller owns. It evaluates
+ * once at startup (so an already-pending wake is surfaced immediately
+ * and the beacon proves arming), then alternates cheap scans at the poll
+ * interval with heartbeat evaluations on the backoff schedule.
+ */
+export declare function runResident(fleet: Fleet, options: WatchOptions): Promise<PassOutcome>;