@tiphys/kernel 0.1.0 → 0.2.0

package/dist/src/commands/validate.js

@@ -96,6 +96,76 @@ export const TYPE_TABLE = new Map([
        `mechanism-rule-evidence-resolves` are registered for type `tuition` and
        nothing runs them until the type resolves. */
     ["tuition", "tuition.schema.json"],
+    /* M4-P25 criterion 4. The fleet's `cutover.json`. It carries NO `kind`
+       field, so this row extends `--type` and NOT `resolveAutoType`; `role-brief`
+       above is the standing precedent for that half of M3R-001, and the half the
+       rule is actually about, a schema that ships without a `--type` row and
+       forces a later implementer to edit an undeclared file, is satisfied here.
+       The document is validated programmatically on every write as well
+       (src/cutover.ts:253), which is what criterion 4 means by validated by the
+       schema rather than by the command. */
+    ["cutover-state", "cutover-state.schema.json"],
+    /* M4-P3 criterion 4. tasks/<id>/executor.json, the launch record an
+       ExecutorAdapter writes.
+  
+       THIS ROW IS THE WHOLE REGISTRATION, AND `resolveAutoType` IS NOT A SECOND
+       PLACE TO EDIT: that function answers `--type auto` by reading the
+       instance's `kind` and looking it up in THIS MAP, so a row added here is
+       the auto resolver's source of truth as well. M3R-001's requirement that a
+       shipped schema not arrive without its `--type` row is satisfied by the
+       row; nothing else in this module holds a type list.
+  
+       WHAT THE ROW CANNOT DO, stated here rather than left to be discovered.
+       An executor record carries no `kind` field, because M4-P3's criterion 6
+       fixes the record's fields and `kind` is not among them, so `--type auto`
+       on a real executor.json is a USAGE error naming the missing kind. That is
+       the `role-brief` situation above reached by a different route: there the
+       document cannot be decoded before the type is known, here the decoded
+       document does not say what it is. Both are types a caller must NAME. The
+       property is asserted by a registered test rather than trusted, so a later
+       phase that gives the record a `kind` reddens this comment instead of
+       leaving it stale. */
+    ["executor-record", "executor-record.schema.json"],
+    /* M4-P7 criterion 1. tasks/<id>/model-resolution.json, the record a harness
+       adapter writes at TURN END saying which tier was requested, which the
+       charter resolved, and which model family served the turn.
+  
+       ONE ROW SERVES BOTH REGISTRATIONS, which is the property the brief for
+       this phase asks to be got right and the row above states the mechanism
+       for: `resolveAutoType` answers `--type auto` by reading the instance's
+       `kind` and looking it up in THIS MAP. The difference from the executor
+       record is that a model-resolution record DOES carry a `kind`, required and
+       `const`, so `--type auto` resolves a real record rather than raising the
+       usage error the row above documents. `test/model-resolution.test.ts`
+       asserts both halves against the shipped CLI rather than against this
+       comment.
+  
+       THE DERIVED CHECKS COME WITH THE ROW AND ARE THE REASON IT MATTERS. The
+       schema is Kind A and reaches presence; `model-resolution-subject-echo` in
+       src/checks.ts is Kind B and reaches agreement between sibling fields, and
+       nothing runs it until the type resolves here. */
+    ["model-resolution", "model-resolution.schema.json"],
+    /* M4-P9 step 4. <fleet>/write-bypass.json, the infrastructure-hotfix bypass
+       the project-write block reads.
+  
+       THE ROW IS WHAT MAKES THE DECLARATION CHECKABLE BEFORE IT IS TRUSTED. The
+       hook reads the document defensively and refuses on anything it cannot use,
+       which is the right behaviour at decision time and a terrible way to find
+       out you mistyped an expiry: the orchestrator learns at the moment its own
+       hotfix is refused. With this row an author runs `tiphys validate --type
+       write-bypass <file>` and is told which pointer is wrong, before the
+       document is in front of a hook.
+  
+       A bypass declaration DOES carry a `kind`, required and `const`, so one row
+       serves `--type` and `resolveAutoType` together (M3R-001), unlike the
+       executor record above.
+  
+       WHAT THE ROW CANNOT DO, stated rather than left to be discovered: the
+       schema reaches the SHAPE and never the WINDOW. Whether `expiresAt` is in
+       the future is a comparison against a clock, and `decideWrite` takes `now`
+       as a parameter precisely so that comparison is testable at the boundary
+       rather than hidden inside a validator. */
+    ["write-bypass", "write-bypass.schema.json"],
 ]);
 /**
  * COMPANION SCHEMAS, declared beside the type table (M3-P4 step 3).

package/dist/src/cutover.d.ts

@@ -0,0 +1,584 @@
+/**
+ * Cutover state and rollback (kernel plan M4, M4-P26; D-19's second limb at
+ * delivery/plan/kernel-plan-v1.md:394).
+ *
+ * WHAT THIS MODULE IS. The freeze point is not one event. It is FIVE
+ * independently flippable switches, taken from the list the current delivery
+ * process retains at
+ * delivery/decisions/DR-0025-controlled-pre-m4-local-pilot.md:45 and read
+ * against DR-0036's authority condition. Five switches rather than one event
+ * is what makes rollback PARTIAL rather than all-or-nothing, and it is why
+ * `credentials-and-refs`, the one switch with owner latency, is separable
+ * from the four that are not.
+ *
+ * THE SPLIT THAT KEEPS THIS HONEST, and it runs through every function here.
+ * Rollback of the FILES is cheap: everything under the retirement roots is
+ * git-tracked and revertible from history. Rollback of AUTHORITY is the
+ * expensive half: the branch-protection ruleset is owner-configured, the
+ * orchestrator cannot change it, and
+ * delivery/decisions/DR-0036-the-harness-adapter-leads-m4-and-the-kernel-is-the-second-subject.md:15
+ * prices the revert at "whatever phases ran under it". Nothing in this module
+ * flips authority. It PREPARES the request an owner acts on, and it refuses
+ * loudly rather than pretending the preparation is the act.
+ *
+ * WHAT THIS MODULE DELIBERATELY DOES NOT DO. It does not print
+ * `tiphys cutover status`, does not write switches to `kernel`, and does not
+ * ship a state schema. Those are M4-P25's acceptance criteria and M4-P25's
+ * files. This phase was dispatched ahead of its stated dependency because the
+ * conflict pre-pass holds `src/commands/cutover.ts` for exactly one unit at a
+ * time, so the state MODEL is created here and the status SURFACE is left
+ * where the plan put it. The boundary is recorded in
+ * delivery/work-history/m4-p26.md:1 rather than left to be discovered.
+ *
+ * PLAN CONSTRAINTS. C-1: current state comes from `cutover.json` and from
+ * meta.json plus the turn-end file, never from the tail of a log. C-2: no pid,
+ * no signal, no /proc and no process probing appears here; a live worktree is
+ * a DIRECTORY and an open task is a FILE STATE. C-3: nothing is backgrounded.
+ */
+import type { Fleet } from "./fleet.ts";
+import { type GuardResult } from "./task.ts";
+import type { SchemaDocument } from "./validate.ts";
+/**
+ * The five retained items of DR-0025, in the order section 4.3 of the M4
+ * plan tabulates them. This list is CLOSED. A sixth name is a plan revision,
+ * not a code edit, because every rollback trigger enumerates it.
+ */
+export declare const CUTOVER_SWITCHES: readonly ["planning-and-scope", "review-and-arbitration", "credentials-and-refs", "salvage-and-recovery", "closeout"];
+export type CutoverSwitchName = (typeof CUTOVER_SWITCHES)[number];
+/** Which process holds the authority a switch governs. */
+export type SwitchState = "current" | "kernel";
+export declare const SWITCH_STATES: readonly SwitchState[];
+/**
+ * The switch with owner latency. Named as a constant because three separate
+ * places have to treat it differently and a repeated string literal is how
+ * one of them ends up not doing so.
+ */
+export declare const OWNER_LATENCY_SWITCH: CutoverSwitchName;
+/**
+ * One switch's record. `restoreTo` is the value the switch held BEFORE the
+ * flip. It is what makes freeze-point restore a matter of reading a recorded
+ * value rather than reconstructing an intent, and a record without it cannot
+ * be rolled back at all, which is why every read here refuses one.
+ */
+export interface SwitchRecord {
+    state: SwitchState;
+    flippedAt: string;
+    flippedBy: string;
+    reason: string;
+    restoreTo: SwitchState;
+}
+export interface CutoverState {
+    switches: Record<CutoverSwitchName, SwitchRecord>;
+}
+/**
+ * `cutover.json` sits at the FLEET ROOT and not under `state/`, because
+ * `state/` is gitignored (src/fleet.ts:29) and trigger 2 step 1 identifies a
+ * flip with `git log` over this exact path. A switch history that is not
+ * committed is not a history.
+ */
+export declare function cutoverStatePath(fleet: Fleet): string;
+/**
+ * The document as it was parsed, keys and all. It is carried beside the typed
+ * state because the typed view is NARROWER than the file: `CutoverState` names
+ * `switches` and nothing else, so a writer that serialises the typed view
+ * DELETES every other key the file held. A rollback is a change to the
+ * switches, not a rewrite of the document, and this is what lets the two be
+ * different sizes.
+ */
+export type CutoverDocument = Record<string, unknown>;
+export type CutoverRead = {
+    kind: "read";
+    state: CutoverState;
+    document: CutoverDocument;
+} | {
+    kind: "absent";
+} | {
+    kind: "refused";
+    reason: string;
+};
+/**
+ * Validate a parsed document into a CutoverState, returning every reason at
+ * once rather than the first.
+ *
+ * FAIL CLOSED ON `restoreTo`. A record missing it, or carrying it as a word
+ * outside the two-value vocabulary, is REFUSED rather than defaulted to
+ * `current`. Defaulting would make rollback silently guess, and a guess that
+ * happens to be right most of the time is the guard that cannot go red.
+ */
+export declare function validateCutoverDocument(document: unknown): string[];
+/** Read and validate the fleet's cutover state. */
+export declare function readCutoverState(fleet: Fleet): CutoverRead;
+export declare function renderCutoverState(state: CutoverState | CutoverDocument): string;
+/**
+ * Put a new switch table into the document the file actually held, leaving
+ * every other key exactly as it was read.
+ *
+ * WHY THIS EXISTS AS A NAMED FUNCTION. `validateCutoverDocument` refuses an
+ * unknown SWITCH NAME because the five are a closed list, and that made it
+ * look as though the whole document were closed. It is not: M4-P25 owns the
+ * schema and may add top-level keys, so a rollback that serialises only what
+ * this module's interface names would silently delete them. Refusing them
+ * instead would be this phase deciding M4-P25's schema, which is not its to
+ * decide, so the document is CARRIED rather than narrowed or refused.
+ */
+export declare function withSwitches(document: CutoverDocument, switches: Record<CutoverSwitchName, SwitchRecord>): CutoverDocument;
+/**
+ * Publish a whole cutover state ATOMICALLY: serialise everything, write it to
+ * a sibling temporary file, fsync that file, then rename over the
+ * destination. Nothing partial is ever visible at the destination path,
+ * because rename(2) within one directory is atomic.
+ *
+ * THE MECHANISM THIS EXISTS AGAINST is not "a crash". It is WRITING STATE
+ * PER ITEM WHILE ITERATING, which leaves a file that is internally valid and
+ * factually wrong: three switches saying `kernel` and two saying `current`
+ * describes a process that has no owner for three of its five authorities.
+ * Every caller in this module builds the complete next state first and calls
+ * this once.
+ */
+export declare function publishCutoverState(path: string, state: CutoverState | CutoverDocument): void;
+export interface SwitchChange {
+    name: CutoverSwitchName;
+    from: SwitchState;
+    to: SwitchState;
+}
+export interface RollbackPlan {
+    changes: SwitchChange[];
+    next: CutoverState;
+}
+/**
+ * Observer called once per switch as the next state is assembled IN MEMORY,
+ * before anything reaches disk. It exists so a caller can report progress,
+ * and it is also the seam criterion 2's red witness uses: an observer that
+ * throws on the third call aborts the assembly, and the destination file must
+ * still hold the five values it held before.
+ */
+export type SwitchObserver = (change: SwitchChange, index: number) => void;
+export interface RollbackOptions {
+    now: string;
+    by: string;
+    reason: string;
+    onSwitch?: SwitchObserver;
+}
+export type RollbackTrigger = "drain-reversal" | "freeze-point-restore" | "retirement-unmet";
+export declare const ROLLBACK_TRIGGERS: readonly RollbackTrigger[];
+/**
+ * The target value a trigger moves a switch to.
+ *
+ * Trigger 1 (drain reversal) hands every authority back to the current
+ * process, so the target is `current` for all five: in-flight work has to be
+ * handled by the process that started it.
+ *
+ * Trigger 2 (freeze-point restore) reads each switch's own `restoreTo`. That
+ * is the difference between the two, and it is why M4-P25 criterion 4 refuses
+ * a write that omits the field.
+ *
+ * ROLLBACK IS MONOTONE AND THE CLAMP BELOW IS WHAT MAKES THE MODULE HEADER
+ * TRUE. `restoreTo` is the value a switch held BEFORE its last flip, and
+ * `planRollback` sets it to the value the switch is leaving. So a switch that
+ * has already been rolled back to `current` carries `restoreTo: "kernel"`, and
+ * returning that value would move the switch FORWARD on the second run of the
+ * same command. The failure arm of trigger 1 step 1 exits nonzero after the
+ * local write has already happened, and the natural response to that is to run
+ * the command again, so the second run is not a hypothetical. A rollback never
+ * hands authority to the kernel: `current` is a floor, and a switch already at
+ * it is a no-op rather than a flip.
+ */
+export declare function targetFor(trigger: RollbackTrigger, record: SwitchRecord): SwitchState;
+/**
+ * Assemble the complete next state. Throws rather than returning a partial
+ * plan, and touches no file at all: publishing is a separate call.
+ */
+export declare function planRollback(state: CutoverState, trigger: RollbackTrigger, options: RollbackOptions): RollbackPlan;
+export type RollbackOutcome = {
+    ok: true;
+    changes: SwitchChange[];
+    next: CutoverState;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Plan and publish in one call: validate the whole input, assemble the whole
+ * next state, then write once.
+ *
+ * ORDER IS THE PROPERTY. Every refusal reachable from a bad input happens
+ * before `publishCutoverState` is called, so a refusal leaves the file
+ * byte-identical. That is asserted directly rather than trusted: see
+ * test/cutover.test.ts.
+ */
+export declare function applyRollback(fleet: Fleet, trigger: RollbackTrigger, options: RollbackOptions): RollbackOutcome;
+/**
+ * `unexaminable` is a THIRD kind and not an error channel. A drain predicate
+ * that cannot decide an entry has not found it clean, and folding the
+ * undecidable into "nothing here" is how a guard reads quiet at full speed.
+ */
+export type InFlightKind = "worktree" | "task" | "unexaminable";
+export interface InFlightItem {
+    kind: InFlightKind;
+    id: string;
+    detail: string;
+}
+/**
+ * WHAT DRAIN COUNTS, and the omission is the decision.
+ *
+ * In-flight work only: live worktrees and open tasks with no turn-end. Pushed
+ * unmerged BRANCHES are deliberately NOT counted (M4-D-15, decided at
+ * delivery/plan/kernel-plan-m4.md:3279). This container cannot delete a remote
+ * ref and the delete dry run exits 0 either way, and the probes generalised
+ * that further: a dry run does not probe push authorization at all
+ * (delivery/verification/m4-prototype-probes.md:165). A drain predicate over
+ * branches therefore blocks cutover on an owner action with no local
+ * pre-check, which is a predicate that can never read clean.
+ *
+ * C-2 is load-bearing here. A live worktree is a DIRECTORY on disk and an
+ * open task is meta.json's status plus the absence of the turn-end file. No
+ * process is probed, no pid is read, and nothing asks whether an agent is
+ * still breathing.
+ */
+export declare function inFlightItems(fleet: Fleet): InFlightItem[];
+/**
+ * The named list of things no local command can see. It is printed with every
+ * drain report and is NOT abbreviated when the network is unreachable: a
+ * command that silently degrades to a shorter answer is indistinguishable
+ * from one reporting a quiet system, which is the shape standing warning 6
+ * records for watchers.
+ */
+export declare const CANNOT_SEE: readonly string[];
+export interface CommandResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+}
+export declare function runGit(cwd: string, args: string[]): CommandResult;
+/**
+ * Commit and push the fleet's rolled-back state.
+ *
+ * THE FAILURE ARM IS WRITTEN FIRST, and that ordering is the point rather
+ * than a style. A rollback that changes `cutover.json` locally and does not
+ * land it leaves every other environment believing the switches are still
+ * `kernel`, and a push whose failure is swallowed is indistinguishable from a
+ * push that worked. Every arm below returns a reason; none returns silence.
+ *
+ * A fleet with no remote is a REFUSAL, not a skip. The caller may pass
+ * `allowNoRemote` to turn it into a reported, non-fatal condition, and when it
+ * does the reason is still printed, so a reader can never mistake the local
+ * write for a published one.
+ *
+ * THE COMMIT CARRIES THE NAMED PATHS AND NOTHING ELSE. Staging everything at
+ * the fleet root stages whatever is dirty anywhere under it, and the
+ * precondition of trigger 1 is that IN-FLIGHT WORK EXISTS: a half-written
+ * note, a torn meta.json, an operator scratch file. Committing all of it under
+ * the message "cutover rollback" publishes somebody else's unfinished work
+ * under this command's name, which is a write whose scope is wider than the
+ * sentence describing it. Three checks make the scope exactly the named set:
+ * the index must be empty before, the staging names paths, and the staged set
+ * is compared with the requested one afterwards.
+ */
+export type SyncOutcome = {
+    ok: true;
+    pushed: true;
+    head: string;
+    staged: string[];
+} | {
+    ok: true;
+    pushed: false;
+    reason: string;
+    staged: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function syncFleetState(fleetRoot: string, options: {
+    allowNoRemote?: boolean;
+    message: string;
+    paths: string[];
+}): SyncOutcome;
+/**
+ * Refuse to touch a tree that holds uncommitted work.
+ *
+ * ANY `git checkout --` in such a tree is destructive, INCLUDING when it names
+ * a single path, and especially the path being edited. This repository has
+ * paid for that twice; the rule is standing warning 8 in the agent-rules file.
+ * The guard is a precondition of the restore and not a warning printed beside
+ * it, because a warning is advice and this is the only thing standing between
+ * a rollback and four rounds of somebody's uncommitted work.
+ */
+export declare function refuseIfTreeDirty(repoRoot: string): GuardResult;
+export type RestoreFilesOutcome = {
+    ok: true;
+    roots: string[];
+    removed: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Restore the named retirement roots from a pre-freeze sha.
+ *
+ * The dirty check runs FIRST and returns before any version-control
+ * invocation that can write. That order is the whole guarantee, and the test
+ * asserts the dirty file is byte-identical afterwards rather than asserting
+ * the exit code alone.
+ *
+ * "RESTORE" IS A CLAIM ABOUT THE WHOLE ROOT, AND CHECKING A TREE OUT OVER A
+ * PATH IS NOT ONE. `checkout <sha> -- <root>` writes what the sha held and
+ * removes NOTHING, so every file added under the root after the freeze
+ * survives the restore untouched. The result is a hybrid tree that the caller
+ * prints `RESTORED` over: a verdict wider than the operation that produced it.
+ * The post-freeze additions are therefore enumerated and removed, and then the
+ * root is COMPARED with the sha. The comparison is the verdict; without it the
+ * success arm is an assumption, and a success arm that cannot fail is the
+ * guard that cannot go red.
+ */
+export declare function restoreRetirementRoots(repoRoot: string, sha: string, roots: string[]): RestoreFilesOutcome;
+/**
+ * The property that makes trigger 2 step 3 unrehearsable, in one sentence,
+ * exported so the document, the command and the rehearsal script all print
+ * the SAME sentence and cannot drift apart.
+ */
+export declare const UNREHEARSABLE_REASON: string;
+export type RestoreRequestOutcome = {
+    ok: true;
+    text: string;
+    fields: number;
+} | {
+    ok: false;
+    reasons: string[];
+};
+/**
+ * Generate the owner request for trigger 2 step 3.
+ *
+ * TWO STRUCTURALLY DIFFERENT REFUSALS, and the second is the one a field
+ * check is green on. An ABSENT key is caught by asking whether the key is
+ * there. A key that is PRESENT and EMPTY passes that question and produces a
+ * request with a blank where a pre-flip value belongs, which the owner would
+ * have to fill in from memory. Both are refused, and the refusal names the
+ * field, because an owner request with a hole in it is worse than no request:
+ * it looks complete.
+ */
+export declare function generateRestoreRequest(document: unknown): RestoreRequestOutcome;
+export type Disposition = "PORT" | "DELETE" | "KEEP";
+export interface RetirementRow {
+    id: string;
+    disposition: Disposition;
+    /** For PORT: the kernel artifact the rule moves to, relative to the repo. */
+    destination?: string;
+    /**
+     * For PORT: a command that was RED under the OLD rule. Retirement is
+     * refused until it is red under the NEW artifact too. This is what turns
+     * "PORT, verify not weaker" from a judgment into a command.
+     */
+    negativeWitness?: string[];
+    /**
+     * The exit status the row RECORDED for its negative witness, when it
+     * records one. Present, it is required to match: see `evaluatePortRow`.
+     */
+    expectedWitnessExit?: number;
+}
+export type PortVerdict = "ported" | "unported";
+export interface PortResult {
+    id: string;
+    verdict: PortVerdict;
+    reason: string;
+}
+/**
+ * Decide one PORT row.
+ *
+ * `ported` needs BOTH halves and the second is the one that matters. A verdict
+ * derived only from the destination file existing is the vacuous version: a
+ * file can exist and say nothing. The negative witness was RED under the old
+ * rule, so a witness that exits 0 under the new artifact means the new
+ * artifact does not catch what the old one caught, which is precisely
+ * "WEAKER". Exit 0 from the witness is therefore `unported`, not a pass.
+ *
+ * `ported` IS REACHED FROM A POSITIVE TEST AND NEVER FROM A FALLTHROUGH, and
+ * that is what the first three checks below are. `readRetirementInventory`
+ * casts whatever the fixture's `rows` array holds, so a row may be a string, a
+ * number, or an object whose `disposition` is misspelt; the earlier form asked
+ * only whether the disposition was NOT the word `PORT`, so every one of those
+ * returned `ported`, which is a verdict of "this retirement is complete" over
+ * a row nobody could read. The vocabulary is closed, so a value outside it is
+ * `unported` and names itself.
+ */
+export declare const DISPOSITIONS: readonly Disposition[];
+export declare function evaluatePortRow(row: RetirementRow, repoRoot: string): PortResult;
+export type InventoryRead = {
+    kind: "read";
+    rows: RetirementRow[];
+} | {
+    kind: "absent";
+} | {
+    kind: "refused";
+    reason: string;
+};
+/**
+ * Read an M4-P23 retirement inventory. The path is a parameter because that
+ * phase runs concurrently with this one and its file does not exist on this
+ * branch; the rehearsal supplies a fixture.
+ */
+export declare function readRetirementInventory(path: string): InventoryRead;
+/** The shipped schema document's basename, in the package's `schemas/`. */
+export declare const CUTOVER_STATE_SCHEMA_FILENAME = "cutover-state.schema.json";
+/**
+ * Absolute path of the shipped cutover-state schema.
+ *
+ * `packageRoot()` walks UP and TESTS rather than counting `..`, because the
+ * depth differs between running from `src/` and running from `dist/src/`
+ * (src/modes.ts:39 states the same reason for the same walk).
+ */
+export declare function cutoverStateSchemaPath(): string;
+/** The shipped schema document, read once. */
+export declare function cutoverStateSchema(): SchemaDocument;
+/**
+ * Validate a whole cutover document against the SHIPPED SCHEMA.
+ *
+ * WHY THIS IS NOT `validateCutoverDocument`, and the two are kept apart on
+ * purpose. That function is this module's READ guard and answers "can this
+ * file be interpreted". This one is the WRITE guard and answers "is this
+ * document one the package is prepared to ship", and criterion 4 says the
+ * required-field rule is validated BY THE SCHEMA rather than by a command.
+ * A check implemented only in a command is one the schema cannot enforce for
+ * a later writer, and a later writer is precisely who rollback depends on:
+ * M4-P26's `targetFor` READS the recorded `restoreTo` (src/cutover.ts:352)
+ * rather than remembering an intent, so a record written without one is a
+ * switch that can never be rolled back.
+ */
+export declare function cutoverSchemaDiagnostics(document: unknown): string[];
+/**
+ * The captured pre-freeze state, relative to the REPOSITORY root. It carries
+ * the branch-protection ruleset as it was before the first flip, so the
+ * restore request M4-P26 generates has an input rather than a memory. T-025
+ * is why: the one step that cannot be rehearsed is the one that failed, and
+ * its INPUT can be captured in advance even when its EXECUTION cannot.
+ */
+export declare const PRE_FREEZE_RULESET_PATH = "delivery/plan/cutover/pre-freeze-ruleset.json";
+export type PreFreezeVerdict = 
+/** No switch reads `kernel`, so nothing has been frozen and nothing is owed. */
+{
+    kind: "not-required";
+} | {
+    kind: "satisfied";
+    capturedAt: string;
+} | {
+    kind: "refused";
+    arm: "absent" | "stale" | "unreadable";
+    reason: string;
+};
+/**
+ * THE CAPTURE TIME IS READ FROM THE DOCUMENT, NOT FROM ITS MTIME, and that is
+ * a correction rather than a preference.
+ *
+ * The criterion says the capture must not be OLDER than the most recent switch
+ * write. An mtime does not survive the journey: `git clone` and `git checkout`
+ * set every working-tree mtime to the moment of the checkout, so a capture
+ * taken weeks before a flip reads as newer than the flip on any fresh clone,
+ * and the guard reports satisfied on exactly the machine a reviewer uses.
+ * Measured, and the measurement is in the work history. So the document
+ * records `captured-at` and the comparison is content to content.
+ *
+ * FAIL CLOSED ON AN UNREADABLE CAPTURE. A document with no `captured-at`, or
+ * one that does not parse as an instant, is `unreadable` and refuses. Treating
+ * it as satisfied would make a malformed capture indistinguishable from a good
+ * one, which is the guard that cannot go red.
+ */
+export declare function preFreezeGuard(repoRoot: string, state: CutoverState): PreFreezeVerdict;
+export type BranchCount = {
+    kind: "counted";
+    count: number;
+    branches: string[];
+} | {
+    kind: "unexaminable";
+    reason: string;
+};
+/**
+ * Count the PUSHED, UNMERGED branches, and print them nowhere near the drain
+ * verdict.
+ *
+ * THIS NUMBER DOES NOT FEED THE PREDICATE, AND THAT IS THE DECISION (M4-D-15,
+ * delivery/plan/kernel-plan-m4.md:3279). Remote ref deletion is refused in
+ * this container, and `git push --dry-run` does not probe push authorization
+ * at all, in either direction, for any ref namespace
+ * (delivery/verification/m4-prototype-probes.md:165). A drain defined as "no
+ * unmerged branches" therefore waits forever on an owner action that has no
+ * local pre-check, which is a predicate that can never read clean. It is
+ * reported because an operator wants to see it, and it is reported on its own
+ * line so that no reader can mistake it for a reason the cutover is blocked.
+ *
+ * `unexaminable` is a THIRD answer for the same reason it is one in
+ * `inFlightItems`: a repository with no `origin/<default>` cannot be asked
+ * this question, and printing `0` there would be an answer nobody measured.
+ */
+export declare function unmergedBranchCount(repoRoot: string, upstream?: string): BranchCount;
+/** The M4-P23 inventory, relative to the REPOSITORY root. */
+export declare const RETIREMENT_INVENTORY_PATH = "delivery/plan/cutover/retirement-inventory.json";
+/**
+ * The first tokens a retirement row's command may start a segment with.
+ *
+ * MIRRORED FROM `scripts/check-retirement-inventory.mjs`, DELIBERATELY, AND
+ * THE DRIFT IS ASSERTED BY A TEST rather than by this comment. The script is
+ * this project's own predicate and is KEPT rather than shipped (DR-0029), so
+ * the kernel cannot import it; but the two lists screening the same rows must
+ * not diverge, so `test/cutover.test.ts` reads the script's
+ * `ALLOWED_FIRST_TOKENS` and requires this set to be no wider.
+ *
+ * WHAT THE LIST BUYS AND WHAT IT DOES NOT. Every tool on it is one with no
+ * option for writing a file, so a row cannot modify the tree this command is
+ * auditing. It is a TOOL allowlist, not a sandbox: the child still runs with
+ * this process's privileges and can read anything this process can read.
+ */
+export declare const RETIREMENT_COMMAND_TOKENS: ReadonlySet<string>;
+/**
+ * Screen one inventory command. The rows are DATA FROM A FILE, so the command
+ * is screened before anything spawns it, and the check is on the EXECUTABLE
+ * POSITION of every segment rather than on the whole string: a whole-string
+ * denylist refuses `grep -c 'npm ci' gate-registry.yaml`, which runs no npm at
+ * all and merely searches for those characters.
+ */
+export declare function screenRetirementCommand(command: unknown): string[];
+export type RowAdaptation = {
+    kind: "row";
+    row: RetirementRow;
+} | {
+    kind: "refused";
+    result: PortResult;
+};
+/**
+ * Turn one row of the SHIPPED inventory into the shape `evaluatePortRow`
+ * takes.
+ *
+ * THIS ADAPTER EXISTS BECAUSE THE TWO SHAPES REALLY ARE DIFFERENT, and the
+ * difference is silent in the dangerous direction. `RetirementRow` declares
+ * `negativeWitness` as an argv ARRAY (src/cutover.ts:1128), and the M4-P23
+ * inventory writes `negative-witness` as an OBJECT carrying a SHELL STRING
+ * (delivery/plan/cutover/retirement-inventory.json:1). Handing the shipped
+ * document straight to `evaluatePortRow` therefore returns `unported` with
+ * "PORT row carries no negative-witness command" for every row in it: a
+ * verdict that looks like a finding about the kernel and is a finding about a
+ * key spelling. The adapter is named, tested and refuses rather than
+ * defaulting, so the mismatch cannot come back as a silent all-red.
+ */
+export declare function retirementRowFromDocument(raw: unknown): RowAdaptation;
+export interface RetirementReport {
+    results: PortResult[];
+    unported: number;
+}
+export type RetirementRead = {
+    kind: "read";
+    report: RetirementReport;
+} | {
+    kind: "refused";
+    reason: string;
+};
+/**
+ * Evaluate every PORT row of the inventory.
+ *
+ * THE VACUOUS VERDICT IS THE ONE THIS GUARDS AGAINST. `ported` is not "the
+ * named kernel artifact exists"; a file can exist and say nothing. Both halves
+ * are required and the second is the one that matters: the row's negative
+ * witness was RED against a subject that does not carry the rule, so a witness
+ * exiting 0 means the probe discriminates nothing and the row is `unported`.
+ * That derivation is M4-P26's `evaluatePortRow` and is REUSED here rather than
+ * reimplemented; this function supplies the reading, the adaptation and the
+ * screen.
+ */
+export declare function evaluateRetirementInventory(inventoryPath: string, repoRoot: string): RetirementRead;