@tiphys/kernel 0.0.0 → 0.1.0

package/dist/src/lock.js

@@ -0,0 +1,500 @@
+import { randomUUID } from "node:crypto";
+import { linkSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { hostname } from "node:os";
+import { setTimeout as sleep } from "node:timers/promises";
+/**
+ * Lease-based session lock (kernel plan v1, M1-P3 step 1; DR-0007; plan
+ * constraint C-2). One orchestrator per fleet: the lock file at
+ * state/orchestrator.lock holds a JSON lease {holderId, hostname,
+ * acquiredAt, expiresAt, durationSeconds, token} where holderId is an
+ * opaque value generated at acquire. Liveness is lease freshness only:
+ * this module never probes any running program in any way (FM-053), and
+ * the death of a holder is deliberately invisible to the lease (an
+ * unexpired lease excludes even when its holder is gone; recovery is the
+ * explicit --take-over after expiry).
+ *
+ * Mutation contract (EXT-F-01, adopted verbatim from the plan):
+ * - Every mutation (acquire, renew, release, takeover) goes through the
+ *   ONE shared atomic mutation primitive, applyLeaseMutation. A mutation
+ *   is decided against an observed lease state and applied only if the
+ *   file still holds exactly that state; the application is confirmed by
+ *   re-reading the unique per-mutation token it wrote. A confirmation
+ *   showing another writer's token means the mutation lost and returns
+ *   failure without retry. Ownership is not valid until the primitive
+ *   completes.
+ * - Renew fails on an expired lease and succeeds only while holderId
+ *   matches and expiresAt is in the future.
+ * - Takeover succeeds only if the observed lease is still the lease being
+ *   replaced (compare-and-swap over the lease file content) and
+ *   serializes with renew, release, and competing takeovers.
+ *
+ * Serialization mechanism: mutations are serialized through a claim file
+ * beside the lock (<lock>.mutex, created O_EXCL; FM-022's
+ * serialize-through-a-claim pattern), and inside that claim the primitive
+ * re-reads the lock, byte-compares it with the observed state, applies
+ * via O_EXCL create (absent lock, PR-006) or write-temp-then-rename, and
+ * confirms by re-reading its own token (FM-022 write-then-verify). No
+ * steal protocol exists on purpose (FM-058): a claim file left behind by
+ * a crashed mutation makes later mutations fail loudly after a bounded
+ * wait, naming the file for manual removal; the critical section is a
+ * few file operations, so this window is tiny.
+ *
+ * What the token confirmation is and is NOT (corrected per D-2; the
+ * previous wording here claimed a second safety net that does not
+ * exist). The confirmation read asserts only "my bytes are in the file
+ * now". That is last-writer-wins: it catches an intruder who applied
+ * AFTER this mutation, and it does NOT catch one who applied before and
+ * merely lost the race to write last. The O_EXCL claim file is
+ * therefore the sole serializer, and it is advisory: no handle is held
+ * on it and nothing checks ownership when it is unlinked. The apply is
+ * preceded by a second read-and-compare (stillMatches) so that a lost
+ * claim degrades to a clean loss instead of a double win, but that
+ * narrows the window rather than closing it. Deleting a live claim file
+ * can still produce two holders; that is why the CLI's remedy text now
+ * says so instead of inviting it.
+ *
+ * Exclusion domain (PR-201, DR-0007 stated honestly): the lease excludes
+ * within one filesystem and one clock, the fleet home the lock file lives
+ * in. Cross-environment exclusion for a fleet shared through a git remote
+ * is M4 residue and is not claimed here. Mutations of the lock file made
+ * outside this module (manual edits) are not covered by the contract.
+ *
+ * Renewal discipline (PR-203): the default lease lasts 900 seconds and
+ * the holder renews at or before half-life (renewByMs). Holdership on
+ * mutating kernel commands (spawn, teardown) is verified against the
+ * lease by M1-P4.
+ */
+export const DEFAULT_LEASE_DURATION_SECONDS = 900;
+/** Bounded wait for the mutation claim file, then fail loudly. */
+const MUTEX_WAIT_TOTAL_MS = 5000;
+const MUTEX_WAIT_POLL_MS = 10;
+function parseLease(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    const candidate = parsed;
+    if (typeof candidate.holderId !== "string" ||
+        candidate.holderId === "" ||
+        typeof candidate.hostname !== "string" ||
+        typeof candidate.acquiredAt !== "string" ||
+        typeof candidate.expiresAt !== "string" ||
+        typeof candidate.durationSeconds !== "number" ||
+        typeof candidate.token !== "string" ||
+        Number.isNaN(Date.parse(candidate.expiresAt))) {
+        return undefined;
+    }
+    return candidate;
+}
+export function renderLease(lease) {
+    return `${JSON.stringify(lease, null, 2)}\n`;
+}
+/** Read the current lock file state: absent, or present with raw bytes. */
+export function observeLease(lockPath) {
+    let raw;
+    try {
+        raw = readFileSync(lockPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { kind: "absent" };
+        }
+        throw error;
+    }
+    return { kind: "present", raw, lease: parseLease(raw) };
+}
+export function isExpired(lease, nowMs) {
+    return Date.parse(lease.expiresAt) <= nowMs;
+}
+/** The renew-by deadline (half-life of the current term), for holders. */
+export function renewByMs(lease) {
+    return Date.parse(lease.expiresAt) - (lease.durationSeconds * 1000) / 2;
+}
+function readCurrent(lockPath) {
+    try {
+        return { present: true, raw: readFileSync(lockPath, "utf8") };
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { present: false, raw: "" };
+        }
+        throw error;
+    }
+}
+/**
+ * Re-read the lock file and re-compare it against the state a mutation
+ * was decided on. Used immediately before every apply (D-2).
+ */
+function stillMatches(lockPath, observed) {
+    const current = readCurrent(lockPath);
+    if (observed.kind === "absent") {
+        return !current.present;
+    }
+    return current.present && current.raw === observed.raw;
+}
+/**
+ * The single staging path a lease rename goes through (CR-202). One
+ * fixed name is safe because staging only ever happens inside the
+ * mutation claim, and it makes strand cleanup deterministic.
+ */
+export function stagePathFor(lockPath) {
+    return `${lockPath}.stage`;
+}
+/**
+ * The one shared atomic mutation primitive (EXT-F-01). Applies next (new
+ * file content, or null to remove the lock) only if the lock file still
+ * holds exactly the observed state, and confirms the application by
+ * re-reading the mutation's own token. Loses without retry otherwise.
+ */
+export async function applyLeaseMutation(lockPath, observed, next, token) {
+    const mutexPath = `${lockPath}.mutex`;
+    const deadline = Date.now() + MUTEX_WAIT_TOTAL_MS;
+    for (;;) {
+        try {
+            writeFileSync(mutexPath, token, { flag: "wx" });
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                throw error;
+            }
+            if (Date.now() >= deadline) {
+                // CR-204: name the lease situation first, so an operator is not
+                // nudged toward a takeover when the obstacle is a claim file and
+                // there is no lease at all.
+                // The remedy sentence is deliberately NOT part of this reason:
+                // the CLI appends it from the claimTimeout flag, so the
+                // classification is load-bearing at every layer rather than
+                // carried along as prose (CR-204).
+                // U-6: an expired lease is not a held one. Saying "lock held"
+                // here contradicted lock status in the same fleet, which calls
+                // the same lease expired, and reads as "the holder is alive"
+                // when the truth is the opposite.
+                const holder = observed.kind === "present" && observed.lease !== undefined
+                    ? isExpired(observed.lease, Date.now())
+                        ? `expired lease from ${observed.lease.holderId}`
+                        : `lock held by ${observed.lease.holderId}`
+                    : "no lease, no live holder";
+                return {
+                    won: false,
+                    claimTimeout: true,
+                    reason: `${holder}; stale claim file ${mutexPath} blocking after ` +
+                        `${String(MUTEX_WAIT_TOTAL_MS)}ms`,
+                };
+            }
+            await sleep(MUTEX_WAIT_POLL_MS);
+        }
+    }
+    try {
+        // CR-202: clear any stranded stage left by a mutation that died
+        // between its stage write and its rename. This runs inside the
+        // claim, so it provably cannot race a live mutation (a live one
+        // would hold the claim), which is why no age heuristic is needed
+        // or wanted. It is unconditional because the release path (unlink)
+        // and the absent-lock acquire path (O_EXCL create) never touch the
+        // stage: cleaning only in the rename branch would let a strand
+        // survive a release/acquire-only sequence indefinitely.
+        try {
+            unlinkSync(stagePathFor(lockPath));
+        }
+        catch {
+            // No strand present, which is the normal case.
+        }
+        const current = readCurrent(lockPath);
+        if (observed.kind === "absent") {
+            if (current.present) {
+                return {
+                    won: false,
+                    reason: "lost: a lease appeared after this mutation observed none",
+                };
+            }
+        }
+        else if (!current.present) {
+            return {
+                won: false,
+                reason: "lost: the observed lease is gone",
+            };
+        }
+        else if (current.raw !== observed.raw) {
+            return {
+                won: false,
+                reason: "lost: the lease changed after this mutation observed it",
+            };
+        }
+        // D-2: re-read and re-compare immediately before every apply. The
+        // claim file is the ONLY serializer, and it is advisory: no handle
+        // is held on it, and the operator remedy this CLI prints tells a
+        // human to delete it. If a claim is lost that way, another mutation
+        // can enter this section concurrently; without this second compare
+        // both could apply and both could believe they won. With it, the
+        // loser sees changed bytes and degrades to a clean loss. This
+        // narrows the window to the syscall gap; it does not remove it, and
+        // the module docs say so rather than claiming a guarantee.
+        if (!stillMatches(lockPath, observed)) {
+            return {
+                won: false,
+                reason: "lost: the lease changed while this mutation held the claim",
+            };
+        }
+        if (next === null) {
+            unlinkSync(lockPath);
+            const confirm = readCurrent(lockPath);
+            if (confirm.present) {
+                return { won: false, reason: "lost: removal did not stick" };
+            }
+            return { won: true };
+        }
+        if (observed.kind === "absent") {
+            // D-1: publish the initial lease atomically. writeFileSync with
+            // flag "wx" is openSync(O_EXCL) followed by a SEPARATE writeSync,
+            // so the lock file's NAME becomes visible at length zero before
+            // the lease bytes land. observeLease, leaseStatus and doctor all
+            // read outside the claim, so a reader landing in that window sees
+            // an empty file and reports a healthy fleet as corrupt; it turned
+            // acceptance criterion 3's own witness red on pristine code.
+            //
+            // linkSync gives both properties at once: the stage file already
+            // holds the complete lease, and link fails with EEXIST if the
+            // lock path exists, which is exactly the atomic exclusive-create
+            // test PR-006 asks for. So exclusion is preserved and the name
+            // never exists half-published. renew and takeover were already
+            // immune because they stage then rename; this makes the absent
+            // lock path use the same discipline, which is the asymmetry the
+            // module previously left unjustified.
+            const stagePath = stagePathFor(lockPath);
+            writeFileSync(stagePath, next);
+            try {
+                linkSync(stagePath, lockPath);
+            }
+            catch (error) {
+                if (error.code === "EEXIST") {
+                    return {
+                        won: false,
+                        reason: "lost: a lease appeared after this mutation observed none",
+                    };
+                }
+                throw error;
+            }
+            finally {
+                try {
+                    unlinkSync(stagePath);
+                }
+                catch {
+                    // The stage sweep at the top of the claim also covers this.
+                }
+            }
+        }
+        else {
+            // The stage is ONE fixed path beside the lock (CR-202). Every
+            // stage write happens inside the claim, so no two stages can ever
+            // coexist and a fixed name needs no uniqueness to be safe; the
+            // claim-held sweep above then makes cleanup of a crash strand
+            // deterministic (exactly one possible strand path, removed
+            // unconditionally) instead of an age-based guess over a family of
+            // unique names. The CAS is untouched by this choice: the
+            // byte-compare against the observed state and the token
+            // confirmation read both still happen inside the claim, and the
+            // rename remains atomic within one directory.
+            const stagePath = stagePathFor(lockPath);
+            writeFileSync(stagePath, next);
+            try {
+                renameSync(stagePath, lockPath);
+            }
+            catch (error) {
+                try {
+                    unlinkSync(stagePath);
+                }
+                catch {
+                    // Stage cleanup is best effort; the original error surfaces.
+                }
+                if (error.code === "ENOENT") {
+                    // Another mutation swept this stage, which means it entered
+                    // the critical section concurrently, which means this claim
+                    // was lost (D-2). Report it as a loss rather than letting a
+                    // raw ENOENT stack out of the CLI.
+                    return {
+                        won: false,
+                        reason: "lost: the staged lease disappeared before it was published, " +
+                            "which means another mutation held the claim concurrently",
+                    };
+                }
+                throw error;
+            }
+        }
+        const confirm = readCurrent(lockPath);
+        const confirmedLease = confirm.present ? parseLease(confirm.raw) : undefined;
+        if (confirmedLease === undefined || confirmedLease.token !== token) {
+            return {
+                won: false,
+                reason: "lost: confirmation read shows another writer's token",
+            };
+        }
+        return { won: true };
+    }
+    finally {
+        try {
+            unlinkSync(mutexPath);
+        }
+        catch {
+            // Claim file already gone; nothing to release.
+        }
+    }
+}
+function buildLease(nowMs, durationSeconds) {
+    return {
+        holderId: randomUUID(),
+        hostname: hostname(),
+        acquiredAt: new Date(nowMs).toISOString(),
+        expiresAt: new Date(nowMs + durationSeconds * 1000).toISOString(),
+        durationSeconds,
+        token: randomUUID(),
+    };
+}
+/**
+ * Acquire the lease, or take over an expired one when takeover is set.
+ * Refusals (lock held, expired without takeover, unexpired takeover)
+ * never mutate the file; only won mutations do.
+ */
+export async function acquireLease(lockPath, options = {}) {
+    const nowMs = options.nowMs ?? Date.now();
+    const durationSeconds = options.durationSeconds ?? DEFAULT_LEASE_DURATION_SECONDS;
+    const observed = options.observed ?? observeLease(lockPath);
+    if (observed.kind === "present") {
+        if (observed.lease === undefined) {
+            return {
+                ok: false,
+                reason: `lease file ${lockPath} is corrupt; inspect it manually`,
+            };
+        }
+        if (!isExpired(observed.lease, nowMs)) {
+            return {
+                ok: false,
+                reason: options.takeover === true
+                    ? `takeover refused: lock held by ${observed.lease.holderId}, unexpired until ${observed.lease.expiresAt}`
+                    : `lock held by ${observed.lease.holderId}, expires ${observed.lease.expiresAt}`,
+            };
+        }
+        if (options.takeover !== true) {
+            return {
+                ok: false,
+                reason: `lease expired (holder ${observed.lease.holderId}, expired ` +
+                    `${observed.lease.expiresAt}); acquire refused, takeover is ` +
+                    `explicit: lock acquire --take-over`,
+            };
+        }
+    }
+    const lease = buildLease(nowMs, durationSeconds);
+    const result = await applyLeaseMutation(lockPath, observed, renderLease(lease), lease.token);
+    if (!result.won) {
+        // CR-204: a claim-file timeout is not a held lease. Its reason
+        // already states the lease situation, so it is never re-prefixed
+        // with "lock held", and the classification travels to the caller.
+        if (result.claimTimeout === true) {
+            return { ok: false, reason: result.reason, claimTimeout: true };
+        }
+        return { ok: false, reason: `lock held (${result.reason})` };
+    }
+    return { ok: true, lease };
+}
+/**
+ * Renew the lease held by holderId. Fails on an expired lease even when
+ * holderId matches (EXT-F-01: a paused holder whose lease expired cannot
+ * renew), fails on a holder mismatch, and never mutates the file on any
+ * failure. The new expiry strictly increases (a renew that does not
+ * extend the lease would be useless).
+ */
+export async function renewLease(lockPath, holderId, options = {}) {
+    const nowMs = options.nowMs ?? Date.now();
+    const observed = options.observed ?? observeLease(lockPath);
+    if (observed.kind === "absent") {
+        return { ok: false, reason: "renew refused: no lease present" };
+    }
+    if (observed.lease === undefined) {
+        return {
+            ok: false,
+            reason: `lease file ${lockPath} is corrupt; inspect it manually`,
+        };
+    }
+    if (observed.lease.holderId !== holderId) {
+        return {
+            ok: false,
+            reason: `renew refused: lease is held by ${observed.lease.holderId}, not ${holderId}`,
+        };
+    }
+    if (isExpired(observed.lease, nowMs)) {
+        return {
+            ok: false,
+            reason: `renew refused: lease expired ${observed.lease.expiresAt}; an ` +
+                `expired lease cannot be renewed, re-acquire or take over instead`,
+        };
+    }
+    const durationSeconds = options.durationSeconds ?? observed.lease.durationSeconds;
+    const newExpiresMs = Math.max(nowMs + durationSeconds * 1000, Date.parse(observed.lease.expiresAt) + 1);
+    const lease = {
+        ...observed.lease,
+        expiresAt: new Date(newExpiresMs).toISOString(),
+        durationSeconds,
+        token: randomUUID(),
+    };
+    const result = await applyLeaseMutation(lockPath, observed, renderLease(lease), lease.token);
+    if (!result.won) {
+        if (result.claimTimeout === true) {
+            return { ok: false, reason: result.reason, claimTimeout: true };
+        }
+        return { ok: false, reason: `renew ${result.reason}` };
+    }
+    return { ok: true, lease };
+}
+/**
+ * Release the lease held by holderId. Expiry does not block a release
+ * (an expired former holder may clean up its own lease), but a holder
+ * mismatch refuses, so a losing holder can never remove the winner's
+ * lease; and the compare-and-swap in the primitive means a release
+ * staged before a takeover completes loses to it.
+ */
+export async function releaseLease(lockPath, holderId, options = {}) {
+    const observed = options.observed ?? observeLease(lockPath);
+    if (observed.kind === "absent") {
+        return { ok: false, reason: "release refused: no lease present" };
+    }
+    if (observed.lease === undefined) {
+        return {
+            ok: false,
+            reason: `lease file ${lockPath} is corrupt; inspect it manually`,
+        };
+    }
+    if (observed.lease.holderId !== holderId) {
+        return {
+            ok: false,
+            reason: `release refused: lease is held by ${observed.lease.holderId}, not ${holderId}`,
+        };
+    }
+    const result = await applyLeaseMutation(lockPath, observed, null, randomUUID());
+    if (!result.won) {
+        if (result.claimTimeout === true) {
+            return { ok: false, reason: result.reason, claimTimeout: true };
+        }
+        return { ok: false, reason: `release ${result.reason}` };
+    }
+    return { ok: true, lease: null };
+}
+/** Report the lock state; reading only, never mutating (always safe). */
+export function leaseStatus(lockPath, nowMs = Date.now()) {
+    const observed = observeLease(lockPath);
+    if (observed.kind === "absent") {
+        return { state: "free" };
+    }
+    if (observed.lease === undefined) {
+        return {
+            state: "corrupt",
+            detail: `lease file ${lockPath} does not parse as a lease`,
+        };
+    }
+    return {
+        state: isExpired(observed.lease, nowMs) ? "expired" : "held",
+        lease: observed.lease,
+    };
+}

