@tiphys/kernel 0.0.0 → 0.2.0

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

@@ -0,0 +1,47 @@
+/** The remote a fleet home pushes to unless told otherwise. */
+export declare const DEFAULT_REMOTE = "origin";
+/**
+ * The commit subject, and it carries NO PATHS ON PURPOSE (criterion 6,
+ * CLAUDE.md binding convention 7: commit messages carry no AI model or tool
+ * names). A message composed from the paths it commits inherits whatever
+ * those paths are named, and a fleet's decision records and task directories
+ * are named after the things they decide, which routinely includes the
+ * harness or the model a decision is about. A count cannot carry a name.
+ */
+export declare function syncCommitMessage(count: number): string;
+/** One path git reports as changed, with its two status columns. */
+export interface ChangedPath {
+    path: string;
+    /** The index column (X). A space means unstaged; `?` means untracked. */
+    index: string;
+    /** The worktree column (Y). */
+    worktree: string;
+}
+/**
+ * Parse `git status --porcelain=v1 -z --untracked-files=all`.
+ *
+ * The NUL form is the only safe one: a path holding a space, a quote or a
+ * newline is printed raw here and is C-quoted in the newline form, so the
+ * newline form would need an unquoting pass that is its own defect surface.
+ * A rename or copy record carries TWO paths, the new one first and the
+ * original second, and both are returned: a rename out of the durable half
+ * into the ephemeral half must be visible as a change to both names.
+ */
+export declare function parsePorcelainStatus(payload: string): ChangedPath[];
+/** The `.gitignore` rule that makes one path ephemeral. */
+export interface IgnoreRule {
+    source: string;
+    line: string;
+    pattern: string;
+}
+/**
+ * Parse `git check-ignore --no-index -v -z --stdin`, whose output is a flat
+ * NUL-separated stream of four fields per MATCHING path: source, line
+ * number, pattern, pathname. Paths that match no rule are absent from the
+ * output entirely, which is what makes the result a set of the ephemeral
+ * ones rather than a verdict per input.
+ */
+export declare function parseCheckIgnore(payload: string): Map<string, IgnoreRule>;
+/** How an ignore rule is named in every line this command prints. */
+export declare function renderRule(rule: IgnoreRule): string;
+export declare function cmdSync(argv: string[]): number;

package/dist/src/commands/sync.js

