@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/pool.d.ts

@@ -0,0 +1,326 @@
+import type { Fleet } from "./fleet.ts";
+/**
+ * Worktree pool over a project clone (kernel plan v1, M1-P3 step 3).
+ * BUILD from the contract (plan decision D-1, FM-026): a clean disposable
+ * worktree per task at <fleet>/worktrees/<task-id>, parallel-safe through
+ * unique paths, O_EXCL record creation, and git worktree add's own
+ * locking. That safety is claimed only at the width M1 actually uses:
+ * criterion 15's two concurrent creates, which are witnessed. This
+ * phase's own verification measured failures above roughly six-way
+ * concurrency on both the fetch and the worktree add, and hardening
+ * for that width is deferred to M5 (see the deferral list in
+ * delivery/work-history/m1-p3.md). Do not read this as a guarantee at
+ * arbitrary concurrency. Substrate-neutral: pure filesystem and git
+ * (DR-0007).
+ *
+ * Base resolution is the five binding steps of EXT-F-03: resolve the
+ * project's configured remote and its default branch, fetch that branch,
+ * record the fetched base SHA in the pool record (and the CLI emits it on
+ * stdout; M1-P4 spawn copies it into tasks/<id>/meta.json as baseSha),
+ * create the task branch and worktree directly from that exact SHA, and
+ * on fetch failure fail rather than silently use a stale local branch,
+ * unless --offline was explicitly passed, in which case the last fetched
+ * remote-tracking SHA is used and offline: true is recorded. The clone's
+ * local branches are never consulted: a stale local branch is never the
+ * base, whether behind or ahead of the remote.
+ *
+ * The pool record lives BESIDE the worktree (worktrees/<task-id>.pool.json,
+ * plain JSON per D-3), never inside it, so the record can never dirty the
+ * destroy-time cleanliness check (FM-059: no exemption list, ever).
+ *
+ * Destroy refuses a dirty worktree (uncommitted changes or untracked
+ * files) unless --discard, which is reserved for the teardown scout path
+ * (PR-010). A transient git index.lock during destroy is retried; the
+ * lock file is removed only under a fail-safe staleness proof (provably
+ * no holder via lsof plus mtime age beyond a threshold; any uncertainty
+ * means leave it and fail loudly), per FM-036 and FM-051.
+ */
+/** Task branch created by the pool at the fetched base SHA. */
+export declare function taskBranchName(taskId: string): string;
+/** Task ids are single safe path segments. */
+export declare const TASK_ID_PATTERN: RegExp;
+export interface PoolRecord {
+    taskId: string;
+    project: string;
+    remote: string;
+    branch: string;
+    baseSha: string;
+    branchName: string;
+    offline: boolean;
+    createdAt: string;
+}
+export type PoolResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * THE BOUND ON A NETWORK-REACHING GIT SUBPROCESS (M4-P19 fix round).
+ *
+ * `spawnSync` with no `timeout` waits for the child forever. For a local
+ * git command that is harmless: it either answers or fails. For one that
+ * opens a socket it is not, and the failure mode is not a slow command,
+ * it is a command that NEVER RETURNS. Measured by the clean-room
+ * reviewer against head abde402: a remote pointed at a TCP listener that
+ * accepts and never speaks made `tiphys pool list` and `tiphys doctor`
+ * run until killed (exit 124 under `timeout 25`), where the same fixture
+ * on the phase base exited 0 in about a second.
+ *
+ * This bound is applied to `ls-remote --symref <remote> HEAD` only, and
+ * the reason it is safe THERE and not elsewhere is a property of the
+ * command rather than a judgement about it: that invocation transfers a
+ * ref advertisement and nothing else, so a legitimate one is bounded by
+ * round-trip latency. `git fetch` (src/pool.ts, src/teardown.ts) and
+ * `git push` (src/teardown.ts) transfer objects, so their legitimate
+ * duration IS unbounded and a wall-clock cap on them would abort real
+ * work. They are left unbounded deliberately, and they are reached only
+ * from a command the operator invoked to do that work, never from a
+ * reporting path; keeping reporting paths off the network entirely is
+ * the other half of this fix (see `reconstructPoolRecord`).
+ *
+ * TIPHYS_GIT_NETWORK_TIMEOUT_MS is a TEST SEAM in the style of
+ * TIPHYS_WATCH_TEST_HOLD (src/watcher.ts) and TIPHYS_LOCK_TEST_HOLD
+ * (src/commands/lock.ts): a test cannot afford to wait out the shipped
+ * bound, and a shipped bound short enough for a test would abort a
+ * legitimate ls-remote over a slow link. A value that is not a positive
+ * integer is IGNORED rather than honoured, so a malformed environment
+ * cannot silently remove the bound.
+ */
+export declare const NETWORK_TIMEOUT_MS = 20000;
+/**
+ * Exported as a PURE function so the validation has a witness that does
+ * not have to wait out a twenty-second bound to observe it. The
+ * end-to-end bound is witnessed separately, against a real remote that
+ * never answers; this is the arm that says a malformed environment
+ * cannot silently switch the bound off.
+ *
+ * `Number("")` is 0 and `Number("0x10")` is 16, so neither a blank value
+ * nor a hexadecimal one is passed through: the accepted set is exactly
+ * the positive integers, and everything else falls back.
+ */
+export declare function resolveNetworkTimeoutMs(raw: string | undefined): number;
+/** Exported for the contention-classification test. */
+export declare function isTransientGitLockError(stderr: string): boolean;
+export declare function recordPath(fleet: Fleet, taskId: string): string;
+export declare function worktreePath(fleet: Fleet, taskId: string): string;
+/**
+ * THE RECORD'S ENTRY TYPE IS ESTABLISHED BEFORE IT IS OPENED. A bare read
+ * here hung `tiphys pool destroy` forever with zero output against a named
+ * pipe at `worktrees/<id>.pool.json`; measured before the fix, `pool list`
+ * (which reads only the NAME) returned in the same second while
+ * `pool destroy --task t-0001` was killed at ten seconds. The two commands
+ * differ by whether this function runs, which is what makes the mechanism
+ * the open and not the command.
+ *
+ * A non-regular record is a REFUSAL rather than `undefined`: `undefined`
+ * already means "there is no record", and a caller that cannot tell that
+ * apart from "the record could not be opened" would rebuild a worktree over
+ * a record it never read.
+ */
+export declare function readPoolRecord(fleet: Fleet, taskId: string): PoolRecord | undefined;
+/**
+ * POST-RECLAIM RECONSTRUCTION (M4-D-12, kernel plan M4 section M4-P19).
+ *
+ * THE RULE, and it is the whole design: RECONSTRUCT FOR REPORTING, NEVER
+ * FOR DESTRUCTION. A reconstructed record exists in memory for the life
+ * of one command and is NEVER written to worktrees/<id>.pool.json, so a
+ * later reader can never mistake a reconstruction for an original.
+ *
+ * THE DEFECT IT CLOSES, measured rather than assumed. tasks/<id>/meta.json
+ * is TRACKED and survives a reclaim; worktrees/<id>.pool.json cannot,
+ * because it sits beside the worktree BY DESIGN so it can never dirty the
+ * destroy-time cleanliness check (see the module header above, FM-059).
+ * Teardown then refuses without a pool record and says so in terms
+ * (src/teardown.ts), so the plan's stated fallback of "recovery is manual
+ * teardown" does not work post-reclaim: the manual path is itself blocked.
+ *
+ * WHAT IS DERIVED AND WHAT IS NOT. meta.json carries six of the eight
+ * PoolRecord fields directly (taskId, project, baseSha, branchName,
+ * offline, createdAt). It carries NEITHER `remote` NOR `branch`, which are
+ * the project's configured remote and that remote's default branch. Those
+ * two are re-derived from git through the SAME two resolvers poolCreate
+ * uses, so a reconstruction is a repeat of the original derivation and
+ * never a remembered value.
+ *
+ * WHEN EITHER OF THOSE TWO CANNOT BE DERIVED THE RESULT IS INCOMPLETE AND
+ * NAMES THE FIELD. It is never filled with a plausible default. "origin"
+ * and "main" are right often enough to look harmless and wrong often
+ * enough to destroy work: a guessed default branch sends the landed-ness
+ * judgement at a ref that is not the project's default, and teardown's
+ * authorization to delete a task branch comes from exactly that judgement
+ * (V-1, the defect src/spawn.ts was rewritten to prevent). An unresolvable
+ * field is therefore a refusal, not a gap to fill.
+ */
+export type ReconstructResult = 
+/** Every field derived. Safe to report, and safe to pass to a GATED path. */
+{
+    kind: "complete";
+    record: PoolRecord;
+}
+/** meta.json read, but git could not answer for the named fields. */
+ | {
+    kind: "incomplete";
+    unresolved: string[];
+    detail: string;
+}
+/** No readable task meta, so there is nothing to reconstruct from. */
+ | {
+    kind: "absent";
+    reason: string;
+};
+/**
+ * What a caller of `reconstructPoolRecord` is permitted to do to answer.
+ *
+ * THE FIELD IS REQUIRED AND THE TYPE IS WHY (M4-P19 fix round). The
+ * reconstruction rebuilds `branch` through `resolveDefaultBranch`, which
+ * falls back to `git ls-remote` when `<remote>/HEAD` is unset locally,
+ * and that fallback opens a socket. `<remote>/HEAD` unset is not an
+ * exotic state: it is the NORMAL state of a clone made by `git init` +
+ * `git remote add` + `git fetch`, which is how this kernel's own tests
+ * and fixtures build one. So the fallback is reached on ordinary fleets,
+ * and a caller that must return, such as `pool list` or `doctor`, must
+ * not reach it.
+ *
+ * Measured against head abde402, where this option did not exist and
+ * every caller got the network: with the remote pointed at a TCP
+ * listener that accepts and never speaks, `tiphys pool list` and
+ * `tiphys doctor` ran until killed. Making the decision a required field
+ * rather than a defaulted one is the part of the fix that survives the
+ * next caller: adding one without choosing does not compile.
+ */
+export interface ReconstructOptions {
+    /**
+     * True only for a caller the operator invoked to CHANGE something and
+     * which may therefore wait on a remote. False for every reporting
+     * path, which then reports `unreconstructable (unresolved: branch)`
+     * rather than blocking.
+     */
+    network: boolean;
+}
+/**
+ * Rebuild a pool record for taskId from tasks/<id>/meta.json and git.
+ * Reads only; writes nothing anywhere, ever.
+ */
+export declare function reconstructPoolRecord(fleet: Fleet, taskId: string, options: ReconstructOptions): ReconstructResult;
+export interface CreateOptions {
+    taskId: string;
+    project: string;
+    offline: boolean;
+}
+/**
+ * pool create (EXT-F-03 five steps; see module doc). Returns the pool
+ * record on success.
+ *
+ * On failure NOTHING IS REMOVED. The pool record, the worktree
+ * directory and the task branch may each survive, depending on how far
+ * the attempt got, and the reason line names exactly which of them did
+ * and the command that clears them. The automatic rollback this
+ * docstring used to promise was deleted deliberately: it served a
+ * concurrent-create path M1 never enters (parallelism is off until M5)
+ * and produced four consecutive rounds of defects, including deleting
+ * state it had not validated. Failing loudly and leaving state is the
+ * chosen contract, not an oversight.
+ */
+export declare function poolCreate(fleet: Fleet, options: CreateOptions): Promise<PoolResult<PoolRecord>>;
+/**
+ * Where an entry's pool record came from. `record` is an original read
+ * from worktrees/<id>.pool.json; the other two exist only after a reclaim
+ * has taken worktrees/ with it, and are computed fresh on every call.
+ */
+export type PoolEntryOrigin = "record" | "reconstructed" | "unreconstructable";
+export interface PoolListEntry {
+    taskId: string;
+    headSha: string;
+    origin: PoolEntryOrigin;
+    /**
+     * Set only for `unreconstructable`: what this listing could not establish.
+     * Usually the PoolRecord fields git could not answer for; `meta` means the
+     * task record itself was present and did not read, which is a different
+     * state from a task that is closed and from one that is not there.
+     */
+    unresolved?: string[];
+}
+/**
+ * One entry per pool record, with the worktree's current HEAD SHA, PLUS
+ * one per OPEN task that has no pool record beside it (M4-P19).
+ *
+ * The second group is what a reclaim leaves behind: tasks/ is tracked and
+ * survives, worktrees/ is gitignored and does not, so a task can be open
+ * with its record gone. Reporting only the first group makes those tasks
+ * invisible to `pool list` and to doctor, which is the state the plan
+ * calls a defect. Every such entry is marked, never silently blended in
+ * with the originals, and NOTHING here is written to disk.
+ *
+ * Closed tasks are excluded: a closed task is not in the pool, and
+ * listing every task this fleet ever finished as a missing worktree would
+ * make the report useless within a week.
+ *
+ * THIS FUNCTION OPENS NO SOCKET (M4-P19 fix round). It reads the
+ * filesystem and runs local git commands, and its reconstruction is
+ * asked for with `{ network: false }`. An entry whose default branch
+ * cannot be established from the clone alone is reported
+ * `unreconstructable (unresolved: branch)` rather than waited on. See
+ * `ReconstructOptions` for the measured hang that this closes.
+ */
+export declare function poolList(fleet: Fleet): PoolListEntry[];
+export interface LsofProbe {
+    available: boolean;
+    exitCode: number | null;
+    stdout: string;
+}
+/** Age a lock file must reach before a staleness proof is even considered. */
+export declare const STALE_LOCK_AGE_MS = 300000;
+/**
+ * Fail-safe staleness proof for a git lock file (FM-036, FM-051): true
+ * only when the lock exists, its mtime age exceeds the threshold, and
+ * lsof is available and shows provably no holder (exit 1, empty stdout).
+ * Any uncertainty (lsof missing, erroring, or listing holders) is false:
+ * the lock is left in place and the operation fails loudly.
+ */
+export declare function provablyStaleLock(lockFile: string, opts?: {
+    nowMs?: number;
+    ageThresholdMs?: number;
+    runLsof?: (path: string) => LsofProbe;
+}): boolean;
+export interface DestroyOptions {
+    taskId: string;
+    /** Override the dirty-worktree refusal (plan step 3, PR-010). */
+    discard: boolean;
+    /**
+     * Authorize deleting a task branch that carries commits beyond its
+     * recorded base (V-1). Deliberately distinct from discard, whose
+     * plan-defined meaning is the dirty-tree override only: conflating
+     * them would make the scout path silently destroy committed work.
+     * M1-P4 teardown passes this from its ship path after its landedness
+     * judgement, which makes the dependency on teardown explicit rather
+     * than assumed.
+     */
+    deleteBranchForce: boolean;
+    /**
+     * An IN-MEMORY reconstructed record (M4-P19), used ONLY when no record
+     * exists on disk. It is never written: `haveRecord` still comes from
+     * the file, so nothing here creates worktrees/<id>.pool.json and
+     * nothing unlinks a file that is not there.
+     *
+     * WHY THIS EXISTS AT ALL, since the whole design is "never for
+     * destruction". Without it, stage 2's base-sha gate has no base to
+     * compare against and returns its "pool record missing or unreadable"
+     * refusal, so the post-reclaim path would be blocked at the one gate
+     * that was ALREADY going to do the right thing. Passing the
+     * reconstruction in makes that gate WORK rather than abstain, which is
+     * strictly safer than the alternative of relaxing it. The caller is
+     * responsible for having derived it (src/teardown.ts's
+     * --from-reconstructed path is the only one), and `pool destroy` on
+     * the command line never sets it.
+     */
+    reconstructed?: PoolRecord;
+}
+/** What a completed destroy removed, for the operator's record. */
+export interface DestroyOutcome {
+    deletedBranch?: string;
+    /** The branch tip at deletion time: the recovery handle (V-1). */
+    deletedSha?: string;
+}
+export declare function poolDestroy(fleet: Fleet, options: DestroyOptions): Promise<PoolResult<DestroyOutcome>>;