@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/commands/doctor.d.ts

@@ -0,0 +1,264 @@
+/**
+ * tiphys doctor: deterministic health checks over the current directory as
+ * a fleet home (kernel plan v1, M1-P2 step 3). One line per check, format
+ * "CHECK <name> PASS|WARN|FAIL <detail>", exit 0 only if no check FAILs.
+ * Every check is file-based (substrate-neutral, DR-0007): no process is
+ * ever probed (plan constraint C-2), and no currency is ever read off a
+ * log tail (plan constraint C-1; this phase's checks read no task state,
+ * and any later task-currency check must read tasks/<id>/meta.json and the
+ * turn-end file only).
+ */
+export type CheckStatus = "PASS" | "WARN" | "FAIL";
+export interface CheckResult {
+    name: string;
+    status: CheckStatus;
+    detail: string;
+    /** Names the WARN condition a profile may promote to FAIL (EXT-F-08). */
+    condition?: string;
+}
+/**
+ * Readiness profiles (EXT-F-08): a profile promotes its required WARN
+ * conditions to FAIL, so exit 0 under a profile means ready for that mode
+ * (SC-011: never green by omission). The M1 table is deliberately small
+ * and grows at M2/M3 with the gate registry.
+ */
+export declare const PROFILES: Record<string, readonly string[]>;
+/**
+ * Evaluate a running node version against the kernel's engines.node range.
+ * Fails closed (CR-102): only the exact ">=<major>[.<minor>[.<patch>]]"
+ * form is interpreted, compared over the full version tuple; any other
+ * range shape, and any unparseable version, is FAIL with a reason line,
+ * never a silent truncation.
+ */
+export declare function nodeCheckFor(range: string, version: string): CheckResult;
+/**
+ * THE VERDICT OVER A LEASE THAT HAS BEEN READ (M4-P17 criteria 1 and 2).
+ *
+ * AN EXPIRED LEASE IS A FAIL. Until this phase it was a PASS carrying the
+ * word `(expired)` inside the detail, and that is the H-B shape this
+ * repository keeps paying for: the check's condition was TRUE OF THE
+ * DANGEROUS STATE, so a fleet whose orchestrator died holding the lease
+ * reported `CHECK lock PASS` and doctor exited 0. AGENTS.md's resume clause
+ * says doctor reports "which leases are expired and who last held them"; a
+ * green line with a parenthesis in it is not that report, and an operator
+ * scanning for FAIL lines never saw it.
+ *
+ * The holder id and the expiry are both in the detail because the remedy
+ * needs both: WHO to ask before breaking the lease, and WHEN it lapsed.
+ *
+ * `nowMs` IS A PARAMETER, and that is what makes criterion 2's boundary
+ * member testable at all. `Date.now()` cannot be driven to a chosen
+ * millisecond from outside the process, so a lease whose expiry is exactly
+ * the current instant is unreachable through the CLI: by the time doctor
+ * runs, the instant has passed and the case under test is the interior one
+ * again. The caller above passes the clock; the witness passes an instant.
+ *
+ * THE COMPARISON IS NOT MADE HERE. `expiryHasPassed` (src/lock.ts) owns it,
+ * so doctor and the lock module cannot return two verdicts about one lease.
+ * That is the same rule checkBeacon follows for `judgeBeacon`, and it was
+ * written down there after a delta review found doctor carrying its own copy
+ * of the beacon comparison and missing a floor the module had.
+ */
+export declare function lockCheckFor(holderId: string, expiresAt: string, nowMs: number): CheckResult;
+/**
+ * The installed kernel's own package root: the first ancestor of THIS MODULE
+ * carrying a `package.json`.
+ *
+ * **This is deliberately NOT `kernelRoot()` from src/roles.ts, and the reason
+ * is the whole point of the check.** That function walks upward looking for a
+ * `roles/` directory containing a `.md` file, which is the very artifact this
+ * check exists to find missing: against an install with `roles/` removed it
+ * walks PAST the install and answers about an ancestor, and where no ancestor
+ * carries one it throws. A check built on it reports on the wrong tree or
+ * crashes on precisely the state its own criteria describe.
+ *
+ * Walking for `package.json` does not have that property. `package.json` is
+ * the package BOUNDARY rather than a member of the set under test, and it is
+ * present in both shipped layouts. Measured on this head: the published
+ * package puts this module at `dist/src/commands/doctor.js` with the artifacts
+ * three levels up at the package root, and the development checkout puts it at
+ * `src/commands/doctor.ts` with the artifacts two levels up, while
+ * `dist/package.json` does not exist in the pack listing. So a FIXED DEPTH
+ * from `import.meta.url` is wrong in one of the two layouts and the first
+ * `package.json` above the module is right in both.
+ *
+ * Returns the reason rather than throwing, because a guard whose correctness
+ * depends on a crash is not a guard (mechanism index,
+ * `a-guard-s-own-failure-path`).
+ */
+export declare function resolveInstalledKernelRoot(from?: string): {
+    ok: true;
+    root: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * `kernel-artifacts`: the resolved kernel install carries every artifact M3
+ * made load-bearing (kernel plan M3 section 4, stage E0.4's designated subject;
+ * phase M3-P13).
+ *
+ * WHAT THIS CHECK IS FOR. The brief composer resolves `roles/`, the validator
+ * loads `schemas/`, the checklist command resolves `checklists/`, and
+ * `AGENTS.md` is the policy document every role brief points at. Until now an
+ * install that lost one of them reported nothing wrong: the loss surfaced later
+ * as one command's resolution failure, whose message names the path it could
+ * not open rather than the state of the install. doctor is the command whose
+ * whole job is answering "is this environment fit to run", and the kernel's own
+ * artifacts were the one input none of its checks looked at.
+ *
+ * EVERY missing artifact is named, not the first (decision D-2): a check that
+ * names one sends its reader round the loop once per missing item, and the loop
+ * here is a reinstall.
+ *
+ * The condition is `kernel-artifacts-incomplete`, promoted to FAIL under the
+ * `full` profile and left a WARN below it. Below `full` no command that needs
+ * these artifacts is necessarily in the pipeline, and promoting everywhere is
+ * how a check like this ends up failing a fleet that never needed it.
+ */
+export declare function checkKernelArtifacts(resolution?: ReturnType<typeof resolveInstalledKernelRoot>): CheckResult;
+/**
+ * CHECK tasks (M4-P17 criterion 3): how many tasks are OPEN, and which.
+ *
+ * THE DEFINITION IS THE PLAN'S AND IT IS DELIBERATELY NARROW. A task is open
+ * when `tasks/<id>/meta.json` is there and `tasks/<id>/turn-end` is not. Two
+ * file existences, both under `tasks/`, and nothing else. No log is read
+ * (constraint C-1: currency never comes off the tail of an append-only
+ * stream), and nothing is probed for being alive (constraint C-2: liveness is
+ * lease freshness, never a process). A test in test/doctor.test.ts greps this
+ * function's own source for the four tokens that would mean either constraint
+ * had been broken, because a violation of either is invisible in the output.
+ *
+ * ESTABLISHED, ABSENT, UNUSABLE, AND THEY NEVER PRINT THE SAME WORD. This is
+ * the one thing this check must not get wrong. The kernel already carries a
+ * live instance of the opposite, tracked at
+ * delivery/verification/tracked-doctor-charter-selection.md:1: the retention
+ * check selects charter documents by a raw `kind` read, so a document whose
+ * `kind` cannot be read is SKIPPED, and skipping is indistinguishable from
+ * absence, so the command reports PASS over a fleet it could not examine. A
+ * fourth check with that shape would be worse than no check.
+ *
+ * So every candidate under `tasks/` lands in exactly one of three buckets and
+ * the third is reported by name:
+ *
+ *   - open      meta.json is a regular file, turn-end is absent
+ *   - closed    meta.json is a regular file, turn-end is a regular file
+ *   - UNUSABLE  anything else: no meta.json at all, a meta.json or a turn-end
+ *               that is a directory, a named pipe, a dangling link, or a path
+ *               `lstat` itself could not answer about
+ *
+ * An UNUSABLE candidate is a WARN carrying its own condition, never folded
+ * into "closed" and never dropped from the total. A directory under `tasks/`
+ * with no `meta.json` is the common real shape of it, a task half created or
+ * half removed, and the honest report is that the check could not establish
+ * what it is.
+ *
+ * NO PATH HERE IS OPENED. `classifyEntry` (src/task.ts) lstats, stats and
+ * answers a kind; a named pipe at `tasks/<id>/meta.json` is therefore a named
+ * WARN in bounded time rather than a doctor that hangs with no output, which
+ * is the defect CR-520 recorded at the lease path and which this check would
+ * otherwise reintroduce one directory along.
+ */
+export declare function checkTasks(root: string): CheckResult;
+/**
+ * CHECK branches (M4-P17 criterion 5): which branches are PUSHED and NOT YET
+ * MERGED. AGENTS.md's resume clause names this as one of the three things
+ * doctor reports after a reclaim, and it was the one with no implementation.
+ *
+ * PUSHED means a remote-tracking ref exists for it, which is the only
+ * evidence available locally that the branch is somewhere other than this
+ * disk. UNMERGED means the trunk does not already contain it.
+ *
+ * IT REPORTS EVERY PUSHED REF RATHER THAN FILTERING TO A NAMING PATTERN, and
+ * that is a decision rather than an omission. At least two branch spellings
+ * are in use across the repositories this kernel runs over: the pool names
+ * task branches `task/<id>` (src/pool.ts:54), and a delivery process running
+ * on this kernel names phase branches with its own harness prefix followed by
+ * a milestone and phase segment. A filter written for either is blind to the
+ * other, and a check that is blind to a branch is worse than one that names a
+ * branch the reader already knew about. A superset prints rows a reader can
+ * skip; a filter that misses a branch prints nothing at all, and nothing is
+ * what a healthy fleet prints too.
+ *
+ * NO BRANCH PREFIX IS SPELLED OUT HERE, and that is not a style choice.
+ * test/schemas.test.ts:800 asserts by name which shipped files carry the
+ * harness-derived branch prefix and exists to stop that set GROWING; writing
+ * the literal prefix into this comment added src/commands/doctor.ts to it and
+ * reddened that test. The spelling belongs in the delivery process that uses
+ * it, not in the kernel that reports over any of them.
+ *
+ * WARN, AND NO PROFILE PROMOTES IT TO FAIL. The reason is measured and is not
+ * a preference. Deleting a remote ref is REFUSED in the container this kernel
+ * is built in, and `git push --dry-run --delete` exits 0 whether deletion is
+ * allowed or not, so the dry run cannot tell an operator whether the remedy is
+ * even available (CLAUDE.md standing warning 14). A promotable branch check
+ * would therefore make `tiphys doctor --for full` unpassable on the kernel's
+ * own fleet, with no action its operator could take, and an unpassable check
+ * is a check that gets switched off. The count is printed; the exit code does
+ * not move. A test walks every profile in PROFILES and asserts that, so a
+ * later profile cannot promote it by accident.
+ *
+ * AND IT NEVER PRINTS PASS FOR A QUESTION IT COULD NOT ASK. If git refuses to
+ * list the refs, or the trunk cannot be resolved, the check says so under its
+ * own condition instead of reporting an empty list as a clean bill of health.
+ * An empty result from a query that failed is indistinguishable from an empty
+ * result from a query that succeeded, which is the third way this repository
+ * has shipped a guard that could not go red.
+ */
+export declare function checkBranches(root: string): CheckResult;
+/**
+ * CHECK worktrees (M4-P19): every entry in the worktree pool, and whether a
+ * pool record still exists beside it.
+ *
+ * THE STATE THIS REPORTS IS THE POST-RECLAIM ONE. `worktrees/` is
+ * gitignored (src/fleet.ts:28) and `tasks/` is tracked, so a reclaim takes
+ * every worktrees/<id>.pool.json with it and leaves the task records
+ * standing. Before this check, nothing in the kernel said so: `pool list`
+ * enumerated records, and a task whose record was gone was invisible to
+ * every reporting path.
+ *
+ * WARN AND NEVER FAIL, AND NOT PROMOTED BY ANY PROFILE. The condition is
+ * named (`worktree-record-missing`) so a later profile CAN promote it, and
+ * none does, deliberately: a fleet that has just been rehydrated from its
+ * remote is EXPECTED to be in exactly this state, so promoting it would
+ * make `doctor --for full` unpassable on the one fleet the remedy exists
+ * for, and an unpassable check is a check that gets switched off (hazard
+ * H-D). The number is printed; the exit code does not move.
+ *
+ * It reads tasks/<id>/meta.json and git, never a log tail (C-1), and
+ * probes no process (C-2).
+ */
+export declare function checkWorktrees(root: string): CheckResult;
+/**
+ * CHECK shared-lock (M4-P22 criterion 1): who holds this fleet ACROSS
+ * environments, in exactly one of four statuses.
+ *
+ * CHECK lock above reports the lease on THIS filesystem, which is the only
+ * thing it can report: src/lock.ts:63 states that domain honestly, and
+ * M4-P20 measured two clones of one fleet remote both holding their own
+ * lease at once. This check reports the second layer M4-P21 built, and the
+ * two are separate lines on purpose, because they answer different questions
+ * and an operator reading one of them is entitled to know the other was not
+ * merged into it.
+ *
+ * THE VERDICT IS NOT MADE HERE. `sharedLockStatus` (src/exclusion.ts) owns
+ * it, exactly as `expiryHasPassed` owns CHECK lock's comparison and
+ * `judgeBeacon` owns CHECK beacon's. This check only decides how to present
+ * a status, so doctor and the exclusion layer cannot return two verdicts
+ * about one register.
+ *
+ * THE FOURTH STATUS IS NEVER PASS, which is this check's whole reason for
+ * having four. An unreachable register absorbed into a green line is the
+ * H-C shape: the bundle says fine and the one question that mattered was
+ * never asked. It is a WARN under its own condition so an operator sees it
+ * without doctor exiting nonzero on a fleet that never opted in, and `full`
+ * promotes it (see the PROFILES table).
+ *
+ * IT SPAWNS NOTHING FOR A FLEET THAT HAS NOT OPTED IN. `sharedLockStatus`
+ * reads the fleet home's own package.json first and returns `not-declared`
+ * before any git call, so the cost of this check on every existing fleet is
+ * one file read.
+ */
+export declare function checkSharedLock(root: string): CheckResult;
+export declare function runChecks(root: string): CheckResult[];
+export declare function cmdDoctor(args: string[]): number;