@tiphys/kernel 0.0.0 → 0.1.0

package/dist/src/teardown.d.ts

@@ -0,0 +1,32 @@
+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;
+}
+export declare function teardownTask(fleet: Fleet, options: TeardownOptions): Promise<TeardownResult>;

package/dist/src/teardown.js

@@ -0,0 +1,314 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { MACHINE_IDENTITY_EMAIL, MACHINE_IDENTITY_NAME } from "./commands/init.js";
+import { poolDestroy, readPoolRecord, worktreePath } from "./pool.js";
+import { checkHoldership, metaPath, readTaskMeta, reportPath, runStep, setTaskStatus, singleLine, } from "./task.js";
+/**
+ * Local git runner. It is deliberately not the pool's: src/pool.ts is
+ * explicitly out of this phase's edit scope, and teardown needs no
+ * contention retry, because nothing in M1 runs teardown concurrently
+ * with anything else (parallelism is off until M5). The locale is pinned
+ * for the same reason the pool pins it: reproducible output.
+ */
+function runGit(cwd, args, extraEnv) {
+    const result = spawnSync("git", ["-C", cwd, ...args], {
+        encoding: "utf8",
+        env: { ...process.env, LC_ALL: "C", LANG: "C", ...extraEnv },
+    });
+    if (result.error !== undefined) {
+        return { status: null, stdout: "", stderr: String(result.error) };
+    }
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+}
+/** The commit-message prefix every salvaged commit carries (R-081a). */
+export const SALVAGE_PREFIX = "WIP-UNREVIEWED (do not treat as reviewed):";
+/**
+ * Is branchRef landed on defaultRef? Both are resolved in contextDir,
+ * and defaultRef is always the just-fetched remote-tracking ref.
+ */
+export function landedness(contextDir, branchRef, defaultRef) {
+    const ancestor = runGit(contextDir, [
+        "merge-base",
+        "--is-ancestor",
+        branchRef,
+        defaultRef,
+    ]);
+    if (ancestor.status === 0) {
+        return { kind: "landed", how: "ancestor" };
+    }
+    if (ancestor.status !== 1) {
+        return {
+            kind: "inconclusive",
+            detail: `git merge-base --is-ancestor exited ${String(ancestor.status)}: ${singleLine(ancestor.stderr)}`,
+        };
+    }
+    const defaultTree = runGit(contextDir, ["rev-parse", "--verify", `${defaultRef}^{tree}`]);
+    if (defaultTree.status !== 0) {
+        return {
+            kind: "inconclusive",
+            detail: `cannot resolve the tree of ${defaultRef}: ${singleLine(defaultTree.stderr)}`,
+        };
+    }
+    const merged = runGit(contextDir, ["merge-tree", "--write-tree", defaultRef, branchRef]);
+    if (merged.status === 1) {
+        // Conflicts: merging is not a no-op, so the branch is not landed.
+        return { kind: "unlanded" };
+    }
+    if (merged.status !== 0) {
+        return {
+            kind: "inconclusive",
+            detail: `git merge-tree --write-tree exited ${String(merged.status)}: ${singleLine(merged.stderr)}`,
+        };
+    }
+    const mergedTree = merged.stdout.split("\n")[0]?.trim() ?? "";
+    if (mergedTree === "") {
+        return {
+            kind: "inconclusive",
+            detail: "git merge-tree --write-tree produced no tree id",
+        };
+    }
+    return mergedTree === defaultTree.stdout.trim()
+        ? { kind: "landed", how: "squash" }
+        : { kind: "unlanded" };
+}
+/**
+ * Resolve everything teardown needs, and perform the mandatory fetch.
+ * Read-only with respect to the task: the fetch updates only the
+ * project's remote-tracking ref.
+ */
+function resolveContext(fleet, taskId) {
+    const meta = readTaskMeta(fleet, taskId);
+    if (meta === undefined) {
+        return {
+            ok: false,
+            reason: `no readable task meta for task id ${taskId}; teardown needs tasks/${taskId}/meta.json`,
+        };
+    }
+    const record = readPoolRecord(fleet, taskId);
+    if (record === undefined) {
+        return {
+            ok: false,
+            reason: `no readable pool record for task id ${taskId}; teardown needs it for the ` +
+                `project remote and default branch, and refuses rather than guessing them`,
+        };
+    }
+    const worktree = worktreePath(fleet, taskId);
+    const defaultRef = `refs/remotes/${record.remote}/${record.branch}`;
+    // PR-001: fetch first, always, and judge landed-ness only against this.
+    const fetched = runGit(record.project, [
+        "fetch",
+        record.remote,
+        `+refs/heads/${record.branch}:${defaultRef}`,
+    ]);
+    if (fetched.status !== 0) {
+        return {
+            ok: false,
+            reason: `fetch of ${record.remote}/${record.branch} failed, so landed-ness cannot ` +
+                `be judged against fresh remote state: ${singleLine(fetched.stderr)}`,
+        };
+    }
+    return { ok: true, value: { meta, record, worktree, defaultRef } };
+}
+/** Uncommitted changes or untracked files in the task worktree. */
+function worktreeDirty(worktree) {
+    const status = runGit(worktree, ["status", "--porcelain"]);
+    if (status.status !== 0) {
+        return {
+            ok: false,
+            reason: `cannot verify worktree cleanliness at ${worktree}: ${singleLine(status.stderr)}`,
+        };
+    }
+    return { ok: true, dirty: status.stdout.trim() !== "" };
+}
+/** Commit the leavings under the WIP label and push the branch (R-081a). */
+function salvageLeavings(context) {
+    const { worktree, record } = context;
+    const added = runGit(worktree, ["add", "-A"]);
+    if (added.status !== 0) {
+        return { ok: false, reason: `salvage failed at git add: ${singleLine(added.stderr)}` };
+    }
+    const message = `${SALVAGE_PREFIX} leavings salvaged by tiphys teardown for task ${context.meta.id}`;
+    // CI runners have no git identity, and the fleet never reads or writes
+    // user or global git configuration (EXT-F-02 option B): the machine
+    // identity is set command-scoped, exactly as init's bootstrap commit
+    // does it.
+    const committed = runGit(worktree, ["commit", "-m", message], {
+        GIT_AUTHOR_NAME: MACHINE_IDENTITY_NAME,
+        GIT_AUTHOR_EMAIL: MACHINE_IDENTITY_EMAIL,
+        GIT_COMMITTER_NAME: MACHINE_IDENTITY_NAME,
+        GIT_COMMITTER_EMAIL: MACHINE_IDENTITY_EMAIL,
+    });
+    if (committed.status !== 0) {
+        return {
+            ok: false,
+            reason: `salvage failed at git commit: ${singleLine(committed.stderr) || singleLine(committed.stdout)}`,
+        };
+    }
+    const pushed = runGit(record.project, [
+        "push",
+        record.remote,
+        `refs/heads/${record.branchName}:refs/heads/${record.branchName}`,
+    ]);
+    if (pushed.status !== 0) {
+        return {
+            ok: false,
+            reason: `salvage committed the leavings as "${SALVAGE_PREFIX} ..." but the push of ` +
+                `${record.branchName} failed: ${singleLine(pushed.stderr)}; the commit is local only`,
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Remove the worktree and close the task. Never called before every
+ * refusal rule has passed.
+ */
+async function finish(fleet, context, options) {
+    const destroyed = await poolDestroy(fleet, {
+        taskId: context.meta.id,
+        discard: options.discard,
+        deleteBranchForce: options.deleteBranchForce,
+    });
+    if (!destroyed.ok) {
+        // The destroy's own reason distinguishes a stage-2 refusal (a true
+        // no-op) from a stage-3 partial failure (worktree already removed,
+        // survivors enumerated). It is passed through verbatim, and the only
+        // thing added is what this layer knows for certain.
+        return {
+            ok: false,
+            reason: `pool destroy did not complete: ${destroyed.reason}; task ${context.meta.id} stays open`,
+        };
+    }
+    // F-1. The worktree is GONE by this point, so a raised write here is
+    // not a refusal and must never crash the command: an uncaught throw
+    // left meta.json reading "open" beside a worktree that no longer
+    // exists, which is the single state authority (C-1) telling a later
+    // reader, and the M1-P5 watcher, something false. It is the same
+    // partial-failure shape M1-P3 defined for destroy, reported in the
+    // same vocabulary, with the manual remedy named.
+    const closed = runStep(`marking task ${context.meta.id} closed`, () => {
+        setTaskStatus(fleet, context.meta, "closed");
+    });
+    if (!closed.ok) {
+        const removed = destroyed.value.deletedBranch === undefined
+            ? `worktree ${context.worktree} HAS BEEN REMOVED`
+            : `worktree ${context.worktree} HAS BEEN REMOVED and branch ` +
+                `${destroyed.value.deletedBranch} was deleted (it was ` +
+                `${destroyed.value.deletedSha ?? "unknown"})`;
+        return {
+            ok: false,
+            reason: `partial teardown of task id ${context.meta.id}: ${removed}, but ` +
+                `${metaPath(fleet, context.meta.id)} could not be marked closed ` +
+                `(${closed.reason}); the task record still reads status open although its ` +
+                `worktree is gone, so repair that file and set "status": "closed" by hand`,
+        };
+    }
+    return { ok: true, value: { taskId: context.meta.id, salvaged: options.salvaged } };
+}
+export async function teardownTask(fleet, options) {
+    const holdership = checkHoldership(fleet);
+    if (!holdership.ok) {
+        return { ok: false, reason: holdership.reason };
+    }
+    const resolved = resolveContext(fleet, options.taskId);
+    if (!resolved.ok) {
+        return resolved;
+    }
+    const context = resolved.value;
+    const { meta, record, worktree } = context;
+    if (meta.shape === "scout") {
+        // (a) A scout is judged by its report, never by its scratch tree.
+        if (!existsSync(reportPath(fleet, options.taskId))) {
+            return {
+                ok: false,
+                reason: `scout task ${options.taskId} has no report: ${reportPath(fleet, options.taskId)} ` +
+                    `is absent, and a scout is torn down only once it has reported`,
+            };
+        }
+        // Scout worktrees are scratch and scouts never push (PR-010), so the
+        // dirty tree is discarded. --delete-branch-force is deliberately NOT
+        // passed: --discard's plan-defined meaning is the dirty-tree
+        // override only, and a scout that committed to its scratch branch is
+        // refused rather than having those commits deleted silently, which is
+        // exactly the M1-P3 V-1 defect.
+        //
+        // CR-304: teardown answers that question ITSELF, before calling
+        // destroy, because the pool's own refusal advises passing
+        // --delete-branch-force, a flag teardown does not accept, so the
+        // operator was told to do something impossible through the command
+        // that printed it and the task could never reach closed. This
+        // refusal is a true no-op and names a route that works; the pool's
+        // gate stays behind it as the enforcer.
+        const tip = runGit(record.project, [
+            "rev-parse",
+            "--verify",
+            "--quiet",
+            `refs/heads/${record.branchName}^{commit}`,
+        ]);
+        if (tip.status === 0 && tip.stdout.trim() !== record.baseSha) {
+            return {
+                ok: false,
+                reason: `scout task ${options.taskId} has commits on its scratch branch ` +
+                    `${record.branchName} (tip ${tip.stdout.trim()}, base ${record.baseSha}) and ` +
+                    `teardown never deletes committed work: copy or push them somewhere ` +
+                    `durable, then release the branch with "git -C ${record.project} update-ref ` +
+                    `refs/heads/${record.branchName} ${record.baseSha}" and re-run teardown`,
+            };
+        }
+        return finish(fleet, context, {
+            discard: true,
+            deleteBranchForce: false,
+            salvaged: false,
+        });
+    }
+    // (b) ship.
+    const dirty = worktreeDirty(worktree);
+    if (!dirty.ok) {
+        return { ok: false, reason: dirty.reason };
+    }
+    if (dirty.dirty && !options.salvage) {
+        return {
+            ok: false,
+            reason: `worktree ${worktree} has uncommitted changes or untracked files; commit ` +
+                `or land them first, or pass --salvage to commit them as ` +
+                `"${SALVAGE_PREFIX} ..." and push`,
+        };
+    }
+    const branchRef = `refs/heads/${record.branchName}`;
+    const landed = landedness(record.project, branchRef, context.defaultRef);
+    if (landed.kind === "inconclusive") {
+        return {
+            ok: false,
+            reason: `cannot determine whether ${record.branchName} is landed on ` +
+                `${record.remote}/${record.branch} (${landed.detail}); refusing`,
+        };
+    }
+    if (landed.kind === "unlanded") {
+        return {
+            ok: false,
+            reason: `branch ${record.branchName} is not landed on ${record.remote}/${record.branch}; ` +
+                `land it before tearing the task down` +
+                (options.salvage ? " (--salvage rescues leavings, it never lands work)" : ""),
+        };
+    }
+    let salvaged = false;
+    if (dirty.dirty) {
+        const rescue = salvageLeavings(context);
+        if (!rescue.ok) {
+            return rescue;
+        }
+        salvaged = true;
+    }
+    // The landed judgement is what authorizes deleting the task branch
+    // (V-1's explicit flag, which src/pool.ts documents as coming from
+    // exactly here). After a salvage the branch carries the WIP commit,
+    // which is on the remote, so the local branch is safe to remove.
+    return finish(fleet, context, {
+        discard: false,
+        deleteBranchForce: true,
+        salvaged,
+    });
+}

package/dist/src/tuition.d.ts

@@ -0,0 +1,159 @@
+/**
+ * THE TUITION FEED AND THE MECHANISM INDEX (kernel plan M3, M3-P8; R-091).
+ *
+ * A tuition entry records one failure mode a delivery paid for. The MECHANISM
+ * INDEX is a PROJECTION of the `mechanisms[]` field of every entry in the
+ * feed, keyed by mechanism, and it is generated rather than authored. T-005 is
+ * why both halves exist and why they are one artifact rather than two: a rule
+ * M1-P3 paid for did not reach M1-P5, which reimplemented the same claim-file
+ * mechanism silently and produced the most severe defect found in M1, and a
+ * second hand-maintained copy of a rule is the state that produced it.
+ *
+ * THE TWO LAYERS ARE STRUCTURALLY DISTINCT, which is the plan's compaction
+ * model (step 2c). The index is the READ layer: dense, consulted at every
+ * dispatch under the `mechanism-lookup` obligation. The entries are the
+ * ARCHIVE layer: longer, read when a rule is disputed. `tuition index --check`
+ * is what keeps the first honest about the second.
+ *
+ * PATHS THIS MODULE READS ARE NOT ITS OWN (D-M3-27, the mechanism index's own
+ * row "Reading a path whose type is not established"). Every read goes through
+ * `readOperatorPath`, so a named pipe at an entry path is refused with the
+ * observed entry type instead of blocking the command forever.
+ */
+/** The generated index, relative to a tuition directory. */
+export declare const MECHANISM_INDEX_FILE = "mechanism-index.yaml";
+/** One mechanism as a tuition entry declares it. */
+export interface MechanismDeclaration {
+    mechanism: string;
+    rule: string;
+    siblings?: string[];
+    "machine-readable-form"?: {
+        path: string;
+        key: string;
+    };
+    evidence: string[];
+}
+/** One tuition entry, after schema validation. */
+export interface TuitionEntry {
+    kind: "tuition";
+    version: number;
+    id: string;
+    project: string;
+    date: string;
+    stage: string;
+    "kernel-relevant": boolean;
+    "what-happened": string;
+    lesson: string[];
+    mechanisms?: MechanismDeclaration[];
+    "structural-consequence"?: {
+        target: string;
+        status: "proposed" | "applied" | "ticketed";
+        change: string;
+        record?: string;
+    }[];
+    evidence: string[];
+}
+/** One row of the generated index, plus the entry it was projected from. */
+export interface IndexRow {
+    key: string;
+    name: string;
+    rule: string;
+    siblings?: string[];
+    "machine-readable-form"?: {
+        path: string;
+        key: string;
+    };
+    evidence: string[];
+    /** The tuition id this row came from. Not part of the rendered document. */
+    source: string;
+}
+/**
+ * THE KEY IS DERIVED FROM THE NAME, NEVER INVENTED: lowercase, every run of
+ * characters outside [a-z0-9] collapsed to one hyphen, ends trimmed. The same
+ * derivation `schemas/mechanism-index.schema.json` documents and M3-P6's
+ * registered test applies, stated once in code so the generator and the check
+ * cannot disagree about it.
+ */
+export declare function mechanismKey(name: string): string;
+export type EntryFileListing = {
+    ok: true;
+    paths: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Every tuition ENTRY file in a directory, sorted by name.
+ *
+ * The generated index lives in the same directory and is EXCLUDED BY NAME: it
+ * is the projection's output, and a projection that reads its own output is a
+ * loop rather than a check. Anything that is not a `.yaml` file is ignored, so
+ * a README beside the feed is not an entry.
+ */
+export declare function listEntryFiles(directory: string): EntryFileListing;
+export type EntryLoad = {
+    ok: true;
+    entry: TuitionEntry;
+    body: string;
+} | {
+    ok: false;
+    reason: string;
+    diagnostics: string[];
+};
+/**
+ * Read, decode and schema-validate one tuition entry.
+ *
+ * THE RAW BYTES COME BACK WITH THE ENTRY, and that is not a convenience. An
+ * earlier version had `tuition add` call this and then read the same path a
+ * second time for the bytes to write. Two reads meant two independent
+ * refusals of a non-regular path, and a refusal that another refusal shadows
+ * cannot be witnessed: mutating either left the other rejecting the same
+ * input, which is exactly the shape T-018 records. One read, one
+ * classification, one guard.
+ */
+export declare function loadEntry(path: string): EntryLoad;
+export type Projection = {
+    ok: true;
+    rows: IndexRow[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Project the mechanism index out of a set of entries, sorted by key.
+ *
+ * A KEY CLAIMED BY TWO ENTRIES IS AN ERROR NAMING BOTH, never a silent
+ * first-wins. Two entries stating the same mechanism differently is exactly
+ * the divergence this document exists to prevent, and the projection cannot
+ * decide which of the two rules the project actually learned. The resolution
+ * is an editorial one: merge the two entries' rules by hand into whichever one
+ * owns the mechanism.
+ */
+export declare function projectIndex(entries: readonly TuitionEntry[]): Projection;
+/**
+ * Emit a YAML scalar, quoting only when a plain one would not round trip.
+ *
+ * THE CONDITION IS THE POINT: this generator's output is re-read by
+ * `--check`, so a scalar that YAML would decode as something other than the
+ * string handed in makes the projection disagree with itself. The reserved
+ * leading indicators, an embedded `: ` or ` #`, and a trailing colon are the
+ * cases; everything else is emitted plain, which is what keeps the document
+ * readable.
+ */
+export declare function yamlScalar(value: string): string;
+/** Render the index document. The bytes are what `--check` compares. */
+export declare function renderIndex(rows: readonly IndexRow[]): string;
+/**
+ * Compare a committed index document against a fresh projection.
+ *
+ * NAMES THE MECHANISM AND THE ENTRY IT CAME FROM, which is the criterion's
+ * letter (4): a reader of a red `--check` must be able to go straight to the
+ * file that changed. Both directions are reported, because a row DELETED from
+ * the feed and a row ADDED to it are different faults with the same symptom.
+ *
+ * The field comparison is over the DECODED values rather than the bytes, so a
+ * rewrap of a folded scalar is not reported as a rule change; a byte
+ * comparison is done by the caller afterwards and reported as formatting,
+ * which keeps "the rule changed" and "the file was hand-edited" apart.
+ */
+export declare function driftLines(committed: unknown, rows: readonly IndexRow[]): string[];