@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/task.js

@@ -0,0 +1,307 @@
+import { existsSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/* IMPORTED UNDER THE OLD NAMES rather than re-exported straight through,
+   because this module CALLS them as well as publishing them. A bare
+   `export ... from` publishes without binding, so the internal call sites below
+   would not resolve and the only signal would be a build error. */
+import { classifyPathEntry as classifyEntry, readRegularPathIfPresent as readRegularFileIfPresent, refuseOpenPathForWrite as refuseOpenForWrite, } from "./fleet.js";
+import { leaseStatus } from "./lock.js";
+export { classifyEntry, readRegularFileIfPresent, refuseOpenForWrite };
+export const TASK_SHAPES = ["ship", "scout"];
+export function taskDir(fleet, taskId) {
+    return join(fleet.tasksDir, taskId);
+}
+export function metaPath(fleet, taskId) {
+    return join(taskDir(fleet, taskId), "meta.json");
+}
+export function briefPath(fleet, taskId) {
+    return join(taskDir(fleet, taskId), "brief.md");
+}
+export function turnEndPath(fleet, taskId) {
+    return join(taskDir(fleet, taskId), "turn-end");
+}
+export function executorRecordPath(fleet, taskId) {
+    return join(taskDir(fleet, taskId), "executor.json");
+}
+export function reportPath(fleet, taskId) {
+    return join(taskDir(fleet, taskId), "report.md");
+}
+/** Serialize meta the way every kernel JSON state file is written. */
+export function renderTaskMeta(meta) {
+    return `${JSON.stringify(meta, null, 2)}\n`;
+}
+export function writeTaskMeta(fleet, meta) {
+    writeFileSync(metaPath(fleet, meta.id), renderTaskMeta(meta));
+}
+/** Which required field first failed, or undefined when all of them hold. */
+function firstBadMetaField(candidate) {
+    if (typeof candidate.id !== "string")
+        return "id (a string)";
+    if (typeof candidate.project !== "string")
+        return "project (a string)";
+    if (candidate.shape !== "ship" && candidate.shape !== "scout") {
+        return 'shape (either "ship" or "scout")';
+    }
+    if (typeof candidate.branch !== "string")
+        return "branch (a string)";
+    if (typeof candidate.worktree !== "string")
+        return "worktree (a string)";
+    if (typeof candidate.baseSha !== "string")
+        return "baseSha (a string)";
+    if (typeof candidate.baseOffline !== "boolean")
+        return "baseOffline (a boolean)";
+    if (candidate.status !== "open" && candidate.status !== "closed") {
+        return 'status (either "open" or "closed")';
+    }
+    if (typeof candidate.createdAt !== "string")
+        return "createdAt (a string)";
+    return undefined;
+}
+/**
+ * THE ONE READ of a task record, and the one that says WHICH of the four
+ * outcomes happened.
+ *
+ * The type probe is INSIDE this function and not in front of one of its
+ * callers (CR-520, CR-521). There is exactly one implementation of "read a
+ * task record", every caller of it is protected, and adding a caller
+ * cannot reopen the hole: src/teardown.ts reaches this directly, without
+ * going through the liveness classifier, and a named pipe here used to
+ * hang it forever.
+ *
+ * WHY THIS IS A SEPARATE FUNCTION FROM `readTaskMeta` RATHER THAN ITS NEW
+ * SIGNATURE, declared rather than left to be inferred. Widening the return
+ * type of `readTaskMeta` is the shape this repair wants, and it is a
+ * compile-time break in four modules that this fix round's file list does not
+ * own (src/pool.ts, src/liveness.ts, src/teardown.ts, src/commands/next.ts).
+ * The distinction is therefore made AVAILABLE upstream of all of them here,
+ * `readTaskMeta` is documented as the deliberate NARROWING of it, and the
+ * sites that still collapse are named in the fix round's work history rather
+ * than quietly left.
+ */
+export function classifyTaskMeta(fleet, taskId) {
+    const path = metaPath(fleet, taskId);
+    const read = readRegularFileIfPresent(path);
+    if (read.kind === "absent") {
+        return { kind: "absent" };
+    }
+    if (read.kind === "refused") {
+        return { kind: "unreadable", reason: read.reason };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(read.body);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return {
+            kind: "unparsable",
+            reason: `${path} is present (${read.body.length} byte(s)) and does not parse as ` +
+                `JSON (${detail}), which is what a task record killed mid-write looks ` +
+                `like; it is not evidence that there is no task here`,
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return {
+            kind: "malformed",
+            reason: `${path} parses as JSON but not as an object, so it is not a task record`,
+        };
+    }
+    const candidate = parsed;
+    const bad = firstBadMetaField(candidate);
+    if (bad !== undefined) {
+        return {
+            kind: "malformed",
+            reason: `${path} parses as JSON but is not a task record: it needs ${bad}; it is ` +
+                `not evidence that there is no task here`,
+        };
+    }
+    return { kind: "read", meta: candidate };
+}
+/**
+ * Read meta.json, or undefined when it is absent, is not a regular file,
+ * does not parse, or parses and is not a task record.
+ *
+ * THIS IS A DELIBERATE NARROWING OF `classifyTaskMeta` AND THE COLLAPSE IS THE
+ * WHOLE OF CR-F02. `undefined` answers "is there a readable record" and it
+ * cannot answer "is there a task here", because it is returned both when the
+ * kernel looked and found nothing and when it found something it could not
+ * read. A caller that reports an absence, skips an entry, or decides nothing
+ * is in flight must call `classifyTaskMeta` instead; a caller that REFUSES on
+ * every one of the four (teardown does) loses nothing by using this.
+ */
+export function readTaskMeta(fleet, taskId) {
+    const read = classifyTaskMeta(fleet, taskId);
+    return read.kind === "read" ? read.meta : undefined;
+}
+/** Set meta.json status (teardown's last step; C-1's state authority). */
+export function setTaskStatus(fleet, meta, status) {
+    writeTaskMeta(fleet, { ...meta, status });
+}
+/**
+ * Holdership guard for the task-mutating commands (PR-203), shared by
+ * spawn and teardown so there is exactly one implementation of the rule.
+ * It lives here rather than in a guard module of its own because this
+ * phase's files-to-touch list has no shared-guard file and the rule is a
+ * precondition of every task mutation.
+ *
+ * The transport is M1-P3's, unchanged and not re-invented: lock acquire
+ * PRINTS the opaque holderId, the operator carries it, and here it
+ * arrives as the TIPHYS_HOLDER_ID environment variable. No second
+ * identity mechanism exists, and nothing about the holder is derived
+ * from the running program (plan constraint C-2): this reads the lease
+ * FILE and nothing else.
+ *
+ * With no lease file present the command proceeds (the plan's M1 test
+ * contexts). A lease that exists but is unreadable, expired, or held by
+ * a different holder refuses: fail closed, because every one of those
+ * states means this caller cannot prove it is the one orchestrator.
+ */
+export function checkHoldership(fleet) {
+    const status = leaseStatus(fleet.lockPath);
+    if (status.state === "free") {
+        return { ok: true };
+    }
+    if (status.state === "corrupt") {
+        return {
+            ok: false,
+            reason: `lease file ${fleet.lockPath} exists but does not parse; refusing without provable holdership`,
+        };
+    }
+    const holder = process.env.TIPHYS_HOLDER_ID;
+    if (status.state === "expired") {
+        return {
+            ok: false,
+            reason: `lease ${fleet.lockPath} expired ${status.lease.expiresAt} (holder ` +
+                `${status.lease.holderId}); re-acquire or take over before mutating tasks`,
+        };
+    }
+    if (holder === undefined || holder === "") {
+        return {
+            ok: false,
+            reason: `lease ${fleet.lockPath} is held by ${status.lease.holderId} and ` +
+                `TIPHYS_HOLDER_ID is not set; set it to the holder id lock acquire printed`,
+        };
+    }
+    if (holder !== status.lease.holderId) {
+        return {
+            ok: false,
+            reason: `lease ${fleet.lockPath} is held by ${status.lease.holderId}, not by ` +
+                `TIPHYS_HOLDER_ID ${holder}`,
+        };
+    }
+    return { ok: true };
+}
+/** True when the task directory already exists (spawn's rollback scope). */
+export function taskDirExists(fleet, taskId) {
+    return existsSync(taskDir(fleet, taskId));
+}
+/**
+ * True when tasks/<id>/ already holds a previous incarnation of the task
+ * id, which spawn refuses (CR-301).
+ *
+ * The task directory is the DURABLE record: teardown removes the worktree
+ * and the pool record but deliberately leaves tasks/<id>/ behind, so the
+ * id is free from the pool's point of view and occupied from the task
+ * state's. Spawning into it would overwrite the closed task's records,
+ * hand the launch-failure rollback files it did not create, and leave the
+ * previous incarnation's turn-end file readable while the new
+ * incarnation's meta says open, which is a completion that did not happen
+ * sitting under the C-1 state authority.
+ *
+ * A path that exists but is not a directory counts as occupied too: it is
+ * not a state this kernel may write into, and refusing costs the operator
+ * one rename while guessing could cost the record.
+ */
+export function taskDirOccupied(fleet, taskId) {
+    const dir = taskDir(fleet, taskId);
+    if (!existsSync(dir)) {
+        return false;
+    }
+    try {
+        if (!statSync(dir).isDirectory()) {
+            return true;
+        }
+        return readdirSync(dir).length > 0;
+    }
+    catch {
+        // Unreadable is not empty: fail closed.
+        return true;
+    }
+}
+/**
+ * Collapse captured git or error output to ONE line (CR-303). Plan step 5 ends
+ * "every refusal is exit nonzero plus a single reason line", and git's
+ * own stderr is routinely five lines, so any interpolation of it must be
+ * flattened rather than trusted to be short. The M1-P6 harness reads
+ * these reason lines as evidence.
+ */
+export function singleLine(text) {
+    return text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line !== "")
+        .join("; ");
+}
+/**
+ * Run one step that may signal failure by THROWING, and fold a raised
+ * error into the same ok/reason shape every other step in spawn and
+ * teardown returns (F-1, F-2).
+ *
+ * This exists because the modules were written as a result type end to
+ * end while the Node fs calls underneath them are not: writeFileSync and
+ * mkdirSync raise. Every returned failure was handled correctly and every
+ * THROWN one walked straight past the handler, out of the command, and
+ * onto stderr as a stack trace, taking spawn's rollback and teardown's
+ * state update with it. Wrapping is therefore not defensive decoration
+ * for a state M1 never reaches: it is the difference between a rollback
+ * that runs and an orphaned worktree, and between a task marked closed
+ * and a meta.json that lies about a worktree that is already gone.
+ *
+ * It never swallows: the caller still gets a reason naming the step, and
+ * still decides whether to roll back, report a partial failure, or refuse.
+ */
+export function runStep(what, step) {
+    try {
+        return { ok: true, value: step() };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return { ok: false, reason: `${what} failed: ${detail}` };
+    }
+}
+/**
+ * runStep's shape for a step that returns a PROMISE (M4-P2 step 2).
+ *
+ * This is a PROMOTION, not a new function. It lived module-private in
+ * src/watcher.ts, where its own comment said "src/task.ts covers the sync
+ * one"; spawn's launch call site needs the same shape now that
+ * `ExecutorAdapter.launch` returns a promise, and T-005's one-mechanism
+ * rule makes copying it a third time the wrong answer. The promotion was
+ * measured before it was made: the two functions were run side by side over
+ * six `what`/thrown-error pairs covering an ordinary Error, an Error with an
+ * empty message, a thrown string, a thrown object with a custom toString, an
+ * Error subclass and a multi-line pair, and their reason strings were
+ * compared as buffers. All six were byte-identical, so no watcher message
+ * changes on any of those six. The capture is in the M4-P2 work history
+ * under `delivery/work-history/m4-p2.md`.
+ *
+ * WHY A SEPARATE FUNCTION RATHER THAN WIDENING runStep. `runStep` returns
+ * `{ok: true, value}` the instant its callback returns, and a callback that
+ * returns a promise returns one IMMEDIATELY. So `runStep` over an async
+ * step is not merely imprecise: its `ok: true` is a claim that the step
+ * SUCCEEDED when nothing has run yet, and a later rejection escapes the
+ * result type entirely as an unhandled rejection. That is the exact defect
+ * this phase's criterion 4 witness reddens against.
+ *
+ * It never swallows, on the same terms as the sync one: the caller gets a
+ * reason naming the step and still decides what to do about it.
+ */
+export async function runStepAsync(what, step) {
+    try {
+        return { ok: true, value: await step() };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return { ok: false, reason: `${what} failed: ${detail}` };
+    }
+}

package/dist/src/teardown.d.ts

@@ -0,0 +1,39 @@
+import type { Fleet } from "./fleet.ts";
+/** The commit-message prefix every salvaged commit carries (R-081a). */
+export declare const SALVAGE_PREFIX = "WIP-UNREVIEWED (do not treat as reviewed):";
+export type TeardownResult = {
+    ok: true;
+    value: {
+        taskId: string;
+        salvaged: boolean;
+    };
+} | {
+    ok: false;
+    reason: string;
+};
+export type Landedness = {
+    kind: "landed";
+    how: "ancestor" | "squash";
+} | {
+    kind: "unlanded";
+} | {
+    kind: "inconclusive";
+    detail: string;
+};
+/**
+ * Is branchRef landed on defaultRef? Both are resolved in contextDir,
+ * and defaultRef is always the just-fetched remote-tracking ref.
+ */
+export declare function landedness(contextDir: string, branchRef: string, defaultRef: string): Landedness;
+export interface TeardownOptions {
+    taskId: string;
+    salvage: boolean;
+    /**
+     * Proceed on a pool record RECONSTRUCTED from tasks/<id>/meta.json and
+     * git, when worktrees/<id>.pool.json did not survive a reclaim
+     * (M4-P19, M4-D-12). See the FROM-RECONSTRUCTED header below for what
+     * this flag does and, more importantly, what it does NOT do.
+     */
+    fromReconstructed: boolean;
+}
+export declare function teardownTask(fleet: Fleet, options: TeardownOptions): Promise<TeardownResult>;