@ohos-ports/nx 23.2.1-beta.0 → 23.3.0-beta.0

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

@@ -0,0 +1,55 @@
+import { type AncestorStatus } from '../../../utils/git-utils';
+import { type MigrateCommitLedgerEntry, type MigrateRunPolicy, type MigrateRunState } from './run-state';
+import { type StepTally } from './state-machine';
+export declare function progressLine(tally: StepTally): string;
+export interface ExistingRunFacts {
+    runId: string;
+    createdAt: string;
+    recordedBranch: string | undefined;
+    currentBranch: string | null;
+    progress: StepTally;
+    unresolvedIssues: number;
+    policy: MigrateRunPolicy;
+    commits: {
+        recorded: number;
+        reachable: number;
+        unchecked: number;
+        newest: {
+            sha: string | null;
+            status: AncestorStatus;
+        } | null;
+    };
+    liveWorkers: {
+        pid: number;
+        stepId: string;
+        label: string;
+    }[];
+    otherHolders: number[] | 'unknown';
+    otherActiveRuns: string[] | 'unknown';
+    appliedStillPlanned: number | undefined;
+    replacedRunId?: string;
+}
+export declare function collectExistingRunFacts(root: string, runId: string, state: MigrateRunState, plannedMigrationIds?: readonly string[]): ExistingRunFacts;
+export declare function liveWorkers(state: MigrateRunState): ExistingRunFacts['liveWorkers'];
+export declare function recordedCommits(state: MigrateRunState): MigrateCommitLedgerEntry[];
+export declare function renderContinueCommand(root: string, runId: string, policy: MigrateRunPolicy, agentId?: string): string;
+export interface ExistingRunCommands {
+    continueCommand: string;
+    startFresh: {
+        command: string;
+    } | {
+        migrationsPath: string;
+    };
+}
+export declare function renderExistingRunCommands(root: string, facts: ExistingRunFacts, migrationsPath: string | undefined, agentId?: string): ExistingRunCommands;
+/**
+ * Title plus body lines, in the shape the agent-output writers take. Every
+ * body line goes through `singleLine`: branch names and timestamps came from
+ * git and disk, and the lines end up on the stdout the agent scans for
+ * blocks. The title carries only the run id, which discovery validated.
+ */
+export declare function renderExistingRunReport(facts: ExistingRunFacts, commands?: ExistingRunCommands): {
+    title: string;
+    bodyLines: string[];
+};
+export declare function workersLine(workers: ExistingRunFacts['liveWorkers']): string;

package/dist/src/command-line/migrate/run/existing-run-report.js

