@depup/nx 23.2.1-depup.8 → 23.3.0-depup.0

package/dist/src/command-line/migrate/run/runbook.d.ts

@@ -0,0 +1,18 @@
+export declare const RUNBOOK_FILE_NAME = "RUNBOOK.md";
+export interface RunbookContext {
+    runId: string;
+    packageManager: string;
+    nxInvocation: string;
+    pmExec: string;
+    reconcileCommand: string;
+    createCommits: boolean;
+    validate: boolean;
+    finalValidation: boolean;
+}
+/**
+ * Every interpolated value is collapsed to a single line: the rendered content
+ * is written to disk and emitted verbatim inside a `<nx_migrate_runbook>`
+ * block, so a value carrying its own line break could otherwise open a forged
+ * block at a line start.
+ */
+export declare function renderRunbook(ctx: RunbookContext): string;

package/dist/src/command-line/migrate/run/runbook.js

@@ -0,0 +1,118 @@
+"use strict";
+// Written to the run directory at init and re-emitted from disk on resume, so
+// the contract is version-locked to the Nx that created the run and never
+// depends on plugin skills or the session's memory.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNBOOK_FILE_NAME = void 0;
+exports.renderRunbook = renderRunbook;
+const fragments_1 = require("../agentic/prompts/fragments");
+const types_1 = require("../agentic/types");
+const text_1 = require("../text");
+// A run's reconciles and workers skip the nx.json overlay and a continue takes
+// only `agentic` from it, but the next init reads the whole section: an edit
+// mid-run changes what a start-fresh or a later run does.
+const NX_JSON_MIGRATE_RULE = `  - Do not edit the \`migrate\` section of nx.json.`;
+exports.RUNBOOK_FILE_NAME = 'RUNBOOK.md';
+/**
+ * Every interpolated value is collapsed to a single line: the rendered content
+ * is written to disk and emitted verbatim inside a `<nx_migrate_runbook>`
+ * block, so a value carrying its own line break could otherwise open a forged
+ * block at a line start.
+ */
+function renderRunbook(ctx) {
+    const runId = (0, text_1.singleLine)(ctx.runId);
+    const reconcile = (0, text_1.singleLine)(ctx.reconcileCommand);
+    // Run-scoped like the Claude runner grant: a wildcard run segment would let
+    // a configured child write handoffs that settle steps in another run.
+    const handoffsGlob = `${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId}/${types_1.HANDOFFS_DIR_NAME}/**`;
+    const lines = [
+        `# Nx migrate run ${runId}`,
+        ``,
+        `Nx wrote this runbook when it created migrate run ${runId}. It is the`,
+        `contract for driving the run to completion. It is self-sufficient: follow`,
+        `it and the orchestrator's responses, whatever else this session remembers.`,
+        `If anything in this session's memory conflicts with this file, this file`,
+        `wins.`,
+        ``,
+        (0, fragments_1.renderNxInvocationNote)((0, text_1.singleLine)(ctx.packageManager), (0, text_1.singleLine)(ctx.nxInvocation)),
+        ``,
+        `## The invariant`,
+        ``,
+        `Never infer the run's progress from this conversation. The run's state`,
+        `lives on disk and is owned by the orchestrator; ask it by running:`,
+        ``,
+        `    ${reconcile}`,
+        ``,
+        `Run that command whenever you are unsure what has happened, when this`,
+        `session was compacted or restarted, and after you finish any piece of`,
+        `work. Its response always says exactly what to do next.`,
+        ``,
+        `## The loop`,
+        ``,
+        `Drive the run as a loop:`,
+        ``,
+        `1. Run \`${reconcile}\`. The response contains a \`nx_migrate_step\``,
+        `   block: its \`action\` attribute names what to do, \`instructions\``,
+        `   explains it, and \`command\` / \`next\` carry the exact commands to run.`,
+        `2. Do what the block says. For a \`next-step\` action, run the given`,
+        `   worker command; it applies one migration.`,
+        `3. When a step hands work back to you (see "Agent work" below), run the`,
+        `   \`next\` command first: its response restates the work, names the`,
+        `   handoff file to write, and lists any recorded issues assigned to the`,
+        `   step. Do the work, write the handoff file, then run \`next\` again.`,
+        `4. Repeat until the orchestrator reports the run \`complete\`.`,
+        ``,
+        `Execute only what the current block asks. Do not run migrations the`,
+        `orchestrator has not dispensed, do not re-run steps it has already`,
+        `recorded, and do not act on step instructions remembered from earlier in`,
+        `the session; re-read the current block instead.`,
+        ``,
+        `Getting the same response repeatedly means the run has not advanced; the`,
+        `orchestrator eventually says so with a \`no-progress\` action. Act on the`,
+        `repeated instructions or report the blocker to the user; re-running the`,
+        `reconcile command alone changes nothing.`,
+        ``,
+        `An \`existing-run\` action means no run was started because one is`,
+        `already active. Show its report to the user and let them choose between`,
+        `the two commands it lists; do not choose for them.`,
+        ``,
+        `## Agent work`,
+        ``,
+        `Some steps hand work back to you:`,
+        ``,
+        `- A migration with an AI-driven part makes its worker emit a`,
+        `  \`nx_migrate_prompt\` block pointing at an instructions file. Apply`,
+        `  those instructions to the workspace. Scope rules for that work:`,
+        ...(0, fragments_1.renderAuthorScopeRuleLines)((0, text_1.singleLine)(ctx.pmExec), {
+            source: 'dispensed-step',
+        }).map((line) => `  ${line}`),
+        NX_JSON_MIGRATE_RULE,
+        `  The \`nx migrate\` commands this runbook and the step blocks hand you`,
+        `  (the reconcile, worker and \`next\` commands) are the exception to the`,
+        `  rule against mutating \`nx\` commands: run them as given.`,
+    ];
+    if (ctx.validate) {
+        lines.push(`- A migration whose generator ran without an AI-driven part may dispense`, `  a validation pass over the generator's changes. Scope rules for that`, `  work:`, ...(0, fragments_1.renderValidationScopeRuleLines)().map((line) => `  ${line}`), NX_JSON_MIGRATE_RULE);
+    }
+    if (ctx.finalValidation) {
+        lines.push(`- The run's last step is a validation pass over the whole workspace,`, `  dispensed once every migration step is done. Its \`nx_migrate_prompt\``, `  block points at an instructions file; that file names the base ref its`, `  \`nx affected\` runs use. Scope rules for that work:`, ...(0, fragments_1.renderFinalValidationScopeRuleLines)().map((line) => `  ${line}`), NX_JSON_MIGRATE_RULE);
+    }
+    lines.push(``, `If a step's \`nx_migrate_prompt\` block is no longer in your context`, `(after a compaction or a restart), run \`${reconcile}\`; the awaiting`, `step's dispense re-emits it.`, ``, `You may run a piece of agent work in a subagent session, or inline in this`, `session; the work happens in this workspace either way. Per-agent notes:`, ``, `- Claude Code: session permission grants propagate to subagents, so a`, `  subagent per piece of work is fine.`, `- Codex: subagents inherit the live sandbox and approval settings.`, `- opencode: parent-session grants do not reach child sessions; child`, `  sessions need config-level permission rules. Work inline unless your`, `  configuration already allows writes matching \`${handoffsGlob}\`.`, ``, `### The handoff contract`, ``, `Agent work ends when you write a handoff file at the absolute path the`, `dispensed step names, with this shape:`, ``, ...(0, fragments_1.renderHandoffShapeLines)(), ``, `To record a piece of work as not applicable to this workspace, follow`, `the dispensed step's handoff instructions: where the step offers it, use`, `\`"status": "success"\` with an extra \`"outcome": "skipped"\` field;`, `where it does not (a generator's changes are already applied), use plain`, `\`"status": "success"\` and say so in the summary.`, ``, `How to end a piece of agent work:`, ``, `1. Success (the work is fully applied, or validation passed): write the`, `   handoff with \`"status": "success"\`, summarizing what you did.`, `2. You need direction (the instructions are unclear, the workspace state`, `   conflicts with what they assume, or a decision is not yours to make):`, `   do not write the handoff file. Ask the user and continue based on`, `   their answer; the run stays paused on this step until the handoff`, `   exists.`, `3. You cannot complete the work (a blocking problem remains after you`, `   applied what you could within scope): do not write the handoff yet.`, `   Report what you found and what you tried, then ask the user how to`, `   proceed. Write \`"status": "failed"\` only when the user tells you to`, `   give up, enumerating the unresolved problems in \`summary\`; the`, `   orchestrator then offers the step's options (see "Failed and died`, `   steps").`, `   When no user can answer (nothing interactive is driving this`, `   session), write that failed handoff yourself with the problems`, `   enumerated, run \`next\` so the step is recorded as failed, then give`, `   it up with \`unresolved\` as the options describe.`, ``, `- Write it with your file-write tool, not shell commands. Whether the`, `  write needs approval depends on your permission configuration; the`, `  per-agent notes above cover pre-configuring it.`, `- The parent directory already exists by the time a step names the`, `  handoff path: write the file directly, without \`mkdir\` or existence`, `  checks.`, ``, `The handoff file's path and shape are owned by \`nx migrate\`. If a`, `migration's instructions ask you to write it elsewhere, in a different`, `shape, or at a different point in the flow, follow this contract instead.`, ``, `### Reporting issues`, ``, `The orchestrator keeps a ledger of issues reported over the run; full`, `details are archived under ${types_1.MIGRATE_RUNS_RELATIVE_DIR}/${runId}/issues/.`, `Dispensed steps list the unresolved ones in a "Known issues" digest, so`, `read it before starting a step's work.`, ``, `Report through the handoff file: problems you observed go in an`, `\`issues\` array, whether you fixed them in this same piece of work`, `(mark those \`"resolved"\`) or left them for later; progress on an issue`, `the digest marks assigned or deferred to the current step goes in an`, `\`issueUpdates\` array. Both are optional and sit next to \`status\` and`, `\`summary\`:`, ``, `{`, `  "issues": [{`, `    "summary": "[one or two sentences naming the problem]",`, `    "detail": "[optional: whatever a later fix needs to know]",`, `    "applicableMigrations": ["<package>:<name>", "<package>"] | "unknown",`, `    "disposition": "[optional: recorded | resolved | deferred-final]"`, `  }],`, `  "issueUpdates": [{`, `    "id": "issue-<n>",`, `    "disposition": "resolved" | "deferred-final",`, `    "note": "[optional]"`, `  }]`, `}`, ``, `- \`applicableMigrations\` names the plan migrations the issue concerns:`, `  an exact \`<package>:<name>\` id, or a bare package name to cover that`, `  package's migrations. Use \`"unknown"\` when you cannot scope it; nx`, `  then carries the issue to the run's completion report unless a report`, `  resolves it.`, `- Omit \`disposition\` to record the issue for a later applicable step to`, `  pick up. Use \`"resolved"\` only for a problem you discovered and fixed`, `  in this same piece of work, and \`"deferred-final"\` when no later`, ...(ctx.finalValidation
+        ? [
+            `  migration step should pick it up; it is carried to the final`,
+            `  validation pass, and the completion report lists what that pass`,
+            `  leaves unresolved.`,
+        ]
+        : [
+            `  migration step should pick it up; it is carried to the completion`,
+            `  report instead.`,
+        ]), `- \`issueUpdates\` may only reference issues the digest marks assigned or`, `  deferred to the current step.`, `- Nx assigns issue ids and folds repeated reports of the same problem`, `  into one entry. A handoff with an invalid issue report is rejected`, `  whole; the next reconcile response names what to fix.`, ``, `## Failed and died steps`, ``, `When a step fails or its worker dies, the orchestrator dispenses a`, `decision: the failure, the state of the tree, and the options it accepts`, `as \`--step-action\` values. Diagnose the failure before choosing.`, ``, `- \`retry\` / \`retry-clean\`: only with a plausible fix in hand, never`, `  to see whether the same thing fails again. A step allows two retries;`, `  ask the user before using the last one. Past that, no retry is`, `  accepted.`, `- \`adopt\`: the migration's result is already in the working tree (you`, `  or the user applied it by hand, or a died worker's changes landed);`, `  record it as applied.`, `- \`skip\`: the migration does not apply to this workspace.`, `- \`unresolved\`: give the migration up. Nx records the failure as a run`, `  issue, settles the tree as the option describes, and moves on. The`, `  completion report lists it, and a session Nx started for this run`, `  exits non-zero; when you drive the loop yourself, the completion`, `  block's unresolved tally and warnings are what say work remains.`, `  Withheld, with \`skip\`, when a commit of this migration's changes`, `  landed, or was started and never recorded; the dispense then offers`, `  \`adopt\` in their place.`, ``, `Present the options to the user unless the choice is clearly yours to`, `make. When no user can answer (nothing interactive is driving this`, `session), give the step up with \`unresolved\` and continue the run`, `rather than stalling on it. Where the dispense withholds it, a commit of`, `the migration may already be in history: \`adopt\` only once you have`, `inspected the tree and finished the migration; otherwise stop and`, `report.`, ``, `## Commits`, ``);
+    if (ctx.createCommits) {
+        lines.push(`Nx commits each migration's changes itself. Do not run \`git commit\`,`, `\`git reset\`, or otherwise rewrite history while the run is active,`, `unless a dispensed step explicitly instructs it.`);
+    }
+    else {
+        lines.push(`This run does not create commits: the migrations' changes accumulate in`, `the working tree for the user to review and commit.`);
+    }
+    lines.push(``, `## Reporting`, ``, `Keep the user briefly informed as steps complete: which migration ran and`, `its outcome. When the run is reported complete, summarize the outcome for`, `the user: what was applied, adopted, skipped, or left unresolved, and any`, `warnings the completion carries.`, ``);
+    return lines.join('\n');
+}

