@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/commands/lock.js

@@ -0,0 +1,340 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { setTimeout as sleep } from "node:timers/promises";
+import { EX_USAGE } from "../cli.js";
+import { loadFleet, refuseOpenPathForWrite } from "../fleet.js";
+import { acquireLease, leaseStatus, observeLease, releaseLease, renewLease, } from "../lock.js";
+/**
+ * tiphys lock <acquire [--take-over] [--duration <seconds>] | renew
+ * --holder <id> [--duration <seconds>] | release --holder <id> | status>
+ * (kernel plan v1, M1-P3 step 2). Runs in a fleet home (cwd). The holder
+ * identity for renew and release is the opaque holderId that acquire
+ * printed; it outlives any one command invocation (FM-022) and is never
+ * derived from the running program (plan constraint C-2).
+ */
+const USAGE = "usage: tiphys lock <acquire [--take-over] [--duration <seconds>] | " +
+    "renew --holder <id> [--duration <seconds>] | " +
+    "release --holder <id> | status>";
+/**
+ * Deterministic race-witness hold point (the plan's test determinism
+ * rule: scripted interleaves over sleep-based timing). When
+ * TIPHYS_LOCK_TEST_HOLD names a barrier path, the mutating subcommands
+ * observe the lease and freeze their decision clock first, write
+ * <barrier>.observed as a ready marker, then wait for the barrier file
+ * to appear before deciding and applying through the one mutation
+ * primitive. A test can thereby interleave two real CLI invocations at
+ * the exact compare-and-swap point. Inert unless the variable is set.
+ *
+ * The seam is LOUD about not holding (D-3). It previously had two exits
+ * from its wait and only one of them meant "held": on the other the
+ * command walked into the mutation carrying a stale observation and
+ * told nobody, so a witness could score a compare-and-swap it never
+ * staged and still pass. Both exits are now closed with a throw, the
+ * bound is monotonic (process.hrtime.bigint, not Date.now, because a
+ * realtime bound mixed with monotonic test durations is precisely what
+ * made "it failed fast" look like proof the bound was not reached), and
+ * the reason the wait ended is written to <barrier>.released so the
+ * test can assert the interleave actually happened. This is a test
+ * integrity fix; it is NOT a fix for the unattributed U-2 flake, whose
+ * trigger remains unexplained.
+ */
+const HOLD_WAIT_LIMIT_MS = 30_000;
+async function maybeHoldForTest(lockPath) {
+    const barrier = process.env.TIPHYS_LOCK_TEST_HOLD;
+    if (barrier === undefined || barrier === "") {
+        return undefined;
+    }
+    if (existsSync(barrier)) {
+        throw new Error(`lock test hold point: barrier ${barrier} already existed before the ` +
+            `hold; this interleave was never staged and the run is not evidence`);
+    }
+    const observed = observeLease(lockPath);
+    const nowMs = Date.now();
+    /* THE MARKER PATHS ARE DERIVED FROM A CALLER-SUPPLIED PATH, so their entry
+       type is established before either is opened for writing. A named pipe at
+       `<barrier>.observed` blocked this seam forever with zero output, which is
+       the same class this round closed in the lease and brief readers; the seam
+       is inert unless the variable is set, which changes how it is REACHED and
+       not what it does once reached. */
+    const observedRefusal = refuseOpenPathForWrite(`${barrier}.observed`);
+    if (observedRefusal !== undefined) {
+        throw new Error(`lock test hold point: ${observedRefusal}`);
+    }
+    writeFileSync(`${barrier}.observed`, "");
+    const startNs = process.hrtime.bigint();
+    const limitNs = BigInt(HOLD_WAIT_LIMIT_MS) * 1000000n;
+    let held = false;
+    for (;;) {
+        if (existsSync(barrier)) {
+            held = true;
+            break;
+        }
+        if (process.hrtime.bigint() - startNs >= limitNs) {
+            break;
+        }
+        await sleep(10);
+    }
+    const waitedMs = Number((process.hrtime.bigint() - startNs) / 1000000n);
+    if (!held) {
+        throw new Error(`lock test hold point: barrier ${barrier} never appeared within ` +
+            `${String(HOLD_WAIT_LIMIT_MS)}ms (waited ${String(waitedMs)}ms on the ` +
+            `monotonic clock); this interleave was never staged and the run is ` +
+            `not evidence`);
+    }
+    // Record that the hold really held, and why the wait ended, so the
+    // witness can assert the interleave rather than assume it.
+    /* Re-established immediately before this second write rather than once
+       per call: the two writes are separated by a wait of up to thirty seconds
+       and the path is derived from one the CALLER supplied. */
+    const releasedRefusal = refuseOpenPathForWrite(`${barrier}.released`);
+    if (releasedRefusal !== undefined) {
+        throw new Error(`lock test hold point: ${releasedRefusal}`);
+    }
+    writeFileSync(`${barrier}.released`, `held after ${String(waitedMs)}ms (monotonic), barrier observed\n`);
+    return { observed, nowMs };
+}
+/**
+ * THE DECISION-CLOCK SEAM (M4-P21 criteria 4 and 5). When
+ * TIPHYS_LOCK_TEST_NOW_MS carries a finite number of milliseconds, every
+ * mutating subcommand decides against that instant instead of `Date.now()`,
+ * by feeding the EXISTING `nowMs` option the lease library already takes
+ * (src/lock.ts:568). It exists because the two clock-skew witnesses must
+ * move ONE environment's clock ten minutes without touching a system clock,
+ * which the plan requires by name, and because criterion 6 is about what the
+ * COMMAND prints, so the skew has to reach the command rather than only the
+ * library. Inert unless the variable is set, exactly like the hold point
+ * above, and a value that does not parse is a loud refusal rather than a
+ * silent fall back to the real clock: a seam that quietly ignores its input
+ * would make a skew witness green while measuring no skew at all.
+ *
+ * AND IT IS GATED, BECAUSE IT SHIPS. `judgeByCounter` (src/exclusion.ts:553)
+ * computes `unchangedForMs = nowMs - previous.firstSeenMs`, so the module's
+ * promised "two readings of ONE clock" become one reading of a clock the
+ * CALLER supplies. Measured in the published CLI before this gate existed:
+ * the honest challenger was refused with "fencing counter 1 has stood still
+ * for 0ms of the 900000ms this environment requires", and the SAME command
+ * with this one variable set an hour ahead took a live lease over instantly
+ * and still printed `signal=counter`. A captured witness of that run was
+ * indistinguishable from an honest one.
+ *
+ * TWO CHANGES, and they are different in kind. The ALLOWANCE
+ * (TIPHYS_ALLOW_TEST_CLOCK=1) makes reaching the seam a declared act rather
+ * than a side effect of one environment variable. The LABEL makes the run
+ * SAY SO: `injectedClockSuffix` below is appended to every verdict line the
+ * shared layer prints, so the output of a measurement can never be quoted as
+ * the output of a real judgement. An allowance alone would leave the second
+ * hole open, which is why both are here.
+ */
+export const TEST_CLOCK_ALLOWANCE = "TIPHYS_ALLOW_TEST_CLOCK";
+function testClockMs() {
+    const raw = process.env.TIPHYS_LOCK_TEST_NOW_MS;
+    if (raw === undefined || raw === "") {
+        return undefined;
+    }
+    if (process.env[TEST_CLOCK_ALLOWANCE] !== "1") {
+        throw new Error(`lock test clock: TIPHYS_LOCK_TEST_NOW_MS is set and ` +
+            `${TEST_CLOCK_ALLOWANCE}=1 is not, so this run would have decided ` +
+            `cross-environment exclusion against a clock its caller supplied ` +
+            `while printing the same verdict an honest run prints; set ` +
+            `${TEST_CLOCK_ALLOWANCE}=1 to declare that this run is a measurement, ` +
+            `or unset TIPHYS_LOCK_TEST_NOW_MS`);
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`lock test clock: TIPHYS_LOCK_TEST_NOW_MS=${raw} does not parse as a ` +
+            `number of milliseconds; this run would have measured the real clock ` +
+            `and is not evidence`);
+    }
+    return parsed;
+}
+/**
+ * What a verdict line gains when the decision clock was injected. Empty on
+ * every honest run, so no shipped output changes for anyone who does not set
+ * the variable.
+ */
+function injectedClockSuffix() {
+    return process.env.TIPHYS_LOCK_TEST_NOW_MS === undefined ||
+        process.env.TIPHYS_LOCK_TEST_NOW_MS === ""
+        ? ""
+        : "(injected-clock)";
+}
+/**
+ * Emit the shared exclusion layer's verdict line. One line, and it always
+ * names the SIGNAL that reached the verdict (criterion 6): `signal=counter`
+ * where the register was reachable and its fencing counter decided, or
+ * `signal=clock` where it was not and the command therefore refused rather
+ * than deciding cross-environment exclusion on a local clock.
+ */
+function reportShared(outcome) {
+    if (outcome.shared !== undefined) {
+        process.stdout.write(`${labelClock(outcome.shared.line)}\n`);
+    }
+}
+/**
+ * Mark every `signal=<basis>` token in a verdict line when this run's
+ * decision clock was injected. The token is what criterion 6 asks the
+ * command to print, so it is the token that has to carry the caveat.
+ */
+function labelClock(line) {
+    const suffix = injectedClockSuffix();
+    return suffix === "" ? line : line.replace(/signal=(counter|clock)/g, `signal=$1${suffix}`);
+}
+function usageError(message) {
+    if (message !== undefined) {
+        process.stderr.write(`tiphys lock: ${message}\n`);
+    }
+    process.stderr.write(`${USAGE}\n`);
+    return EX_USAGE;
+}
+/**
+ * The one failure emitter for acquire, renew, and release (CR-204).
+ * When the library classified the failure as a stale mutation claim,
+ * the operator is pointed at the claim file rather than at a holder
+ * that may not exist; the remedy text lives here, so a CLI that
+ * ignored the classification would visibly lose it. Operational
+ * failures exit 1 (usage errors alone use EX_USAGE).
+ */
+function failure(outcome) {
+    // D-2: the claim file is the sole serializer of lock mutations, so
+    // deleting one that is actually live lets a second mutation enter the
+    // critical section and can produce two live holders. The remedy text
+    // therefore states that cost instead of inviting the deletion, and it
+    // names the safe order: make sure no tiphys process is running first.
+    const remedy = outcome.claimTimeout === true
+        ? "; a crashed mutation can leave this file behind, but deleting it while a mutation is genuinely in flight can produce two lock holders, so confirm no tiphys process is running against this fleet before removing it"
+        : "";
+    process.stderr.write(`tiphys lock: ${labelClock(outcome.reason)}${remedy}\n`);
+    return 1;
+}
+function parseFlags(rest) {
+    const parsed = {
+        takeover: false,
+        holder: undefined,
+        durationSeconds: undefined,
+    };
+    for (let i = 0; i < rest.length; i += 1) {
+        const flag = rest[i];
+        if (flag === "--take-over") {
+            parsed.takeover = true;
+        }
+        else if (flag === "--holder" && i + 1 < rest.length) {
+            parsed.holder = rest[i + 1];
+            i += 1;
+        }
+        else if (flag === "--duration" && i + 1 < rest.length) {
+            const seconds = Number(rest[i + 1]);
+            if (!Number.isFinite(seconds) || seconds <= 0) {
+                return undefined;
+            }
+            parsed.durationSeconds = seconds;
+            i += 1;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return parsed;
+}
+export async function cmdLock(args) {
+    const [subcommand, ...rest] = args;
+    if (subcommand === undefined) {
+        return usageError();
+    }
+    const flags = parseFlags(rest);
+    if (flags === undefined) {
+        return usageError();
+    }
+    let lockPath;
+    try {
+        lockPath = loadFleet(process.cwd()).lockPath;
+    }
+    catch (error) {
+        process.stderr.write(`tiphys lock: ${error.message}\n`);
+        return 1;
+    }
+    switch (subcommand) {
+        case "acquire": {
+            if (flags.holder !== undefined) {
+                return usageError("acquire does not take --holder");
+            }
+            const held = await maybeHoldForTest(lockPath);
+            const outcome = await acquireLease(lockPath, {
+                takeover: flags.takeover,
+                durationSeconds: flags.durationSeconds,
+                observed: held?.observed,
+                nowMs: testClockMs() ?? held?.nowMs,
+            });
+            if (!outcome.ok) {
+                return failure(outcome);
+            }
+            const lease = outcome.lease;
+            if (lease === null) {
+                throw new Error("unreachable: acquire produced no lease");
+            }
+            process.stdout.write(`acquired ${lease.holderId} expires ${lease.expiresAt}\n`);
+            reportShared(outcome);
+            return 0;
+        }
+        case "renew": {
+            if (flags.holder === undefined || flags.takeover) {
+                return usageError("renew requires --holder <id>");
+            }
+            const held = await maybeHoldForTest(lockPath);
+            const outcome = await renewLease(lockPath, flags.holder, {
+                durationSeconds: flags.durationSeconds,
+                observed: held?.observed,
+                nowMs: testClockMs() ?? held?.nowMs,
+            });
+            if (!outcome.ok) {
+                return failure(outcome);
+            }
+            const lease = outcome.lease;
+            if (lease === null) {
+                throw new Error("unreachable: renew produced no lease");
+            }
+            process.stdout.write(`renewed ${lease.holderId} expires ${lease.expiresAt}\n`);
+            reportShared(outcome);
+            return 0;
+        }
+        case "release": {
+            if (flags.holder === undefined || flags.takeover || flags.durationSeconds !== undefined) {
+                return usageError("release requires --holder <id> and no other flags");
+            }
+            const held = await maybeHoldForTest(lockPath);
+            const releaseOptions = {
+                observed: held?.observed,
+            };
+            const releaseClock = testClockMs();
+            if (releaseClock !== undefined) {
+                releaseOptions.nowMs = releaseClock;
+            }
+            const outcome = await releaseLease(lockPath, flags.holder, releaseOptions);
+            if (!outcome.ok) {
+                return failure(outcome);
+            }
+            process.stdout.write(`released ${flags.holder}\n`);
+            reportShared(outcome);
+            return 0;
+        }
+        case "status": {
+            if (flags.holder !== undefined || flags.takeover || flags.durationSeconds !== undefined) {
+                return usageError("status takes no flags");
+            }
+            const status = leaseStatus(lockPath);
+            if (status.state === "free") {
+                process.stdout.write("free\n");
+            }
+            else if (status.state === "corrupt") {
+                process.stdout.write(`corrupt ${status.detail}\n`);
+            }
+            else {
+                process.stdout.write(`${status.state} holder ${status.lease.holderId} acquired ` +
+                    `${status.lease.acquiredAt} expires ${status.lease.expiresAt}\n`);
+            }
+            // status always exits 0 so a human takeover decision is informed
+            // by reading, never blocked by an exit code.
+            return 0;
+        }
+        default:
+            return usageError(`unknown lock subcommand "${subcommand}"`);
+    }
+}

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

@@ -0,0 +1,40 @@
+/**
+ * `tiphys mode show --mode <id> [--file <path>]` (kernel plan M3, M3-P3
+ * step 5; fix round 1 finding B-002).
+ *
+ * WHY THIS COMMAND EXISTS: a brief or a human has to be able to read what a
+ * declared mode requires without parsing YAML by hand. That is the whole
+ * scope. It shows; it does not resolve a project into a mode, does not
+ * enforce one, and does not run one.
+ *
+ * IT VALIDATES BEFORE IT SERVES, and that is the point of the fix round.
+ * As first shipped this command read the document and printed it, invoking
+ * neither the schema nor any registered check, so every guard the phase built
+ * was bypassed on the one path built for humans and briefs. The mechanism is
+ * A READER THAT DOES NOT VALIDATE WHAT IT READS, and the fix is not "detect
+ * one more bad state": it is that this command now runs exactly what
+ * `tiphys validate --type assurance-modes --context <dir>` runs, and REFUSES
+ * rather than printing when the document fails. A partial answer from an
+ * invalid document is worse than an error, because the reader cannot tell.
+ *
+ * THE CONTEXT IS THE DOCUMENT'S OWN DIRECTORY. The cross-document checks
+ * resolve `gate-registry.yaml` and `schemas/charter.schema.json` beside the
+ * document, which is where the npm package puts them and where this repository
+ * keeps them. That makes the two `requiresContext` checks run here rather than
+ * SKIP, which matters: a skip fails the run, and a command that always failed
+ * would be a command nobody uses.
+ *
+ * Exit codes:
+ *   0   the document is valid and the mode was found and printed
+ *   1   the document could not be read, is invalid, or no mode carries that id
+ *   64  usage error (BSD sysexits EX_USAGE)
+ *
+ * A MODE ID THAT IS NOT DECLARED IS 1, NOT 64, and the difference is not
+ * pedantry. 64 means the caller used the command wrongly; 1 means the command
+ * worked and the answer is no. `--mode direct-pr` against a document that
+ * declares only `full` is a well-formed question with a negative answer, and a
+ * caller that cannot tell those apart cannot script this.
+ */
+/** Exit code for usage errors, per BSD sysexits EX_USAGE. */
+export declare const EX_USAGE = 64;
+export declare function cmdMode(argv: string[]): number;

package/dist/src/commands/mode.js

@@ -0,0 +1,134 @@
+/**
+ * `tiphys mode show --mode <id> [--file <path>]` (kernel plan M3, M3-P3
+ * step 5; fix round 1 finding B-002).
+ *
+ * WHY THIS COMMAND EXISTS: a brief or a human has to be able to read what a
+ * declared mode requires without parsing YAML by hand. That is the whole
+ * scope. It shows; it does not resolve a project into a mode, does not
+ * enforce one, and does not run one.
+ *
+ * IT VALIDATES BEFORE IT SERVES, and that is the point of the fix round.
+ * As first shipped this command read the document and printed it, invoking
+ * neither the schema nor any registered check, so every guard the phase built
+ * was bypassed on the one path built for humans and briefs. The mechanism is
+ * A READER THAT DOES NOT VALIDATE WHAT IT READS, and the fix is not "detect
+ * one more bad state": it is that this command now runs exactly what
+ * `tiphys validate --type assurance-modes --context <dir>` runs, and REFUSES
+ * rather than printing when the document fails. A partial answer from an
+ * invalid document is worse than an error, because the reader cannot tell.
+ *
+ * THE CONTEXT IS THE DOCUMENT'S OWN DIRECTORY. The cross-document checks
+ * resolve `gate-registry.yaml` and `schemas/charter.schema.json` beside the
+ * document, which is where the npm package puts them and where this repository
+ * keeps them. That makes the two `requiresContext` checks run here rather than
+ * SKIP, which matters: a skip fails the run, and a command that always failed
+ * would be a command nobody uses.
+ *
+ * Exit codes:
+ *   0   the document is valid and the mode was found and printed
+ *   1   the document could not be read, is invalid, or no mode carries that id
+ *   64  usage error (BSD sysexits EX_USAGE)
+ *
+ * A MODE ID THAT IS NOT DECLARED IS 1, NOT 64, and the difference is not
+ * pedantry. 64 means the caller used the command wrongly; 1 means the command
+ * worked and the answer is no. `--mode direct-pr` against a document that
+ * declares only `full` is a well-formed question with a negative answer, and a
+ * caller that cannot tell those apart cannot script this.
+ */
+import { dirname } from "node:path";
+import { runChecks } from "../checks.js";
+import { formatDiagnostics, validateInstance } from "../validate.js";
+import { loadTypeSchema } from "./validate.js";
+import { readModes, renderMode } from "../modes.js";
+/** The artifact type this command reads, and the type its checks are registered for. */
+const MODES_TYPE = "assurance-modes";
+/** Exit code for usage errors, per BSD sysexits EX_USAGE. */
+export const EX_USAGE = 64;
+function usage() {
+    return "usage: tiphys mode show --mode <id> [--file <path>]";
+}
+function parseArgs(argv) {
+    const options = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--mode" || argument === "--file") {
+            const value = argv[index + 1];
+            if (value === undefined || value.startsWith("--")) {
+                return { usageError: `${argument} requires a value` };
+            }
+            if (argument === "--mode") {
+                options.mode = value;
+            }
+            else {
+                options.file = value;
+            }
+            index += 1;
+            continue;
+        }
+        return { usageError: `unknown argument ${argument}` };
+    }
+    if (options.mode === undefined) {
+        return { usageError: "--mode is required" };
+    }
+    return { options };
+}
+function fail(reason, code) {
+    process.stderr.write(`tiphys mode: ${reason}\n`);
+    if (code === EX_USAGE) {
+        process.stderr.write(`${usage()}\n`);
+    }
+    return code;
+}
+export function cmdMode(argv) {
+    const [subcommand, ...rest] = argv;
+    if (subcommand !== "show") {
+        return fail(subcommand === undefined
+            ? "a subcommand is required"
+            : `unknown subcommand ${subcommand}`, EX_USAGE);
+    }
+    const parsed = parseArgs(rest);
+    if (parsed.options === undefined) {
+        return fail(parsed.usageError ?? "usage error", EX_USAGE);
+    }
+    let read;
+    try {
+        read = parsed.options.file === undefined ? readModes() : readModes(parsed.options.file);
+    }
+    catch (error) {
+        /* `packageRoot` throws when the shipped document is not above this module,
+           which is an incomplete installation rather than a caller error. One line,
+           never a stack trace, the same policy `tiphys validate` applies to its own
+           operator-supplied input. */
+        return fail(String(error instanceof Error ? error.message : error), 1);
+    }
+    if (!read.ok) {
+        return fail(read.reason, 1);
+    }
+    /* VALIDATE, THEN SERVE. Schema first and derived checks second, in the same
+       order and through the same functions `tiphys validate` uses, so the two
+       commands cannot drift into disagreeing about what a valid document is. */
+    const lines = formatDiagnostics(validateInstance(loadTypeSchema(MODES_TYPE), read.raw));
+    const checks = runChecks(MODES_TYPE, read.raw, dirname(read.path));
+    if (lines.length > 0 || checks.failed) {
+        process.stderr.write(`tiphys mode: ${read.path} is not a valid ${MODES_TYPE} document, so it is not served\n`);
+        for (const line of [...lines, ...checks.lines]) {
+            process.stderr.write(`${line}\n`);
+        }
+        return 1;
+    }
+    const wanted = parsed.options.mode;
+    const mode = read.modes.find((candidate) => candidate.id === wanted);
+    if (mode === undefined) {
+        const declared = read.modes.map((candidate) => candidate.id).sort();
+        return fail(`${read.path} declares no mode ${wanted}; it declares ${declared.length === 0 ? "none" : declared.join(", ")}`, 1);
+    }
+    /* WHICH DOCUMENT THIS IS, derived from the invocation rather than from the
+       path: no `--file` means `readModes()` walked to the package root and read
+       the kernel's own document. CR-004 item 2 turns on that distinction, because
+       "no phase has been delivered under this mode" is a claim about the kernel's
+       own delivery and is not knowable for a document a consumer supplied. */
+    for (const line of renderMode(mode, { shippedDocument: parsed.options.file === undefined })) {
+        process.stdout.write(`${line}\n`);
+    }
+    return 0;
+}

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