@@ -0,0 +1,227 @@
+"use strict";
+// The report on a run already active. Facts only: nothing here decides, and
+// anything that could not be established says so instead of guessing.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.progressLine = progressLine;
+exports.collectExistingRunFacts = collectExistingRunFacts;
+exports.liveWorkers = liveWorkers;
+exports.recordedCommits = recordedCommits;
+exports.renderContinueCommand = renderContinueCommand;
+exports.renderExistingRunCommands = renderExistingRunCommands;
+exports.renderExistingRunReport = renderExistingRunReport;
+exports.workersLine = workersLine;
+const git_utils_1 = require("../../../utils/git-utils");
+const text_1 = require("../text");
+const run_state_1 = require("./run-state");
+const issues_1 = require("./issues");
+const state_lock_1 = require("./state-lock");
+const state_machine_1 = require("./state-machine");
+const util_1 = require("./util");
+// The stalled count is a subset of `remaining`, called out separately: the
+// count alone would read as work that has not been reached yet. Adopted and
+// unresolved appear only when present, so the common line stays short.
+function progressLine(tally) {
+    return `${tally.applied} applied, ${tally.adopted > 0 ? `${tally.adopted} adopted, ` : ''}${tally.skipped} skipped, ${tally.unresolved.length > 0 ? `${tally.unresolved.length} unresolved, ` : ''}${tally.remaining} remaining${tally.stalled > 0 ? ` (${tally.stalled} awaiting a decision)` : ''}`;
+}
+function collectExistingRunFacts(root, runId, state, plannedMigrationIds) {
+    const head = (0, git_utils_1.getLatestCommitSha)(root);
+    // A landed entry may have lost its sha to a transient rev-parse failure;
+    // it still counts, as a commit that could not be checked.
+    const commits = recordedCommits(state);
+    const statuses = commits.map((entry) => entry.sha && head
+        ? (0, git_utils_1.getAncestorStatus)(entry.sha, head, root)
+        : 'unknown');
+    const newestIndex = commits.length - 1;
+    const planned = plannedMigrationIds ? new Set(plannedMigrationIds) : null;
+    return {
+        runId,
+        createdAt: state.createdAt,
+        recordedBranch: state.branch,
+        currentBranch: (0, git_utils_1.getGitCurrentBranch)(root),
+        progress: (0, state_machine_1.tallySteps)(state),
+        unresolvedIssues: (0, issues_1.unresolvedIssues)(state).length,
+        policy: {
+            createCommits: state.createCommits,
+            skipInstall: state.skipInstall === true,
+        },
+        commits: {
+            recorded: commits.length,
+            reachable: statuses.filter((s) => s === 'ancestor').length,
+            unchecked: statuses.filter((s) => s === 'unknown').length,
+            newest: newestIndex >= 0
+                ? {
+                    sha: commits[newestIndex].sha ?? null,
+                    status: statuses[newestIndex],
+                }
+                : null,
+        },
+        liveWorkers: liveWorkers(state),
+        otherHolders: (0, state_lock_1.liveRunActivityPids)((0, run_state_1.runDir)(root, runId)),
+        otherActiveRuns: otherActiveRuns(root, runId),
+        appliedStillPlanned: planned
+            ? state.steps.filter((s) => s.kind === 'migration' &&
+                s.status === 'succeeded' &&
+                planned.has(s.migrationId)).length
+            : undefined,
+    };
+}
+// Only a step recorded as running can own a worker; a died or finished step's
+// pid may have been reused by an unrelated process since.
+function liveWorkers(state) {
+    return state.steps
+        .filter((s) => s.status === 'running' && s.pid !== undefined && (0, util_1.isPidAlive)(s.pid))
+        .map((s) => ({ pid: s.pid, stepId: s.id, label: (0, state_machine_1.stepLabel)(s) }));
+}
+// The commits the run made, in ledger order.
+function recordedCommits(state) {
+    return state.commits.filter((entry) => madeCommit(entry.kind));
+}
+function madeCommit(kind) {
+    switch (kind) {
+        case 'checkpoint':
+        case 'landed':
+            return true;
+        case 'failed':
+            return false;
+        default: {
+            const exhaustive = kind;
+            throw new Error(`Unhandled commit kind '${exhaustive}'.`);
+        }
+    }
+}
+function otherActiveRuns(root, runId) {
+    try {
+        return (0, run_state_1.findActiveRun)(root).activeRunIds.filter((id) => id !== runId);
+    }
+    catch (e) {
+        if (e instanceof run_state_1.NewerRunStateFormatError) {
+            return 'unknown';
+        }
+        throw e;
+    }
+}
+// The `--run-migrations --run-id` continue, the one entry that re-enters a
+// run on both paths. The policy flags are always explicit: a continue must
+// resolve to the run's recorded policy, and nx.json can flip the bare default
+// either way. `--agentic` names the agent to spawn; bare, inside an agent, it
+// only satisfies the parse and the run continues in place.
+function renderContinueCommand(root, runId, policy, agentId) {
+    return `${(0, util_1.pmExecPrefix)(root)} nx migrate --run-migrations --agentic${agentId === undefined ? '' : `=${agentId}`} --run-id=${runId} ${policy.createCommits ? '--create-commits' : '--no-create-commits'}${policy.skipInstall ? ' --skip-install' : ''}`;
+}
+function renderExistingRunCommands(root, facts, migrationsPath, agentId) {
+    const flag = migrationsPath === undefined
+        ? '--run-migrations'
+        : (0, util_1.runMigrationsFlag)(migrationsPath);
+    return {
+        continueCommand: renderContinueCommand(root, facts.runId, facts.policy, agentId),
+        startFresh: flag === null
+            ? { migrationsPath }
+            : {
+                command: `${(0, util_1.pmExecPrefix)(root)} nx migrate ${flag}${agentId === undefined ? '' : ` --agentic=${agentId}`} --start-fresh --run-id=${facts.runId}`,
+            },
+    };
+}
+/**
+ * Title plus body lines, in the shape the agent-output writers take. Every
+ * body line goes through `singleLine`: branch names and timestamps came from
+ * git and disk, and the lines end up on the stdout the agent scans for
+ * blocks. The title carries only the run id, which discovery validated.
+ */
+function renderExistingRunReport(facts, commands) {
+    const lines = [
+        ...(facts.replacedRunId !== undefined
+            ? [
+                `Not deleting ${facts.replacedRunId}: the newest active run is ${facts.runId}.`,
+            ]
+            : []),
+        `  run: ${facts.runId}`,
+        `  started: ${facts.createdAt} (${(0, text_1.formatAge)(facts.createdAt)})`,
+        `  branch: ${branchLine(facts)}`,
+        `  progress: ${progressLine(facts.progress)}`,
+        `  policy: per-migration commits ${facts.policy.createCommits ? 'on' : 'off'}, installs ${facts.policy.skipInstall ? 'skipped' : 'on'}`,
+        `  commits: ${commitsLine(facts.commits)}`,
+        `  worker: ${workersLine(facts.liveWorkers)}`,
+        `  activity: ${activityLine(facts.otherHolders)}`,
+    ];
+    if (facts.unresolvedIssues > 0) {
+        lines.push(`  issues: ${facts.unresolvedIssues} unresolved`);
+    }
+    if (facts.otherActiveRuns === 'unknown') {
+        lines.push(`  other active runs on disk: unknown (a run written by a newer nx is on disk)`);
+    }
+    else if (facts.otherActiveRuns.length > 0) {
+        lines.push(`  other active runs on disk: ${facts.otherActiveRuns.join(', ')}`);
+    }
+    if (facts.appliedStillPlanned !== undefined) {
+        lines.push(`  plan overlap: ${facts.appliedStillPlanned} of the applied migrations ${facts.appliedStillPlanned === 1 ? 'is' : 'are'} still in the plan; a new run applies ${facts.appliedStillPlanned === 1 ? 'it' : 'them'} again`);
+    }
+    if (commands) {
+        lines.push(``, `To continue the run: ${commands.continueCommand}`, `To start fresh (deletes the run record, then runs the whole plan again): ${'command' in commands.startFresh
+            ? commands.startFresh.command
+            : `re-run this command with --start-fresh --run-id=${facts.runId}, keeping the --run-migrations argument, which names ${displayPath(commands.startFresh.migrationsPath)}; that path cannot be rendered as a command for this shell`}`, `Run either command with NX_MIGRATE_ORCHESTRATOR=true set in the environment.`);
+    }
+    return {
+        title: `A migrate run is already active: ${facts.runId}`,
+        bodyLines: lines.map(text_1.singleLine),
+    };
+}
+// Prose, not a command, so a path goes out verbatim. A path with a line break
+// goes out JSON-escaped: singleLine below would otherwise turn the break into
+// a space and name a different path. JSON.stringify leaves U+0085, U+2028 and
+// U+2029 literal, so those are escaped by hand.
+function displayPath(migrationsPath) {
+    if (!(0, text_1.hasLineBreak)(migrationsPath)) {
+        return migrationsPath;
+    }
+    return JSON.stringify(migrationsPath).replace(/[\u0085\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+// A null probe is 'unknown' on both sides: getGitCurrentBranch folds a
+// detached HEAD and a failed git call into one null.
+function branchLine(facts) {
+    const recorded = facts.recordedBranch ?? 'unknown';
+    const current = facts.currentBranch ?? 'unknown';
+    return recorded === current
+        ? recorded
+        : `started on ${recorded}, currently on ${current}`;
+}
+function commitsLine(commits) {
+    if (!commits.newest) {
+        return 'none recorded';
+    }
+    const newest = commits.newest.sha === null
+        ? 'newest recorded commit has no recorded sha and could not be checked'
+        : `newest recorded commit ${commits.newest.sha.slice(0, 10)} is ${describeStatus(commits.newest.status)}`;
+    const tally = `${commits.reachable} of ${commits.recorded} reachable${commits.unchecked > 0 ? `, ${commits.unchecked} could not be checked` : ''}`;
+    return `${newest} (${tally})`;
+}
+function describeStatus(status) {
+    switch (status) {
+        case 'ancestor':
+            return 'reachable from HEAD';
+        case 'not-ancestor':
+            return 'not reachable from HEAD';
+        case 'unknown':
+            return 'of unknown reachability from HEAD';
+        default: {
+            const exhaustive = status;
+            throw new Error(`Unhandled ancestor status '${exhaustive}'.`);
+        }
+    }
+}
+function activityLine(holders) {
+    if (holders === 'unknown') {
+        return 'unknown whether another nx migrate process is working on it';
+    }
+    if (holders.length === 0) {
+        return 'no other nx migrate process is working on it';
+    }
+    return (0, state_lock_1.describeHolders)(holders);
+}
+function workersLine(workers) {
+    if (workers.length === 0) {
+        return 'none running';
+    }
+    return workers
+        .map((w) => `pid ${w.pid} is still running ${w.stepId} (${w.label})`)
+        .join('; ');
+}

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

@@ -0,0 +1,41 @@
+import { type CommitResult } from '../migrate-commits';
+import type { MigrateOutputSink } from '../deferred-output';
+import type { TreeLease } from './broker';
+import { type MigrateRunState, type MigrateStep } from './run-state';
+export type GiveUpOutcome = {
+    kind: 'given-up';
+    commit: CommitResult | {
+        status: 'install-failed';
+        reason: string;
+    };
+    archiveError?: string;
+} | {
+    kind: 'refused';
+    reason: string;
+};
+export interface GiveUpInput {
+    root: string;
+    dir: string;
+    step: MigrateStep;
+    lease: TreeLease;
+    skipInstall: boolean;
+    reconcileCommand: string;
+    output?: MigrateOutputSink;
+}
+export declare function giveUpWithCommit(input: GiveUpInput): Promise<GiveUpOutcome>;
+/**
+ * Mints the issue that carries a given-up step's failure and points the step
+ * at it, on state where the step is already unresolved. The archive file is
+ * best-effort: run.json is authoritative, and undoing the transition for a
+ * lost detail file would make the agent re-issue an action the run already
+ * took.
+ */
+export declare function recordUnresolvedIssue(dir: string, state: MigrateRunState, stepId: string): {
+    state: MigrateRunState;
+    archiveError?: string;
+};
+export declare function warnUnresolvedNotArchived(label: string, archiveError: string): void;
+/** What the reconcile owes the agent for a give-up that went through. */
+export declare function warnAboutGiveUp(step: MigrateStep, outcome: Extract<GiveUpOutcome, {
+    kind: 'given-up';
+}>): void;

package/dist/src/command-line/migrate/run/give-up.js

@@ -0,0 +1,148 @@
+"use strict";
+// Giving a step up while the run commits is one operation under one tree
+// reservation, run by the process that holds the tree (a session's parent or
+// the reconcile): split across two, the transition would find the give-up's
+// own commit in the ledger and refuse it as a commit of the migration.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.giveUpWithCommit = giveUpWithCommit;
+exports.recordUnresolvedIssue = recordUnresolvedIssue;
+exports.warnUnresolvedNotArchived = warnUnresolvedNotArchived;
+exports.warnAboutGiveUp = warnAboutGiveUp;
+const migrate_commits_1 = require("../migrate-commits");
+const agent_output_1 = require("./agent-output");
+const issues_1 = require("./issues");
+const run_state_1 = require("./run-state");
+const state_lock_1 = require("./state-lock");
+const state_machine_1 = require("./state-machine");
+const util_1 = require("./util");
+async function giveUpWithCommit(input) {
+    const { root, dir, step, lease } = input;
+    const ownMark = lease.markedStepId === step.id;
+    const event = {
+        type: 'stepAction',
+        stepId: step.id,
+        action: 'unresolved',
+        attempt: step.attempt,
+    };
+    const state = (0, run_state_1.readRunState)(dir);
+    // Checked under the reservation, before git runs: a landed commit of the
+    // step, or a mark another operation left, refuses the give-up with nothing
+    // to undo. The mark this reservation set is not evidence against it.
+    const accepted = (0, state_machine_1.applyStepEvent)(ownMark ? (0, state_machine_1.clearCommitStarted)(state, step.id) : state, event);
+    if (accepted.kind === 'error') {
+        return { kind: 'refused', reason: accepted.reason };
+    }
+    const absorbedStepIds = (0, state_machine_1.uncoveredFailedStepIds)(state).filter((id) => id !== step.id);
+    let commit;
+    let entry;
+    try {
+        const result = await (0, migrate_commits_1.commitMigrationIfRequested)(root, { name: (0, state_machine_1.unresolvedCommitName)(step) }, true, state.commitPrefix, () => (0, util_1.installDepsChangedSinceDispense)(root, dir, step, input.skipInstall, input.reconcileCommand, input.output), (0, state_machine_1.stepsToPendingMigrations)(state, absorbedStepIds), undefined, input.output);
+        commit = result;
+        entry = (0, state_machine_1.commitResultToLedgerEntry)(result, step.id, absorbedStepIds);
+    }
+    catch (e) {
+        // The install is the only thrower: the commit reports through its result.
+        // The debt cannot stand in for the install failure, since a later commit
+        // absorbing this diff clears the debt while the dependencies are still
+        // missing.
+        commit = { status: 'install-failed', reason: (0, util_1.summarizeError)(e) };
+        entry = { kind: 'failed', stepIds: [step.id] };
+    }
+    const ran = commit.status !== 'install-failed' && (0, state_machine_1.gitRan)(commit);
+    if (ran)
+        lease.markedStepId = undefined;
+    let archiveError;
+    let refusal;
+    (0, state_lock_1.updateRunState)(dir, (fresh) => {
+        // Re-applied on fresh state. The reservation kept every other commit of
+        // the step out, so only run state edited from outside can refuse it now;
+        // the commit then stays unrecorded, with the mark standing for an adopt.
+        const applied = (0, state_machine_1.applyStepEvent)(ownMark ? (0, state_machine_1.clearCommitStarted)(fresh, step.id) : fresh, event);
+        if (applied.kind === 'error') {
+            refusal = applied.reason;
+            return null;
+        }
+        // A failure once git ran keeps the mark: only a landed entry accounts
+        // for the commit it may have made.
+        const recorded = recordUnresolvedIssue(dir, ownMark && commit.status === 'failed'
+            ? (0, state_machine_1.markCommitStarted)(applied.state, step.id)
+            : applied.state, step.id);
+        archiveError = recorded.archiveError;
+        const next = commit.status === 'install-failed'
+            ? (0, state_machine_1.markInstallFailed)(recorded.state, step.id)
+            : recorded.state;
+        return entry
+            ? (0, state_machine_1.appendCommit)(next, (0, issues_1.attachIssueIdsToCommitEntry)(next, entry))
+            : next;
+    });
+    if (refusal !== undefined) {
+        return {
+            kind: 'refused',
+            reason: entry?.kind === 'landed' && entry.sha
+                ? `${refusal} Note: this action's commit ${entry.sha} had already landed and stays in history; resolve the step against the tree as it stands now.`
+                : refusal,
+        };
+    }
+    return {
+        kind: 'given-up',
+        commit,
+        ...(archiveError !== undefined ? { archiveError } : {}),
+    };
+}
+/**
+ * Mints the issue that carries a given-up step's failure and points the step
+ * at it, on state where the step is already unresolved. The archive file is
+ * best-effort: run.json is authoritative, and undoing the transition for a
+ * lost detail file would make the agent re-issue an action the run already
+ * took.
+ */
+function recordUnresolvedIssue(dir, state, stepId) {
+    // Minted from the transitioned step: a died one only gains its failure in
+    // the transition.
+    const minted = (0, issues_1.mintUnresolvedIssue)(state, state.steps.find((s) => s.id === stepId));
+    let archiveError;
+    try {
+        (0, issues_1.archiveIssues)(dir, minted.application);
+    }
+    catch (e) {
+        archiveError = (0, util_1.summarizeError)(e);
+    }
+    return {
+        state: {
+            ...minted.application.state,
+            steps: minted.application.state.steps.map((s) => s.id === stepId ? { ...s, unresolvedIssueId: minted.issueId } : s),
+        },
+        ...(archiveError !== undefined ? { archiveError } : {}),
+    };
+}
+function warnUnresolvedNotArchived(label, archiveError) {
+    (0, agent_output_1.warnToAgent)({
+        title: `The issue recording that ${label} was left unresolved could not be archived (${archiveError}).`,
+        bodyLines: [
+            `run.json stays authoritative: the step is unresolved and the issue is in its ledger; only the archived file under the run's issues directory is missing.`,
+        ],
+    });
+}
+/** What the reconcile owes the agent for a give-up that went through. */
+function warnAboutGiveUp(step, outcome) {
+    const name = (0, state_machine_1.unresolvedCommitName)(step);
+    switch (outcome.commit.status) {
+        case 'install-failed':
+            (0, util_1.warnCommitFailed)(name, outcome.commit.reason);
+            break;
+        case 'failed':
+            (0, util_1.warnCommitFailed)(name);
+            break;
+        case 'committed':
+        case 'no-changes':
+        case 'disabled':
+            break;
+        default: {
+            const exhaustive = outcome.commit;
+            throw new Error(`Unhandled commit result: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+    if (outcome.archiveError !== undefined) {
+        warnUnresolvedNotArchived((0, state_machine_1.stepLabel)(step), outcome.archiveError);
+    }
+}

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

@@ -0,0 +1,12 @@
+export { CURRENT_RUN_STATE_FORMAT_VERSION, NewerRunStateFormatError, migrateRunsDir, runDir, runHandoffsDir, readRunState, writeRunState, findActiveRun, createRun, } from './run-state';
+export type { MigrateRunStatus, MigrateRunRound, MigrateStepStatus, PromptOutcomeStatus, MigrateStepAwaitingKind, MigrateStepOutcome, MigrateStepPromptOutcome, MigrateStep, MigrateCommitKind, MigrateCommitLedgerEntry, MigrateIssueDisposition, MigrateRunIssue, MigrateRunAnalytics, MigrateRunNoProgress, MigrateRunPolicy, MigrateRunState, } from './run-state';
+export { applyStepEvent, completionSummaryLines, hasPendingCommitDebt, latestRound, runTallies, tallySteps, } from './state-machine';
+export { hasUnresolvedIssues } from './issues';
+export type { StepAction, StepEvent, ApplyStepEventResult, } from './state-machine';
+export { createRunId } from './run-id';
+export { runSingleMigrationWorker } from './worker';
+export type { RunSingleMigrationWorkerInput } from './worker';
+export { activeRunToReplace, completionWarnings, holdRunToContinue, releaseRunToHandOff, runOrchestratorInit, runOrchestratorReconcile, runOrchestratorResume, } from './orchestrator';
+export type { OrchestratorInitResult, RunOrchestratorInitInput, RunOrchestratorReconcileInput, } from './orchestrator';
+export { renderContinueCommand, renderExistingRunCommands, renderExistingRunReport, } from './existing-run-report';
+export { BROKER_ENV_VAR, MigrateCommitBroker, treeOperationLabel, } from './broker';

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

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.treeOperationLabel = exports.MigrateCommitBroker = exports.BROKER_ENV_VAR = exports.renderExistingRunReport = exports.renderExistingRunCommands = exports.renderContinueCommand = exports.runOrchestratorResume = exports.runOrchestratorReconcile = exports.runOrchestratorInit = exports.releaseRunToHandOff = exports.holdRunToContinue = exports.completionWarnings = exports.activeRunToReplace = exports.runSingleMigrationWorker = exports.createRunId = exports.hasUnresolvedIssues = exports.tallySteps = exports.runTallies = exports.latestRound = exports.hasPendingCommitDebt = exports.completionSummaryLines = exports.applyStepEvent = exports.createRun = exports.findActiveRun = exports.writeRunState = exports.readRunState = exports.runHandoffsDir = exports.runDir = exports.migrateRunsDir = exports.NewerRunStateFormatError = exports.CURRENT_RUN_STATE_FORMAT_VERSION = void 0;
+var run_state_1 = require("./run-state");
+Object.defineProperty(exports, "CURRENT_RUN_STATE_FORMAT_VERSION", { enumerable: true, get: function () { return run_state_1.CURRENT_RUN_STATE_FORMAT_VERSION; } });
+Object.defineProperty(exports, "NewerRunStateFormatError", { enumerable: true, get: function () { return run_state_1.NewerRunStateFormatError; } });
+Object.defineProperty(exports, "migrateRunsDir", { enumerable: true, get: function () { return run_state_1.migrateRunsDir; } });
+Object.defineProperty(exports, "runDir", { enumerable: true, get: function () { return run_state_1.runDir; } });
+Object.defineProperty(exports, "runHandoffsDir", { enumerable: true, get: function () { return run_state_1.runHandoffsDir; } });
+Object.defineProperty(exports, "readRunState", { enumerable: true, get: function () { return run_state_1.readRunState; } });
+Object.defineProperty(exports, "writeRunState", { enumerable: true, get: function () { return run_state_1.writeRunState; } });
+Object.defineProperty(exports, "findActiveRun", { enumerable: true, get: function () { return run_state_1.findActiveRun; } });
+Object.defineProperty(exports, "createRun", { enumerable: true, get: function () { return run_state_1.createRun; } });
+var state_machine_1 = require("./state-machine");
+Object.defineProperty(exports, "applyStepEvent", { enumerable: true, get: function () { return state_machine_1.applyStepEvent; } });
+Object.defineProperty(exports, "completionSummaryLines", { enumerable: true, get: function () { return state_machine_1.completionSummaryLines; } });
+Object.defineProperty(exports, "hasPendingCommitDebt", { enumerable: true, get: function () { return state_machine_1.hasPendingCommitDebt; } });
+Object.defineProperty(exports, "latestRound", { enumerable: true, get: function () { return state_machine_1.latestRound; } });
+Object.defineProperty(exports, "runTallies", { enumerable: true, get: function () { return state_machine_1.runTallies; } });
+Object.defineProperty(exports, "tallySteps", { enumerable: true, get: function () { return state_machine_1.tallySteps; } });
+var issues_1 = require("./issues");
+Object.defineProperty(exports, "hasUnresolvedIssues", { enumerable: true, get: function () { return issues_1.hasUnresolvedIssues; } });
+var run_id_1 = require("./run-id");
+Object.defineProperty(exports, "createRunId", { enumerable: true, get: function () { return run_id_1.createRunId; } });
+var worker_1 = require("./worker");
+Object.defineProperty(exports, "runSingleMigrationWorker", { enumerable: true, get: function () { return worker_1.runSingleMigrationWorker; } });
+var orchestrator_1 = require("./orchestrator");
+Object.defineProperty(exports, "activeRunToReplace", { enumerable: true, get: function () { return orchestrator_1.activeRunToReplace; } });
+Object.defineProperty(exports, "completionWarnings", { enumerable: true, get: function () { return orchestrator_1.completionWarnings; } });
+Object.defineProperty(exports, "holdRunToContinue", { enumerable: true, get: function () { return orchestrator_1.holdRunToContinue; } });
+Object.defineProperty(exports, "releaseRunToHandOff", { enumerable: true, get: function () { return orchestrator_1.releaseRunToHandOff; } });
+Object.defineProperty(exports, "runOrchestratorInit", { enumerable: true, get: function () { return orchestrator_1.runOrchestratorInit; } });
+Object.defineProperty(exports, "runOrchestratorReconcile", { enumerable: true, get: function () { return orchestrator_1.runOrchestratorReconcile; } });
+Object.defineProperty(exports, "runOrchestratorResume", { enumerable: true, get: function () { return orchestrator_1.runOrchestratorResume; } });
+var existing_run_report_1 = require("./existing-run-report");
+Object.defineProperty(exports, "renderContinueCommand", { enumerable: true, get: function () { return existing_run_report_1.renderContinueCommand; } });
+Object.defineProperty(exports, "renderExistingRunCommands", { enumerable: true, get: function () { return existing_run_report_1.renderExistingRunCommands; } });
+Object.defineProperty(exports, "renderExistingRunReport", { enumerable: true, get: function () { return existing_run_report_1.renderExistingRunReport; } });
+var broker_1 = require("./broker");
+Object.defineProperty(exports, "BROKER_ENV_VAR", { enumerable: true, get: function () { return broker_1.BROKER_ENV_VAR; } });
+Object.defineProperty(exports, "MigrateCommitBroker", { enumerable: true, get: function () { return broker_1.MigrateCommitBroker; } });
+Object.defineProperty(exports, "treeOperationLabel", { enumerable: true, get: function () { return broker_1.treeOperationLabel; } });

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

@@ -0,0 +1,127 @@
+import { issueFingerprint, type MigrateCommitLedgerEntry, type MigrateIssueDisposition, type MigrateRunIssue, type MigrateRunState, type MigrateStep } from './run-state';
+export { issueFingerprint };
+export interface ReportedIssue {
+    summary: string;
+    detail?: string;
+    applicableMigrations: string[] | 'unknown';
+    disposition?: MigrateIssueDisposition;
+}
+export interface ReportedIssueUpdate {
+    id: string;
+    disposition: Exclude<MigrateIssueDisposition, 'recorded'>;
+    note?: string;
+}
+export type ParsedHandoffIssues = {
+    ok: true;
+    issues: ReportedIssue[];
+    updates: ReportedIssueUpdate[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validates a handoff's `issues` / `issueUpdates` against the run's current
+ * state. Absent fields parse as empty; any invalid entry rejects the whole
+ * report with a reason the awaiting dispense hands back to the agent. Also
+ * rejects unrecognized top-level handoff fields: a misspelled "issueUpates"
+ * would otherwise read as an absent report and be discarded with the handoff.
+ */
+export declare function parseHandoffIssues(extras: Record<string, unknown> | undefined, state: MigrateRunState, reportingStep: MigrateStep): ParsedHandoffIssues;
+export interface IssueArchiveUpdate {
+    issueId: string;
+    stepId: string;
+    disposition: MigrateIssueDisposition;
+    note?: string;
+    detail?: string;
+    applicableMigrations?: string[];
+}
+export interface IssueApplication {
+    state: MigrateRunState;
+    newIssues: {
+        entry: MigrateRunIssue;
+        report: ReportedIssue;
+    }[];
+    updates: IssueArchiveUpdate[];
+}
+/**
+ * Mints the run issue carrying a given-up step's last failure to the completion
+ * report: unscoped and deferred, so no later step claims it, with the migration
+ * id in the summary so identical failures stay apart. A report with the same
+ * text is taken over, not merged: the fingerprint is derived from the summary,
+ * so the ledger cannot hold both, and a merge would keep the report's scope.
+ * Same locking contract as {@link applyReportedIssues}.
+ */
+export declare function mintUnresolvedIssue(state: MigrateRunState, step: MigrateStep): {
+    application: IssueApplication;
+    issueId: string;
+};
+/**
+ * Pure. Must run on state read fresh inside the fold's locked write, or ids
+ * collide and the claim checks test state that is no longer on disk.
+ */
+export declare function applyReportedIssues(state: MigrateRunState, reportingStep: MigrateStep, issues: ReportedIssue[], updates: ReportedIssueUpdate[], resolvedAtCommitCount?: number): IssueApplication;
+/**
+ * The issue ids a landed commit naming `stepIds` carries. Attribution rides on
+ * the persisted `resolvedByStepId`, so a resolution whose own commit attempt
+ * failed still reaches the later commit that absorbs that step's tree.
+ */
+export declare function issueIdsForCommit(state: MigrateRunState, stepIds: string[]): string[];
+/**
+ * Attaches the issue ids a landed entry carries; non-landed entries pass
+ * through. Every commit append (worker, fold, adopt) routes through this so
+ * attribution cannot diverge between terminal paths.
+ */
+export declare function attachIssueIdsToCommitEntry(state: MigrateRunState, entry: MigrateCommitLedgerEntry): MigrateCommitLedgerEntry;
+/**
+ * Adds to a landed entry the resolutions it can now carry, keeping the ids it
+ * has; other entries pass through. Repeating it is a no-op, since
+ * `issueIdsForCommit` skips resolutions an entry already carries.
+ */
+export declare function enrichCommitEntryIssueIds(state: MigrateRunState, index: number): MigrateRunState;
+/**
+ * Reverts resolutions not carried by a landed commit and releases claims
+ * during a reset-backed retry. Returned disposition changes form the archive
+ * trail; claim releases do not.
+ */
+export declare function reopenResolutionsForStep(state: MigrateRunState, stepId: string): {
+    state: MigrateRunState;
+    updates: IssueArchiveUpdate[];
+};
+/**
+ * Claims the still-recorded issues applicable to the step being dispensed, up
+ * to what the digest can publish. Must run inside the dispense's locked write:
+ * serial dispensing is what makes reassignment to the next applicable step
+ * deterministic when an earlier one left the issue unresolved.
+ */
+export declare function claimIssuesForStep(state: MigrateRunState, stepId: string, runId: string): MigrateRunState;
+/**
+ * Before rendering, release terminal claims and defer issues no remaining
+ * step can claim; report-time routing can become stale as steps finish. Do
+ * not archive Nx-driven progression.
+ */
+export declare function settleUnclaimableIssues(state: MigrateRunState): MigrateRunState;
+/**
+ * The bounded "Known issues" digest a work dispense carries. Assigned entries
+ * lead and share claimIssuesForStep's prefix bound, so every kept claim appears.
+ */
+export declare function renderIssueDigestLines(state: MigrateRunState, currentStepId: string, runId: string): string[];
+export declare function renderUnresolvedIssueLines(state: MigrateRunState, runId: string): string[];
+export declare function unresolvedIssues(state: MigrateRunState): MigrateRunIssue[];
+export declare function hasUnresolvedIssues(state: MigrateRunState): boolean;
+export declare function issueArchivePath(runDirPath: string, issueId: string): string;
+export declare function warnReconstructedArchives(issueIds: string[]): void;
+/**
+ * Archives an application's new issues (with the detail the ledger does not
+ * carry) and appends its updates to the archived files. Failures propagate;
+ * the caller then keeps the handoff file as the fallback detail store.
+ * `reconstructedIds` is filled as it goes rather than returned alone: a retry
+ * finds a rebuilt shell healthy, so a throw-interrupted pass is the only
+ * chance to warn that an archive was lost.
+ */
+export declare function archiveIssues(runDirPath: string, application: IssueApplication, reconstructedIds?: string[]): string[];
+/**
+ * Verifies the archive state expected after phase 1. New-issue fields must
+ * match the report and have no updates; existing-issue updates must end with
+ * this application's whole batch.
+ */
+export declare function applicationArchivesIntact(runDirPath: string, application: IssueApplication): boolean;