@@ -0,0 +1,341 @@
+import { spawnSync } from "node:child_process";
+import { EX_USAGE } from "../cli.js";
+import { FLEET_SCRATCH_SUFFIXES, isFleetScratchPath, loadFleet } from "../fleet.js";
+import { MACHINE_IDENTITY_EMAIL, MACHINE_IDENTITY_NAME } from "./init.js";
+/**
+ * `tiphys sync`: commit the durable half of a fleet home and push it
+ * (kernel plan M4, M4-P18).
+ *
+ * WHAT THIS IS THE EXECUTABLE HALF OF. AGENTS.md's
+ * `fleet-state-commit-discipline` clause says durable state is committed and
+ * pushed at the moment it changes, and that the PUSH is the half that gets
+ * dropped. Until this phase the whole clause was discharged by an agent
+ * remembering to run git, which is the shape this repository has recorded
+ * three times: a rule that depends on remembering does not survive a busy
+ * session, and the answer is a mechanism.
+ *
+ * THE DURABLE SET IS DERIVED, NEVER LISTED HERE (criterion 2). A second list
+ * of ephemeral prefixes inside this file would be a second thing to keep in
+ * step with the fleet's own `.gitignore`, and the first divergence would be
+ * silent: a prefix added to the ignore set would keep being committed by a
+ * command that had never heard of it. So the question "is this path
+ * ephemeral" is answered by GIT, against the fleet `.gitignore` that
+ * `tiphys init` wrote, and this module holds no prefix list at all.
+ *
+ * `--no-index` IS THE LOAD-BEARING FLAG AND THE REASON IS THE HAZARD ITSELF.
+ * `git check-ignore` without it answers "would git ignore this path", and a
+ * TRACKED file is never ignored whatever `.gitignore` says, so it answers 1
+ * for exactly the file this command must exclude. The dangerous state is a
+ * lease or a scratch file that got tracked once (by a `git add -f`, or by
+ * being committed before the prefix was ignored): from then on every `git
+ * add -A` re-commits it, and a fleet's lease travels through the remote to
+ * environments that must rebuild it rather than restore it. With
+ * `--no-index` the answer is about the RULES, which is the question being
+ * asked. Measured contract in witness/captures/m4-p18-git-contracts.txt.
+ *
+ * WHY A STAGED EPHEMERAL PATH IS A REFUSAL AND NOT A SKIP (criterion 4).
+ * This command stages the durable paths it enumerated and then commits, and
+ * `git commit` commits the INDEX, not the pathspec it was handed. An
+ * operator who ran `git add -A` first has already put the lease in the
+ * index, so committing at all would commit it. Unstaging on the operator's
+ * behalf is a destructive act on work this command did not create, so the
+ * refusal names the path and the rule that makes it ephemeral, and commits
+ * nothing.
+ *
+ * SUBSTRATE-NEUTRAL (DR-0007) and C-2 clean: pure git and filesystem, no
+ * process probing, no pid, no signal.
+ */
+const USAGE = "usage: tiphys sync [--remote <name>]";
+/** The remote a fleet home pushes to unless told otherwise. */
+export const DEFAULT_REMOTE = "origin";
+/**
+ * The commit subject, and it carries NO PATHS ON PURPOSE (criterion 6,
+ * CLAUDE.md binding convention 7: commit messages carry no AI model or tool
+ * names). A message composed from the paths it commits inherits whatever
+ * those paths are named, and a fleet's decision records and task directories
+ * are named after the things they decide, which routinely includes the
+ * harness or the model a decision is about. A count cannot carry a name.
+ */
+export function syncCommitMessage(count) {
+    return `tiphys sync: ${String(count)} durable path(s)`;
+}
+function runGit(root, args, options = {}) {
+    const run = spawnSync("git", ["-C", root, ...args], {
+        encoding: "utf8",
+        input: options.input,
+        env: options.extraEnv === undefined
+            ? process.env
+            : { ...process.env, ...options.extraEnv },
+    });
+    return {
+        status: run.status,
+        stdout: run.stdout ?? "",
+        stderr: run.stderr ?? "",
+    };
+}
+/**
+ * Parse `git status --porcelain=v1 -z --untracked-files=all`.
+ *
+ * The NUL form is the only safe one: a path holding a space, a quote or a
+ * newline is printed raw here and is C-quoted in the newline form, so the
+ * newline form would need an unquoting pass that is its own defect surface.
+ * A rename or copy record carries TWO paths, the new one first and the
+ * original second, and both are returned: a rename out of the durable half
+ * into the ephemeral half must be visible as a change to both names.
+ */
+export function parsePorcelainStatus(payload) {
+    const fields = payload.split("\0");
+    const found = [];
+    for (let index = 0; index < fields.length; index += 1) {
+        const record = fields[index];
+        if (record === "") {
+            continue;
+        }
+        const x = record.slice(0, 1);
+        const y = record.slice(1, 2);
+        const path = record.slice(3);
+        found.push({ path, index: x, worktree: y });
+        if (x === "R" || x === "C" || y === "R" || y === "C") {
+            const original = fields[index + 1];
+            index += 1;
+            if (original !== undefined && original !== "") {
+                found.push({ path: original, index: x, worktree: y });
+            }
+        }
+    }
+    return found;
+}
+/**
+ * Parse `git check-ignore --no-index -v -z --stdin`, whose output is a flat
+ * NUL-separated stream of four fields per MATCHING path: source, line
+ * number, pattern, pathname. Paths that match no rule are absent from the
+ * output entirely, which is what makes the result a set of the ephemeral
+ * ones rather than a verdict per input.
+ */
+export function parseCheckIgnore(payload) {
+    const fields = payload.split("\0");
+    const found = new Map();
+    for (let index = 0; index + 3 < fields.length; index += 4) {
+        const source = fields[index];
+        const line = fields[index + 1];
+        const pattern = fields[index + 2];
+        const path = fields[index + 3];
+        if (path === "") {
+            continue;
+        }
+        found.set(path, { source, line, pattern });
+    }
+    return found;
+}
+/** How an ignore rule is named in every line this command prints. */
+export function renderRule(rule) {
+    return `${rule.source}:${rule.line} ${rule.pattern}`;
+}
+/**
+ * Ask git which of these paths the fleet `.gitignore` covers.
+ *
+ * THE THREE EXIT CODES ARE NOT TWO. 0 means at least one path matched, 1
+ * means none did, and 128 means git could not answer at all. Folding 128
+ * into "nothing is ephemeral" is how a command reports a clean sync while
+ * committing a lease, so it is a refusal here and the exit code is named.
+ */
+function classify(root, paths) {
+    if (paths.length === 0) {
+        return { ok: true, ephemeral: new Map() };
+    }
+    const run = runGit(root, ["check-ignore", "--no-index", "-v", "-z", "--stdin"], {
+        input: `${paths.join("\0")}\0`,
+    });
+    if (run.status === 0) {
+        return { ok: true, ephemeral: parseCheckIgnore(run.stdout) };
+    }
+    if (run.status === 1) {
+        return { ok: true, ephemeral: new Map() };
+    }
+    return {
+        ok: false,
+        reason: `git check-ignore exited ${String(run.status)} and could not say which paths are ephemeral, ` +
+            `so nothing was committed: ${run.stderr.split("\n")[0] ?? ""}`,
+    };
+}
+function parseArgs(argv) {
+    let remote = DEFAULT_REMOTE;
+    for (let index = 0; index < argv.length; index += 1) {
+        const flag = argv[index];
+        if (flag !== "--remote") {
+            return { usageError: `unknown option ${flag}` };
+        }
+        const value = argv[index + 1];
+        if (value === undefined) {
+            return { usageError: "--remote requires a value" };
+        }
+        remote = value;
+        index += 1;
+    }
+    return { remote };
+}
+export function cmdSync(argv) {
+    const parsed = parseArgs(argv);
+    if (parsed.remote === undefined) {
+        process.stderr.write(`tiphys sync: ${parsed.usageError ?? "usage error"}\n${USAGE}\n`);
+        return EX_USAGE;
+    }
+    const remote = parsed.remote;
+    const fleet = loadFleet(process.cwd());
+    /* THE REMOTE IS ESTABLISHED BEFORE ANYTHING IS COMMITTED. The discipline
+       is commit AND push; a sync that commits and then discovers there is
+       nowhere to push has done the half that gets dropped and reported the
+       half that does not. */
+    const remotes = runGit(fleet.root, ["remote"]);
+    if (remotes.status !== 0) {
+        process.stderr.write(`tiphys sync: git remote failed in ${fleet.root}: ${remotes.stderr.split("\n")[0] ?? ""}\n`);
+        return 1;
+    }
+    const known = remotes.stdout.split("\n").map((line) => line.trim());
+    if (!known.includes(remote)) {
+        process.stderr.write(`tiphys sync: ${fleet.root} has no remote named ${remote}, so durable state cannot be pushed; ` +
+            `add one with git remote add ${remote} <url>, nothing was committed\n`);
+        return 1;
+    }
+    const status = runGit(fleet.root, [
+        "status",
+        "--porcelain=v1",
+        "-z",
+        "--untracked-files=all",
+    ]);
+    if (status.status !== 0) {
+        process.stderr.write(`tiphys sync: git status failed in ${fleet.root}: ${status.stderr.split("\n")[0] ?? ""}\n`);
+        return 1;
+    }
+    const changed = parsePorcelainStatus(status.stdout);
+    const classified = classify(fleet.root, [...new Set(changed.map((entry) => entry.path))]);
+    if (!classified.ok) {
+        process.stderr.write(`tiphys sync: ${classified.reason}\n`);
+        return 1;
+    }
+    const ephemeral = classified.ephemeral;
+    /* THE SCRATCH REFUSAL RUNS BEFORE THE STAGED-EPHEMERAL ONE, and the order
+       is stated because it is a choice. A fleet carrying both a stray scratch
+       file and a staged ephemeral path reports the scratch file and stops; both
+       arms refuse and commit nothing, so no path is committed either way, and
+       the operator sees one refusal at a time rather than two. It also keeps the
+       staged-ephemeral block the last `return 1` before `const durable`, which
+       is where witness/sync-staged-lease-refused.json aims its second member. */
+    /* THE DENYLIST IS THREE DIRECTORY PREFIXES AND THE QUESTION IT ANSWERS IS
+       NARROWER THAN THE ONE THIS COMMAND ASKS.
+  
+       `git check-ignore --no-index` answers "is this path covered by a rule
+       someone wrote down". This command reads that as "is this path meant to
+       be committed". Those are the same question only for paths someone
+       thought to declare, and the fleet ignore set (src/fleet.ts:29) declares
+       three directory prefixes and nothing else. Anything the kernel writes
+       outside them is DURABLE BY DEFAULT.
+  
+       Two paths the kernel itself creates land there, and neither is fleet
+       content: the atomic-rename scratch file src/status.ts:142 writes beside
+       its TRACKED target, and the one src/cutover.ts:278 writes at the fleet
+       ROOT under a random name. Both are write-then-rename scratch, both are
+       left behind by the failure this project's own tuition calls ordinary
+       rather than exceptional (a process killed mid-write), and once either is
+       committed it is tracked forever by ordinary git semantics.
+  
+       A REFUSAL AND NOT A SILENT EXCLUSION, for the reason criterion 4 already
+       gives about a staged ephemeral path: this command must not quietly drop
+       a path an operator can see in `git status`. The cost is stated rather
+       than discovered: a `tiphys sync` that races a live `tiphys status emit`
+       now fails with a named path instead of committing a temp file, and the
+       operator re-runs.
+  
+       THE FLEET IGNORE SET IS NOT WIDENED TO DO THIS, and this module still
+       holds no copy of it. That constant also drives `EPHEMERAL_DIRS`,
+       `DURABLE_DIRS` and the `.gitignore` `tiphys init` writes, so a glob
+       added there would become a directory name `tiphys resume` tried to
+       rebuild. Nothing stops being synced; this is a second, separately named
+       rule about SUFFIXES, declared once in src/fleet.ts and read from there,
+       exactly as the ignore question is asked of git rather than answered
+       here. */
+    const scratch = [...new Set(changed.map((entry) => entry.path))]
+        .filter((path) => !ephemeral.has(path))
+        .map((path) => ({ path, suffix: isFleetScratchPath(path) }))
+        .filter((candidate) => candidate.suffix !== undefined)
+        .sort((a, b) => a.path.localeCompare(b.path));
+    if (scratch.length > 0) {
+        for (const candidate of scratch) {
+            process.stderr.write(`tiphys sync: ${candidate.path} ends in ${candidate.suffix}, which is a ` +
+                `write-then-rename scratch suffix this kernel uses (${FLEET_SCRATCH_SUFFIXES.join(", ")}), ` +
+                `and no fleet .gitignore rule covers it, so committing it would track it forever; ` +
+                `remove it and re-run, nothing was committed\n`);
+        }
+        return 1;
+    }
+    /* CRITERION 4, and the order matters: every staged ephemeral path is
+       reported before anything is staged or committed, so the refusal is a
+       statement about the tree as the operator left it. */
+    const stagedEphemeral = changed.filter((entry) => ephemeral.has(entry.path) && entry.index !== " " && entry.index !== "?");
+    if (stagedEphemeral.length > 0) {
+        for (const entry of stagedEphemeral) {
+            const rule = ephemeral.get(entry.path);
+            process.stderr.write(`tiphys sync: ${entry.path} is staged and is ephemeral by ${renderRule(rule)}; ` +
+                `unstage it with git restore --staged -- ${entry.path} and re-run, nothing was committed\n`);
+        }
+        return 1;
+    }
+    const durable = [
+        ...new Set(changed
+            .map((entry) => entry.path)
+            .filter((path) => !ephemeral.has(path))),
+    ].sort();
+    const excluded = [
+        ...new Set(changed.map((entry) => entry.path).filter((path) => ephemeral.has(path))),
+    ].sort();
+    /* The excluded paths are PRINTED WITH THE RULE THAT EXCLUDED THEM. A
+       command that silently drops paths is indistinguishable from one that
+       never saw them, and the rule reference is what makes the derivation
+       observable rather than asserted. */
+    for (const path of excluded) {
+        process.stdout.write(`EXCLUDED ${path} ${renderRule(ephemeral.get(path))}\n`);
+    }
+    if (durable.length === 0) {
+        process.stdout.write("NOTHING TO COMMIT\n");
+    }
+    else {
+        const added = runGit(fleet.root, ["add", "--", ...durable]);
+        if (added.status !== 0) {
+            process.stderr.write(`tiphys sync: git add failed in ${fleet.root}: ${added.stderr.split("\n")[0] ?? ""}\n`);
+            return 1;
+        }
+        const committed = runGit(fleet.root, ["commit", "-m", syncCommitMessage(durable.length)], {
+            /* The documented deterministic machine identity, command-scoped,
+               exactly as the bootstrap commit does it: CI runners have no git
+               identity and this must never touch user or global config
+               (CLAUDE.md standing warning 5). */
+            extraEnv: {
+                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) {
+            process.stderr.write(`tiphys sync: git commit failed in ${fleet.root}: ${committed.stderr.split("\n")[0] ?? ""}\n`);
+            return 1;
+        }
+        for (const path of durable) {
+            process.stdout.write(`COMMITTED ${path}\n`);
+        }
+    }
+    /* THE PUSH ARM IS NOT OPTIONAL AND ITS FAILURE IS NOT A WARNING. The
+       failure carries GIT'S OWN first stderr line rather than a message
+       composed here: a retry signature or a diagnosis derived from a
+       hand-written example is the failure T-003 and CLAUDE.md standing warning
+       10 both record. */
+    const pushed = runGit(fleet.root, ["push", remote, "HEAD"]);
+    if (pushed.status !== 0) {
+        const first = pushed.stderr.split("\n")[0] ?? "";
+        process.stderr.write(`tiphys sync: git push to ${remote} exited ${String(pushed.status)}, ` +
+            `so the durable state is committed locally and NOT pushed: ${first}\n`);
+        return 1;
+    }
+    process.stdout.write(`PUSHED ${remote}\n`);
+    return 0;
+}

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

@@ -0,0 +1 @@
+export declare function cmdTeardown(args: string[]): Promise<number>;

package/dist/src/commands/teardown.js

@@ -0,0 +1,87 @@
+import { EX_USAGE } from "../cli.js";
+import { loadFleet } from "../fleet.js";
+import { warnIfWatcherStale } from "../liveness.js";
+import { singleLine } from "../task.js";
+import { teardownTask } from "../teardown.js";
+/**
+ * tiphys teardown --task <id> [--salvage] (kernel plan v1, M1-P4
+ * step 5). Runs in a fleet home (cwd).
+ *
+ * Every refusal is exit nonzero plus a SINGLE reason line naming the
+ * blocking condition. A failure of the destroy itself is passed through
+ * with the pool's own wording, which distinguishes a refusal (a true
+ * no-op) from a partial failure (the worktree is already gone and the
+ * survivors are enumerated); this command adds no framing of its own to
+ * either, because the two must never be described alike.
+ */
+const USAGE = "usage: tiphys teardown --task <id> [--salvage] [--from-reconstructed]";
+function usageError(message) {
+    if (message !== undefined) {
+        process.stderr.write(`tiphys teardown: ${message}\n`);
+    }
+    process.stderr.write(`${USAGE}\n`);
+    return EX_USAGE;
+}
+function parseFlags(args) {
+    const parsed = {
+        task: undefined,
+        salvage: false,
+        fromReconstructed: false,
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const flag = args[i];
+        const value = args[i + 1];
+        if (flag === "--task" && value !== undefined) {
+            parsed.task = value;
+            i += 1;
+        }
+        else if (flag === "--salvage") {
+            parsed.salvage = true;
+        }
+        else if (flag === "--from-reconstructed") {
+            parsed.fromReconstructed = true;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return parsed;
+}
+export async function cmdTeardown(args) {
+    const flags = parseFlags(args);
+    if (flags === undefined) {
+        return usageError();
+    }
+    if (flags.task === undefined) {
+        return usageError("teardown requires --task <id>");
+    }
+    let fleet;
+    try {
+        fleet = loadFleet(process.cwd());
+    }
+    catch (error) {
+        process.stderr.write(`tiphys teardown: ${singleLine(error.message)}\n`);
+        return 1;
+    }
+    // Liveness guard (M1-P5 step 2): one stderr warning line when work is
+    // in flight and supervision has gone quiet, and then the teardown
+    // proceeds exactly as it would have. It never blocks and never changes
+    // an exit code (criteria 10 and 11).
+    warnIfWatcherStale(fleet);
+    const result = await teardownTask(fleet, {
+        taskId: flags.task,
+        salvage: flags.salvage,
+        fromReconstructed: flags.fromReconstructed,
+    });
+    if (!result.ok) {
+        // Plan step 5: "every refusal is exit nonzero plus a single reason
+        // line". Enforced here structurally (CR-303) rather than trusted of
+        // every reason string, because reasons interpolate git output and a
+        // raised error message, neither of which is guaranteed to be short.
+        process.stderr.write(`tiphys teardown: ${singleLine(result.reason)}\n`);
+        return 1;
+    }
+    const suffix = result.value.salvaged ? " (leavings salvaged and pushed)" : "";
+    process.stdout.write(`torn down ${result.value.taskId}${suffix}\n`);
+    return 0;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * `tiphys tuition add|list|index` (kernel plan M3, M3-P8 steps 2 and 6;
+ * R-091).
+ *
+ *   add --file <entry> [--into <dir>]   validate an entry and file it
+ *   list [--kernel-relevant] [--dir <d>] one line per entry
+ *   index [--out <f>] [--check] [--dir <d>]  project the mechanism index
+ *
+ * PROMOTION IS NOT A SUBCOMMAND, and that is a decision rather than an
+ * omission. R-091 says kernel-relevant tuition ships upstream as a kernel pull
+ * request; the kernel never opens pull requests, so promotion is a documented
+ * orchestrator procedure (M3-P9's `AGENTS.md`) and building a promoter that M3
+ * would use once is the M1-P3 mistake.
+ *
+ * `add` WRITES WITH AN EXCLUSIVE CREATE, so a second entry claiming an id that
+ * already exists fails loudly and names the file rather than overwriting a
+ * record. A `T-nnn` id is never renumbered and never reused after retirement,
+ * which makes an overwrite a silent loss of exactly the artifact this feed
+ * exists to keep.
+ */
+export declare function cmdTuition(argv: string[]): number;