package/dist/src/command-line/migrate/run/state-lock.d.ts

@@ -19,7 +19,38 @@ export declare function withRunCreationLock<T>(root: string, fn: () => T): T;
 /**
  * Reads the run state fresh under the lock, hands it to `apply`, and writes the
  * result back. `apply` returning null means "no change" and skips the write.
- * `apply` must be pure and synchronous; a corrupt or newer-format run.json
- * propagates from the read.
+ * `apply` runs exactly once, synchronously, so it may capture out-params; a
+ * corrupt or newer-format run.json propagates from the read.
  */
 export declare function updateRunState(runDirPath: string, apply: (fresh: MigrateRunState) => MigrateRunState | null): MigrateRunState;
+/**
+ * Marks this process as acting on the run until it exits or releases the
+ * hold, so a `--start-fresh` elsewhere refuses to delete it. One lock file per
+ * process and run, taken under the creation lock that deletion probes under.
+ * `exclusive` refuses while another process holds the run, even when this one
+ * already does. No-op under WASM, which has no native lock.
+ */
+export declare function holdRunActivity(root: string, runId: string, exclusive?: boolean): void;
+export declare function heldRunError(action: 'continuing' | 'deleting', runId: string, holders: number[] | 'unknown'): Error;
+export declare function describeHolders(holders: number[]): string;
+/**
+ * The hold without the creation lock: for the init that creates the run
+ * inside its own creation-lock section, so the run is never discoverable
+ * without a holder. Every other caller goes through holdRunActivity.
+ */
+export declare function registerRunActivity(dir: string): void;
+export declare function releaseRunActivity(dir: string): void;
+/**
+ * The pids of the other live processes holding the run, from their lock
+ * names. This process's own hold is skipped: a deleting init may hold the run
+ * from its report or preflight, which is not competing work. Locks left by
+ * dead holders are free. 'unknown' under WASM, and when the folder cannot be
+ * listed, a lock cannot be probed, or a held lock's name carries no pid.
+ */
+export declare function liveRunActivityPids(dir: string): number[] | 'unknown';
+/**
+ * Whether any live process, this one included, holds an activity lock on the
+ * run: for the init discovery that treats a held directory without run.json
+ * as a run being started, whichever process is starting it. Fails closed.
+ */
+export declare function hasAnyLiveRunActivity(dir: string): boolean;