@@ -0,0 +1,130 @@
+import type { Fleet } from "../fleet.ts";
+/**
+ * Work remains. DISTINCT FROM 1, which is the command failing, and from 0,
+ * which is every in-flight category empty (criterion 1).
+ */
+export declare const EXIT_WORK_REMAINS = 3;
+/**
+ * WHAT THIS COMMAND CANNOT SEE, as a NAMED LIST (criterion 4).
+ *
+ * Printed unconditionally. It is not derived from a probe and it does not
+ * shorten when something is unreachable, because a list that shrinks when the
+ * network is gone tells the reader that fewer things are unknown at exactly
+ * the moment more of them are.
+ */
+export declare const CANNOT_SEE: readonly string[];
+/** The heading the cannot-see block is printed under. */
+export declare const CANNOT_SEE_HEADING = "cannot see (this command has no network; an absence here is not evidence of absence):";
+/** How a branch turned out to have been delivered, or why that is not settled. */
+export type Delivery = {
+    kind: "delivered";
+    how: "ancestor" | "squash" | "patch-equivalent";
+} | {
+    kind: "open";
+} | {
+    kind: "unknown";
+    detail: string;
+};
+/**
+ * THE DELIVERED-ELSEWHERE PREDICATE (criterion 3).
+ *
+ * `git branch --merged` reports a squash-merged branch as UNMERGED, because
+ * the squash commit's sha is not the branch tip and the branch tip is not an
+ * ancestor of the base. This process squash-merges every phase, so under the
+ * naive implementation EVERY delivered branch reads as open forever and the
+ * stop condition never goes green.
+ *
+ * THE CITATION THAT STOOD HERE UNTIL ROUND 1 WAS WRONG, AND IT WAS WRONG IN
+ * THE SILENT DIRECTION. It read `delivery/STATE.md:54`, which resolves, which
+ * is why no gate reddened; the line it resolves to is about two merge blockers
+ * and says nothing about `git branch --merged`. Measured:
+ * `grep -n 'branch --merged' delivery/STATE.md` returns nothing, at this head
+ * and at the merge base, so the sentence is absent rather than moved. The
+ * claim itself is measured in this repository and the measurement is the
+ * citation now: witness/captures/next-delivered-elsewhere-git.txt records
+ * `git branch --merged main` listing neither the squash-merged branch nor the
+ * one delivered through another pull request. The same wrong citation is in
+ * the plan at delivery/plan/kernel-plan-m4.md:3239 and in this phase's work
+ * history; the work history is corrected, and the plan is an owner-approved
+ * document this phase does not edit, so it is raised rather than changed.
+ *
+ * THREE ARMS, AND THE THIRD IS WHY THIS IS NOT JUST A CALL TO `landedness`.
+ *
+ *   1. ANCESTOR. An ordinary merge or a fast-forward. `landedness` arm one.
+ *   2. CONTENT. Merging the branch into the base changes no tree, so the base
+ *      already carries everything the branch did however it got there. This is
+ *      MEMBER A, the squash merge, and it is `landedness` arm two.
+ *   3. PATCH EQUIVALENCE. Every commit the branch carries has an equivalent
+ *      patch already upstream, found by patch id rather than by sha. This is
+ *      MEMBER B: commits that landed inside ANOTHER branch's pull request, so
+ *      they appear on the base interleaved with commits the branch never had.
+ *
+ * ARM 3 IS NOT REDUNDANT WITH ARM 2, and the case that separates them is the
+ * ordinary one. Once the base moves on and edits the same region again, a
+ * three-way merge of the delivered branch CONFLICTS, so arm 2 answers `open`
+ * for a branch whose every commit is demonstrably already upstream. Arm 3
+ * answers it by patch id, which survives the later edit.
+ *
+ * ARM 2 IS NOT REDUNDANT WITH ARM 3 EITHER. A squash collapses N commits into
+ * one, whose patch id is the id of the COMBINED diff and therefore equals no
+ * individual commit's. For any branch of more than one commit, arm 3 sees only
+ * unmatched commits and answers `open`.
+ *
+ * REUSE, NOT A SECOND IMPLEMENTATION (T-005). Arms 1 and 2 are
+ * `landedness` at src/teardown.ts:123, the predicate `tiphys teardown` already
+ * refuses on. A second copy here would be a second thing to keep true.
+ *
+ * INCONCLUSIVE IS NOT `open` AND IT IS NOT `delivered`. A git failure returns
+ * `unknown`, which the caller counts as work remaining, because the one answer
+ * this predicate must never invent is a confident one.
+ */
+export declare function deliveredElsewhere(contextDir: string, branchRef: string, baseRef: string): Delivery;
+/** One thing that is in flight, in the category that found it. */
+export interface InFlightItem {
+    category: "task" | "worktree" | "branch";
+    what: string;
+}
+/**
+ * Everything in flight in a fleet home, plus every candidate left unread, plus
+ * the disclosures a reader needs to check the judgement rather than trust it.
+ *
+ * `notes` DOES NOT COUNT TOWARD THE EXIT CODE and that is deliberate. It
+ * carries facts about HOW a judgement was made (which base ref each project's
+ * branches were compared against, and by which rule that base was chosen), not
+ * facts about whether work remains. Putting them in `unknown` would hold the
+ * exit at `EXIT_WORK_REMAINS` forever; leaving them out is what let a clone
+ * whose `origin/HEAD` points at a feature branch judge every branch against
+ * that branch with nothing in the output saying so.
+ */
+export interface InFlight {
+    items: InFlightItem[];
+    unknown: string[];
+    notes: string[];
+}
+export declare function baseRefOf(projectDir: string): {
+    ok: true;
+    ref: string;
+    how: string;
+    doubt?: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Every in-flight category in a fleet home, in dependency order: the task
+ * record, the checkout it owns, and the branch that outlives both.
+ */
+export declare function collectInFlight(fleet: Fleet): InFlight;
+/**
+ * THE ONE NEXT ACTION (criterion 1). Exactly one, chosen by the first
+ * non-empty category in the order above, so the answer is derived from the
+ * report rather than picked.
+ */
+export declare function nextAction(report: InFlight): string;
+/** The cannot-see block. Unconditional, and it probes nothing to build. */
+export declare function cannotSeeBlock(): string[];
+/** The whole report, as lines, with exactly one `next action:` line. */
+export declare function renderReport(fleet: Fleet, report: InFlight): string[];
+/** Work remains whenever anything is in flight OR anything could not be read. */
+export declare function exitCodeFor(report: InFlight): number;
+export declare function cmdNext(args: string[]): number;