package/dist/src/modes.d.ts

@@ -0,0 +1,149 @@
+/**
+ * READING THE SHIPPED ASSURANCE MODE DEFINITIONS (kernel plan M3, M3-P3
+ * step 5).
+ *
+ * `assurance-modes.yaml` ships at the package root, beside `gate-registry.yaml`
+ * and the `schemas/` directory. This module locates it, decodes it, and
+ * answers one question: what does a declared mode require. Nothing here
+ * RESOLVES a mode into behaviour and nothing here enforces one. M3 never
+ * executes `direct-pr` or `local-only`, and building an enforcement engine for
+ * a mode this milestone never enters is the M1-P3 failure the plan is trying
+ * not to repeat.
+ *
+ * NO VALIDATION HAPPENS HERE, deliberately. `tiphys validate --type
+ * assurance-modes` is the command that says whether the document is
+ * well-formed, and duplicating its rules in a reader would produce a second
+ * opinion to keep in sync. This module reads what is there and reports what it
+ * cannot find.
+ */
+/** The shipped document's basename, at the package root. */
+export declare const MODES_FILENAME = "assurance-modes.yaml";
+/**
+ * Locate the package root by walking UP from this module and testing for the
+ * shipped document.
+ *
+ * The depth differs between the two layouts this code runs in: from source it
+ * is `src/` and the root is one level up, and from the built entry it is
+ * `dist/src/` and the root is two levels up. Counting `..` would be right in
+ * exactly one of them, which is the layout-dependent break
+ * `schemasDirectory()` already documents. Walking up and TESTING is right in
+ * both, and in a relocated copy as well.
+ */
+export declare function packageRoot(): string;
+/** One mode as the document declares it. Fields absent from the document stay absent. */
+export interface Mode {
+    id: string;
+    declaredBy: string;
+    pipeline: string[];
+    skips: string[];
+    gateSets: string[];
+    mergeAuthority: string;
+    grantedBy?: string;
+    conditions?: string[];
+    reviewContracts?: string[];
+    escalationBounds?: Record<string, unknown>;
+}
+export type ModesRead = 
+/**
+ * `raw` is the DECODED DOCUMENT before this module projects it into `Mode`
+ * records. It is returned because a caller must be able to validate what it
+ * is about to serve, and the projection is lossy by design (it drops
+ * anything the projection does not name). Handing a caller only the
+ * projection would force it to validate a shape no schema describes.
+ */
+{
+    ok: true;
+    path: string;
+    raw: unknown;
+    modes: Mode[];
+} | {
+    ok: false;
+    reason: string;
+};
+/** Read and decode the shipped document, or say why it could not be read. */
+export declare function readModes(path?: string): ModesRead;
+/**
+ * Where the rendered document came from. `shippedDocument` is true only when
+ * the reader was given no `--file` and therefore read the kernel's OWN
+ * `assurance-modes.yaml` from the package root.
+ *
+ * It is a REQUIRED parameter rather than an option with a default, because the
+ * execution-status line below is a claim about a specific document and a
+ * default would let a caller make that claim by omission.
+ */
+export interface RenderContext {
+    shippedDocument: boolean;
+}
+/**
+ * The execution status of one mode, DERIVED rather than looked up in a list of
+ * ids (CR-004 item 2, DR-0020).
+ *
+ * Two facts are available and both are checkable by the reader: whether this is
+ * the kernel's own document, and whether this mode IS the one blueprint section
+ * 8 names as the un-downgraded process, "The current proven process is the
+ * definition of `full`. Downgrades are declared, never improvised."
+ *
+ * WHY THE NAME AND NOT THE SKIP COUNT (CR-002, round 9). This function used
+ * `mode.skips.length === 0` as its proxy for "this is the un-downgraded mode".
+ * The proxy held only because `full` happened to be the only mode with an empty
+ * list, nothing enforced that, and `skips[]` is shipped DATA. Two measured
+ * consequences, both at exit 0 with every registry gate green: giving `full` one
+ * bogus `skips[]` entry made this function say that no phase of the tiphys
+ * project had ever been delivered under `full`, which is false about the mode
+ * this project has delivered every phase under; and giving `direct-pr` an empty
+ * `skips[]` made a mode nobody has ever entered claim to be the one the project
+ * follows, with `merge-authority: owner` printed beneath it, which is not the
+ * regime in force (DR-0015). Blueprint section 8 defines `full` BY NAME, so the
+ * name is the primary fact and the skip count is a consequence of it.
+ *
+ * THE COUNT IS STILL REPORTED, as a fact about the mode rather than as the
+ * ground of the claim. That distinction is the whole finding: a number may be
+ * shown without being believed.
+ *
+ * WHAT MAKES THE `full` SENTENCE TRUE IS DATA, AND IT IS GUARDED IN TWO PLACES
+ * THAT COVER DIFFERENT DOCUMENTS. Keying off the name moves the burden: the
+ * claim is only as good as the `full` in the document being served genuinely
+ * being un-downgraded.
+ *
+ * The VALIDATOR carries it for EVERY document (round 10, CRB9-02).
+ * `mode-no-undeclared-downgrade` rejects a `skips[]` entry that the same mode's
+ * pipeline runs, and also one that the reference does not run; on the reference
+ * those two exhaust the cases, so a `full` declaring any skipped stage at all is
+ * refused and this sentence is never printed over it. Until that second part
+ * existed, a `full` whose stage had MOVED from `pipeline` into `skips` was an
+ * HONEST downgrade that validated at exit 0, and `tiphys mode show --mode full`
+ * printed this sentence about fifteen lines above a `skips: deploy-verify` row.
+ *
+ * A REGISTERED TEST carries it for THIS repository's own document, asserting the
+ * shipped `full` declares no skipped stage. It is kept rather than superseded:
+ * a test guards the document, the check guards every other document, and the
+ * failure this pair exists to prevent is a property asserted where it is stated
+ * and not enforced where it is consumed.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT SAY. It does not say that tiphys runs
+ * anything: nothing runs on tiphys before M4. The un-downgraded mode of the
+ * kernel's own document is the process the tiphys PROJECT follows for its own
+ * delivery; the downgraded ones have never been entered at all. And for a
+ * document that is not the kernel's own, the answer is that tiphys does not
+ * know, because it does not.
+ */
+export declare function executionStatus(mode: Mode, context: RenderContext): string;
+/**
+ * The standing limits of this release, printed on every invocation.
+ *
+ * IT SAYS ONLY WHAT THE SHIPPED SCHEMAS DO. The vocabularies really are closed
+ * enums, so "a document naming any other id is rejected" is the enum's own
+ * behaviour and not a claim about intent. The M4 sentence is attributed to
+ * DR-0020 rather than stated as a property of the code.
+ */
+export declare const RELEASE_LIMITS: string;
+/**
+ * Render one mode for a human or for a brief.
+ *
+ * THE SHAPE IS PART OF THE CONTRACT, because criterion 2 asserts over it: a
+ * section is a line ending in a colon at column zero, and its items are the
+ * lines indented by exactly two spaces beneath it. That makes "prints exactly
+ * the twelve stage ids in order" something a test can extract rather than
+ * something a reader has to eyeball.
+ */
+export declare function renderMode(mode: Mode, context: RenderContext): string[];