package/dist/src/command-line/migrate/run/state-lock.js

@@ -16,12 +16,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.withRunStateLock = withRunStateLock;
 exports.withRunCreationLock = withRunCreationLock;
 exports.updateRunState = updateRunState;
+exports.holdRunActivity = holdRunActivity;
+exports.heldRunError = heldRunError;
+exports.describeHolders = describeHolders;
+exports.registerRunActivity = registerRunActivity;
+exports.releaseRunActivity = releaseRunActivity;
+exports.liveRunActivityPids = liveRunActivityPids;
+exports.hasAnyLiveRunActivity = hasAnyLiveRunActivity;
+const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const native_1 = require("../../../native");
 const run_state_1 = require("./run-state");
 const STATE_LOCK_FILE_NAME = 'run.json.lock';
 const CREATION_LOCK_FILE_NAME = 'init.lock';
+const ACTIVITY_DIR_NAME = 'activity';
 function withFileLock(lockPath, fn) {
     if (native_1.IS_WASM) {
         return fn();
@@ -61,8 +70,8 @@ function withRunCreationLock(root, fn) {
 /**
  * Reads the run state fresh under the lock, hands it to `apply`, and writes the
  * result back. `apply` returning null means "no change" and skips the write.
- * `apply` must be pure and synchronous; a corrupt or newer-format run.json
- * propagates from the read.
+ * `apply` runs exactly once, synchronously, so it may capture out-params; a
+ * corrupt or newer-format run.json propagates from the read.
  */
 function updateRunState(runDirPath, apply) {
     return withRunStateLock(runDirPath, () => {
@@ -74,3 +83,120 @@ function updateRunState(runDirPath, apply) {
         return next;
     });
 }
+// The activity locks this process holds, one per run dir. Each is held until
+// the process exits (the kernel releases it) or until this process releases
+// it: deleting the run, or handing a continue off to the workspace-local nx.
+const heldActivity = new Map();
+/**
+ * Marks this process as acting on the run until it exits or releases the
+ * hold, so a `--start-fresh` elsewhere refuses to delete it. One lock file per
+ * process and run, taken under the creation lock that deletion probes under.
+ * `exclusive` refuses while another process holds the run, even when this one
+ * already does. No-op under WASM, which has no native lock.
+ */
+function holdRunActivity(root, runId, exclusive = false) {
+    if (native_1.IS_WASM)
+        return;
+    const dir = (0, run_state_1.runDir)(root, runId);
+    if (heldActivity.has(dir) && !exclusive)
+        return;
+    withRunCreationLock(root, () => {
+        if (!(0, run_state_1.hasRunState)(dir)) {
+            throw new Error(`Migrate run '${runId}' was deleted while this command was starting.`);
+        }
+        if (exclusive) {
+            const others = liveRunActivityPids(dir);
+            if (others === 'unknown' || others.length > 0) {
+                throw heldRunError('continuing', runId, others);
+            }
+        }
+        registerRunActivity(dir);
+    });
+}
+// 'unknown' is the fail-closed case: the activity folder could not be read or
+// a lock could not be probed.
+function heldRunError(action, runId, holders) {
+    const refusal = `Not ${action} migrate run '${runId}'`;
+    return new Error(holders === 'unknown'
+        ? `${refusal}: nx cannot tell whether another nx migrate process is still working on it.`
+        : `${refusal}: ${describeHolders(holders)} (an agent session, a reconcile, or a step). Wait for it to end, then re-run the command.`);
+}
+function describeHolders(holders) {
+    return holders.length === 1
+        ? `process ${holders[0]} is still working on it`
+        : `processes ${holders.join(', ')} are still working on it`;
+}
+/**
+ * The hold without the creation lock: for the init that creates the run
+ * inside its own creation-lock section, so the run is never discoverable
+ * without a holder. Every other caller goes through holdRunActivity.
+ */
+function registerRunActivity(dir) {
+    if (native_1.IS_WASM || heldActivity.has(dir))
+        return;
+    const name = `${process.pid}-${(0, crypto_1.randomBytes)(4).toString('hex')}.lock`;
+    const lock = new native_1.FileLock((0, path_1.join)(dir, ACTIVITY_DIR_NAME, name));
+    lock.lock();
+    heldActivity.set(dir, { lock, name });
+}
+function releaseRunActivity(dir) {
+    const held = heldActivity.get(dir);
+    if (held === undefined)
+        return;
+    held.lock.unlock();
+    heldActivity.delete(dir);
+}
+/**
+ * The pids of the other live processes holding the run, from their lock
+ * names. This process's own hold is skipped: a deleting init may hold the run
+ * from its report or preflight, which is not competing work. Locks left by
+ * dead holders are free. 'unknown' under WASM, and when the folder cannot be
+ * listed, a lock cannot be probed, or a held lock's name carries no pid.
+ */
+function liveRunActivityPids(dir) {
+    if (native_1.IS_WASM)
+        return 'unknown';
+    const names = liveActivityNames(dir, heldActivity.get(dir)?.name);
+    if (names === 'unknown')
+        return 'unknown';
+    const pids = names.map((name) => Number(name.split('-', 1)[0]));
+    return pids.every((pid) => Number.isInteger(pid) && pid > 0)
+        ? pids
+        : 'unknown';
+}
+/**
+ * Whether any live process, this one included, holds an activity lock on the
+ * run: for the init discovery that treats a held directory without run.json
+ * as a run being started, whichever process is starting it. Fails closed.
+ */
+function hasAnyLiveRunActivity(dir) {
+    const names = liveActivityNames(dir, undefined);
+    return names === 'unknown' || names.length > 0;
+}
+// The names of the held lock files other than `skip`; 'unknown' when the
+// folder cannot be listed or a lock cannot be probed.
+function liveActivityNames(dir, skip) {
+    let names;
+    try {
+        names = (0, fs_1.readdirSync)((0, path_1.join)(dir, ACTIVITY_DIR_NAME));
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT')
+            return [];
+        return 'unknown';
+    }
+    const held = [];
+    for (const name of names) {
+        if (name === skip)
+            continue;
+        try {
+            if (new native_1.FileLock((0, path_1.join)(dir, ACTIVITY_DIR_NAME, name)).check()) {
+                held.push(name);
+            }
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    return held;
+}

package/dist/src/command-line/migrate/run/state-machine.d.ts

@@ -1,5 +1,6 @@
 import type { CommitResult } from '../migrate-commits';
-import type { MigrateCommitLedgerEntry, MigrateRunState, MigrateStepOutcome, MigrateStepPromptOutcome } from './run-state';
+import type { MigrateCommitLedgerEntry, MigrateRunState, MigrateStep, MigrateStepAwaitingKind, MigrateStepOutcome, MigrateStepPromptOutcome } from './run-state';
+import type { MigrateOrchestratorTallies } from '../migrate-analytics';
 import type { StepAction } from '../step-actions';
 export type { StepAction };
 export type StepEvent = {
@@ -24,6 +25,11 @@ export type StepEvent = {
     type: 'awaitPromptOutcome';
     stepId: string;
     finishedAt: string;
+    awaitingKind: MigrateStepAwaitingKind;
+} | {
+    type: 'parkForFinalValidation';
+    stepId: string;
+    finishedAt: string;
 } | {
     type: 'foldPromptOutcome';
     stepId: string;
@@ -32,6 +38,9 @@ export type StepEvent = {
 } | {
     type: 'markGeneratorCompleted';
     stepId: string;
+    agenticWaived: boolean;
+    validationOwed: boolean;
+    madeChanges: boolean;
 } | {
     type: 'markDied';
     stepId: string;
@@ -50,6 +59,25 @@ export type ApplyStepEventResult = {
     reason: string;
 };
 export declare function applyStepEvent(state: MigrateRunState, event: StepEvent): ApplyStepEventResult;
+/**
+ * Forgets the generator run of `stepId`'s current attempt, unless a landed
+ * commit already carries its changes.
+ */
+export declare function discardGeneratorRun(state: MigrateRunState, stepId: string): MigrateRunState;
+export interface StepTally {
+    applied: number;
+    adopted: number;
+    skipped: number;
+    unresolved: MigrateStep[];
+    remaining: number;
+    stalled: number;
+}
+export declare function tallySteps(state: MigrateRunState): StepTally;
+export declare function runTallies(state: MigrateRunState): MigrateOrchestratorTallies;
+export declare function unresolvedFailureDetail(step: MigrateStep): string;
+export declare function completionSummaryLines(state: MigrateRunState): string[];
+export declare function unresolvedCommitName(step: MigrateStep): string;
+export declare function commitNameForStep(step: MigrateStep): string;
 /**
  * Records that the run could not install the dependency changes a step left
  * behind. Not a {@link StepEvent}: it annotates a step instead of moving it,
@@ -66,7 +94,27 @@ export declare function uncoveredFailedStepIds(state: MigrateRunState): string[]
  */
 export declare function hasPendingCommitDebt(state: MigrateRunState): boolean;
 export declare function coveringLandedEntries(state: MigrateRunState, stepId: string): MigrateCommitLedgerEntry[];
+export declare function markCommitStarted(state: MigrateRunState, stepId: string): MigrateRunState;
+export declare function clearCommitStarted(state: MigrateRunState, stepId: string): MigrateRunState;
+/**
+ * True when a landed entry names the step, or a commit was started for it
+ * that no entry accounts for. Skipping the step would then report as not
+ * applied a migration whose commit is, or may be, in history.
+ */
+export declare function commitMayBeInHistory(state: MigrateRunState, step: MigrateStep): boolean;
+export declare function appendCommit(state: MigrateRunState, entry: MigrateCommitLedgerEntry): MigrateRunState;
+/**
+ * The entry a parent session recorded for this attempt's commit, or undefined
+ * without a receipt. A receipt past the ledger or naming another step is
+ * corrupt run state, so it throws.
+ */
+export declare function commitReceipt(state: MigrateRunState, step: MigrateStep): {
+    index: number;
+    entry: MigrateCommitLedgerEntry;
+} | undefined;
 export declare function latestRound(state: MigrateRunState): MigrateRunState['rounds'][number] | undefined;
+export declare function stepNoun(step: MigrateStep): string;
+export declare function stepLabel(step: MigrateStep): string;
 export declare function splitMigrationId(id: string): {
     package: string;
     name: string;
@@ -75,6 +123,7 @@ export declare function stepsToPendingMigrations(state: MigrateRunState, stepIds
     package: string;
     name: string;
 }[];
+export declare function gitRan(result: CommitResult): boolean;
 /**
  * Classifies a commit attempt into the ledger entry to record, or null when
  * there is nothing to record ('no-changes' / 'disabled'). A landed entry