prismatica 0.2.0 → 0.4.0

package/dist/commands/release.js

@@ -0,0 +1,950 @@
+/**
+ * `release prepare` / `release publish` — the owner-only, deterministic npm
+ * release lifecycle. Both commands re-derive their next action from durable
+ * state (Git, the npm registry, records) on every invocation — never a
+ * stored step counter — by orchestrating real git/npm/gh calls around the
+ * pure decision tables in `releases.ts`.
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execa } from 'execa';
+import { checkStillBinds, isCheckEvidenceFile, laneRelative, nonExemptDirtyPaths } from '../assurance/proofinputs.js';
+import { assessImpact, reportGaps } from '../atlas/impact.js';
+import { listFlows } from '../atlas/store.js';
+import { listOpenChanges } from '../change.js';
+import { loadConfig } from '../config.js';
+import { UserError } from '../errors.js';
+import * as git from '../git.js';
+import { readLedger } from '../ledger.js';
+import { ledgerPath } from '../paths.js';
+import { contractPath, listContractIds, readContract, readFlowReport, releaseExists, releasePath, reportExists, writeContract, writeRelease, } from '../records/store.js';
+import { ReleaseSchema } from '../records/types.js';
+import { renderContractBody, renderReleaseBody } from '../render.js';
+import { classifyPreflight, classifySupersede, classifyVersionBumpDiff, deriveReleaseNextAction, resolveTargetVersion, } from '../releases.js';
+import { prismaticaVersion } from '../runtime.js';
+import * as ui from '../ui.js';
+import { runCheck } from './check.js';
+import { runFlowReport } from './flow.js';
+import { runFrame } from './frame.js';
+import { runShip } from './ship.js';
+function readPackageJson(dir) {
+    const parsed = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    if (typeof parsed.name !== 'string' || typeof parsed.version !== 'string') {
+        throw new UserError(`${path.join(dir, 'package.json')} has no readable name/version.`);
+    }
+    return { name: parsed.name, version: parsed.version };
+}
+// ── Lane bootstrap: make a fresh release lane's own tools resolvable ────────
+//
+// `git worktree add` never carries `node_modules` — it is gitignored, so a
+// fresh release lane has none, and Check's configured commands (`npm run
+// typecheck`, `npm run build`, …) resolve nothing until dependencies exist.
+// Deterministic, once: an existing `node_modules` is trusted as-is (never
+// reinstalled); an absent one is installed from the committed lockfile via
+// `npm ci` — the only reproducible install — and no lockfile is a fail-closed
+// refusal, never a silent `npm install` fallback that would let a release
+// resolve fresh, unpinned dependency versions.
+/** Exported so `releasebootstrap.test.ts` can prove this against a real, un-bootstrapped checkout. */
+export async function ensureLaneDependencies(home) {
+    if (fs.existsSync(path.join(home, 'node_modules'))) {
+        return;
+    }
+    if (!fs.existsSync(path.join(home, 'package-lock.json'))) {
+        throw new UserError(`${home} has no node_modules and no package-lock.json — deterministic release bootstrap requires a committed lockfile.`, {
+            command: 'npm install',
+            why: '`npm ci` is the only reproducible install; run `npm install` once to generate package-lock.json, commit it, and rerun `release prepare` — never a silent `npm install` fallback here',
+        });
+    }
+    const result = await execa('npm', ['ci'], { cwd: home, reject: false, all: true });
+    if (result.failed) {
+        throw new UserError(`\`npm ci\` failed to bootstrap ${home}: ${(result.all || result.stderr || result.stdout).trim()}`, {
+            command: 'npm ci',
+            why: 'the lane must be installable before Check can run the repo’s real typecheck/lint/unit/build commands',
+        });
+    }
+}
+// ── The npm registry seam ────────────────────────────────────────────────
+//
+// Minimal, real npm CLI queries. Deliberately not imported by
+// `assurance/mainpush.ts` (nor the reverse) — see that module's own comment
+// on why the two literal copies exist.
+/** npm's own genuine-404 wording — anything else (offline, rate-limited, malformed) is uncertain. */
+const NPM_NOT_FOUND = /E404|404 Not Found|is not in (?:this|the) registry/i;
+async function npmPublicIntegrity(pkgName, version) {
+    const result = await execa('npm', ['view', `${pkgName}@${version}`, 'dist.integrity', '--json'], {
+        reject: false,
+    });
+    if (result.failed) {
+        return NPM_NOT_FOUND.test(`${result.stderr}${result.stdout}`) ? { state: 'absent' } : { state: 'uncertain' };
+    }
+    try {
+        const parsed = JSON.parse(result.stdout);
+        return typeof parsed === 'string' && parsed.length > 0 ? { state: 'present', integrity: parsed } : { state: 'uncertain' };
+    }
+    catch {
+        return { state: 'uncertain' };
+    }
+}
+function parseVersionsJson(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        if (typeof parsed === 'string') {
+            return [parsed]; // npm collapses a single published version to a bare string
+        }
+        return Array.isArray(parsed) && parsed.every((v) => typeof v === 'string') ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function npmDistTags(pkgName) {
+    const result = await execa('npm', ['view', pkgName, 'dist-tags', '--json'], { reject: false });
+    if (result.failed) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(result.stdout);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            return null;
+        }
+        const entries = Object.entries(parsed);
+        return entries.every(([, v]) => typeof v === 'string') ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `null` = could not be answered. Fails closed on any entry it cannot read id/version from. */
+async function npmStagedCandidates(pkgName) {
+    const result = await execa('npm', ['stage', 'list', pkgName, '--json'], { reject: false });
+    if (result.failed) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(parsed)) {
+        return null;
+    }
+    const candidates = [];
+    for (const entry of parsed) {
+        if (typeof entry !== 'object' || entry === null) {
+            return null;
+        }
+        const e = entry;
+        if (typeof e.id !== 'string' || e.id.length === 0 || typeof e.version !== 'string' || e.version.length === 0) {
+            return null;
+        }
+        candidates.push({ id: e.id, version: e.version, tag: typeof e.tag === 'string' ? e.tag : undefined });
+    }
+    return candidates;
+}
+/**
+ * The one registry probe both `prepare` and `publish` build their facts from.
+ * The FIRST query (public versions) is the reachability probe: an outright
+ * failure (network/DNS/registry down) means unreachable; a successful call
+ * whose shape cannot be trusted, or a later query that separately fails,
+ * surfaces as `null` in its own field — "uncertain", never "unreachable".
+ */
+async function queryRegistry(pkgName) {
+    const versionsResult = await execa('npm', ['view', pkgName, 'versions', '--json'], { reject: false });
+    if (versionsResult.failed) {
+        return { reachable: false, publicVersions: null, distTags: null, stagedCandidates: null };
+    }
+    return {
+        reachable: true,
+        publicVersions: parseVersionsJson(versionsResult.stdout),
+        distTags: await npmDistTags(pkgName),
+        stagedCandidates: await npmStagedCandidates(pkgName),
+    };
+}
+/** ~25s bounded wait: enough for ordinary registry propagation lag, never unbounded. */
+const DEFAULT_POLL = { attempts: 6, delayMs: 5000 };
+async function sleep(ms) {
+    if (ms > 0) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+// ── The release workflow's own run, identified deterministically ──────────
+//
+// `prismatica-release.yml` declares `run-name: "Release ${{
+// github.event.inputs.version }}"`, so `gh run list`'s `displayTitle` names
+// exactly the version it was dispatched for — a rerun can tell "a run THIS
+// release already triggered" apart from any other run of this workflow,
+// never guessing from "whatever ran most recently".
+/** Exported so a test can prove this matches `prismatica-release.yml`'s own `run-name:` — two independent copies of the same format would silently drift apart. */
+export function releaseRunTitle(version) {
+    return `Release ${version}`;
+}
+/**
+ * Runs of `prismatica-release.yml` whose title matches `version`, newest
+ * first. `null` = the query could not be answered — fails closed, never
+ * "assume no run exists".
+ */
+async function findReleaseWorkflowRuns(mainRoot, version) {
+    const result = await execa('gh', ['run', 'list', '--workflow', 'prismatica-release.yml', '--json', 'status,conclusion,displayTitle,event,url', '-L', '30'], { cwd: mainRoot, reject: false });
+    if (result.failed) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(parsed)) {
+        return null;
+    }
+    const runs = [];
+    for (const entry of parsed) {
+        if (typeof entry !== 'object' || entry === null) {
+            return null;
+        }
+        const e = entry;
+        if (e.event !== 'workflow_dispatch' || e.displayTitle !== releaseRunTitle(version)) {
+            continue;
+        }
+        if (typeof e.status !== 'string') {
+            return null;
+        }
+        runs.push({
+            status: e.status,
+            conclusion: typeof e.conclusion === 'string' && e.conclusion.length > 0 ? e.conclusion : null,
+            url: typeof e.url === 'string' ? e.url : '',
+        });
+    }
+    return runs;
+}
+/**
+ * Whether `dispatch-workflow` may safely fire another dispatch — re-derived
+ * from the matching run's OWN state every time, never a stored step counter.
+ * `'dispatch'`: no run this release ever triggered, or the one it did fail
+ * closed/cancelled — the documented recovery. `'proceed'`: the workflow's
+ * work (or a later approval) is already visible in the staged or public
+ * namespace — the caller re-derives its next action from fresh facts rather
+ * than this function acting on stale state itself. A queued/in-progress run,
+ * or one that succeeded but has not yet produced a visible staged candidate,
+ * is bounded-observed (never busy-looped, never waited on forever); GitHub
+ * query uncertainty is retried within the same bound, never treated as proof
+ * no run exists.
+ */
+async function resolveDispatchDecision(mainRoot, pkgName, version, poll) {
+    let lastRun; // undefined = never successfully queried
+    for (let attempt = 0; attempt < poll.attempts; attempt += 1) {
+        const runs = await findReleaseWorkflowRuns(mainRoot, version);
+        if (runs !== null) {
+            lastRun = runs[0] ?? null;
+            if (lastRun === null) {
+                return 'dispatch';
+            }
+            const registry = await queryRegistry(pkgName);
+            const visible = (registry.stagedCandidates?.some((candidate) => candidate.version === version) ?? false) ||
+                (registry.publicVersions?.includes(version) ?? false);
+            if (visible) {
+                return 'proceed';
+            }
+            if (lastRun.status === 'completed' && lastRun.conclusion !== 'success') {
+                return 'dispatch';
+            }
+        }
+        if (attempt < poll.attempts - 1) {
+            await sleep(poll.delayMs);
+        }
+    }
+    if (!lastRun) {
+        // `lastRun === null` is unreachable (that branch returns 'dispatch'
+        // immediately above) — this guard exists for TypeScript's narrowing.
+        throw new UserError(`Could not confirm whether ${version}'s release workflow has already run — fails closed.`, {
+            command: `gh run list --workflow prismatica-release.yml`,
+            why: 'GitHub Actions state must be readable before deciding whether another dispatch is safe',
+        });
+    }
+    throw new UserError(`${version}'s release workflow (${lastRun.status}${lastRun.conclusion ? `, ${lastRun.conclusion}` : ''}) has not produced a staged candidate after a bounded wait — fails closed.`, {
+        command: lastRun.url ? `open ${lastRun.url}` : `gh run list --workflow prismatica-release.yml`,
+        why: 'a rerun must not dispatch another run while an existing one may still be working',
+    });
+}
+async function dispatchReleaseWorkflow(mainRoot, mainBranch, version) {
+    const result = await execa('gh', ['workflow', 'run', 'prismatica-release.yml', '--ref', mainBranch, '-f', `version=${version}`], { cwd: mainRoot, reject: false });
+    if (result.failed) {
+        throw new UserError(`Could not dispatch the release workflow: ${(result.stderr || result.stdout).trim()}`, {
+            command: `gh workflow run prismatica-release.yml --ref ${mainBranch} -f version=${version}`,
+            why: 'the workflow definition always runs from main and builds/stages the tagged commit',
+        });
+    }
+}
+/**
+ * `os.tmpdir()` honours `TMPDIR`, which is not guaranteed to point outside
+ * the repository — if it does, `mkdtemp` would create the download directory
+ * inside the working tree. Compares canonical (symlink-resolved) paths, not
+ * strings: a lexically different path that resolves back inside the repo is
+ * still inside it, and containment (not mere inequality) is what the
+ * download must never violate.
+ */
+function assertOutsideRepo(dir, repoRoot) {
+    const repoReal = fs.realpathSync(repoRoot);
+    const dirReal = fs.realpathSync(dir);
+    const rel = path.relative(repoReal, dirReal);
+    const isInside = rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+    if (isInside) {
+        fs.rmSync(dirReal, { recursive: true, force: true });
+        throw new UserError(`The system temporary directory (${dirReal}) resolves inside the repository at ${repoReal} — refusing to download the staged tarball there.`, {
+            command: 'echo $TMPDIR',
+            why: 'the staged artifact must never be downloaded into the user’s repository, even when TMPDIR points inside it',
+        });
+    }
+}
+/**
+ * npm 11's `stage download` supports only `[--json] [--registry <registry>]`
+ * — no `--output` — and always writes `<pkg>-<version>-<stage-id>.tgz` into
+ * its OWN process working directory, silently ignoring any unknown flag.
+ * Running it with `cwd` set to a fresh, private, empty temp directory and
+ * reading that directory back is therefore the only honest way to capture
+ * exactly what npm wrote — never into the owner's repository, and never
+ * trusting a specific filename npm did not document. `assertOutsideRepo`
+ * proves that directory is genuinely outside the repo, by canonical path,
+ * BEFORE npm ever runs.
+ *
+ * Exported so `releasedownload.test.ts` can prove this against a real
+ * process boundary (a fake `npm` on PATH), not a mock that assumes
+ * `--output` works.
+ */
+export async function downloadStagedTarball(repoRoot, stagedId) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'prismatica-release-'));
+    assertOutsideRepo(dir, repoRoot);
+    const result = await execa('npm', ['stage', 'download', stagedId], { cwd: dir, reject: false });
+    const candidates = fs.readdirSync(dir).filter((name) => name.endsWith('.tgz'));
+    if (result.failed || candidates.length !== 1) {
+        const found = candidates.length === 0 ? 'no .tgz file was written' : `${candidates.length} candidates: ${candidates.join(', ')}`;
+        throw new UserError(`Could not download the staged tarball for ${stagedId}: ${result.failed ? (result.stderr || result.stdout).trim() : found}`, {
+            command: `npm stage download ${stagedId}`,
+            why: 'the staged artifact must be re-proven offline before it is safe to approve, and exactly one candidate tarball must be unambiguous',
+        });
+    }
+    return path.join(dir, candidates[0]);
+}
+/**
+ * Downloads package@version's PUBLIC tarball from the registry — used only by
+ * the approved-unrecorded recovery path, which has no staged digest left to
+ * trust and must re-prove the now-public artifact itself. `npm pack` on a
+ * registry spec fetches and saves the exact published bytes (verified against
+ * a real published version: its sha512 SRI equals what `npm view
+ * dist.integrity` reports) — never a local repack.
+ */
+async function downloadPublicTarball(pkgName, version) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'prismatica-release-public-'));
+    const result = await execa('npm', ['pack', `${pkgName}@${version}`, '--pack-destination', dir, '--json'], { reject: false });
+    if (result.failed) {
+        throw new UserError(`Could not download the public tarball for ${pkgName}@${version}: ${(result.stderr || result.stdout).trim()}`, {
+            command: `npm pack ${pkgName}@${version} --pack-destination ${dir} --json`,
+            why: 'recovery without a staged artifact must re-prove the now-public tarball, never trust the registry’s own report of its digest',
+        });
+    }
+    let filename;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        const first = Array.isArray(parsed) ? parsed[0] : undefined;
+        filename = typeof first?.filename === 'string' ? first.filename : null;
+    }
+    catch {
+        filename = null;
+    }
+    const tarballPath = filename ? path.join(dir, filename) : null;
+    if (!tarballPath || !fs.existsSync(tarballPath)) {
+        throw new UserError(`\`npm pack ${pkgName}@${version}\` did not produce a readable tarball.`, {
+            command: `npm pack ${pkgName}@${version} --pack-destination ${dir} --json`,
+            why: 'recovery cannot write a record for an artifact it could not download',
+        });
+    }
+    return tarballPath;
+}
+function sha512Sri(filePath) {
+    const digest = createHash('sha512').update(fs.readFileSync(filePath)).digest('base64');
+    return `sha512-${digest}`;
+}
+/**
+ * Every mismatch between an extracted tarball's `package/` directory and the
+ * production dependency tree `lockPath` promises — empty means the tarball is
+ * exactly what the lock file says. A repo with no lock file has nothing to
+ * verify this way (`[]`), rather than an error.
+ *
+ * Exported so `release.test.ts`'s own packaged-artifact proof and this
+ * module's staged-tarball re-proof apply exactly the same check — never two
+ * independent approximations of it.
+ */
+export function verifyTarballAgainstLock(extractedPackageDir, lockPath) {
+    if (!fs.existsSync(lockPath)) {
+        return [];
+    }
+    let lock;
+    try {
+        lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+    }
+    catch {
+        return [`${lockPath} is not readable JSON`];
+    }
+    const problems = [];
+    for (const [installPath, entry] of Object.entries(lock.packages ?? {})) {
+        if (installPath === '' || entry.dev || entry.devOptional || entry.optional || !entry.version) {
+            continue;
+        }
+        const bundled = path.join(extractedPackageDir, installPath, 'package.json');
+        if (!fs.existsSync(bundled)) {
+            problems.push(`${installPath}: not bundled at all`);
+            continue;
+        }
+        let actual;
+        try {
+            actual = JSON.parse(fs.readFileSync(bundled, 'utf8')).version;
+        }
+        catch {
+            problems.push(`${installPath}: bundled package.json is not readable JSON`);
+            continue;
+        }
+        if (actual !== entry.version) {
+            problems.push(`${installPath}: bundled ${actual}, lock says ${entry.version}`);
+        }
+    }
+    return problems;
+}
+/**
+ * Extracts `tarballPath` and re-proves its contents against
+ * `package-lock.json` — offline. Used both for the staged artifact before
+ * 2FA approval and, during approved-unrecorded recovery, for the public
+ * tarball downloaded in its place — one comparison, never two independent
+ * approximations of it. `context` names which for error messages only
+ * (`'staged'` / `'public'`).
+ */
+async function reproveTarball(mainRoot, tarballPath, context) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'prismatica-release-reprove-'));
+    const extracted = path.join(dir, 'extracted');
+    fs.mkdirSync(extracted, { recursive: true });
+    const untarred = await execa('tar', ['-xzf', tarballPath, '-C', extracted], { reject: false });
+    if (untarred.failed) {
+        throw new UserError(`Could not extract the ${context} tarball: ${(untarred.stderr || untarred.stdout).trim()}`, {
+            command: `tar -xzf ${tarballPath} -C ${extracted}`,
+            why: `the ${context} artifact must be re-proven offline before it is safe to trust`,
+        });
+    }
+    const problems = verifyTarballAgainstLock(path.join(extracted, 'package'), path.join(mainRoot, 'package-lock.json'));
+    if (problems.length > 0) {
+        throw new UserError(`The ${context} tarball does not match package-lock.json: ${problems.join('; ')}`, {
+            command: `tar -tzf ${tarballPath}`,
+            why: 'an artifact whose bundled dependencies disagree with the lock file is never safe to trust',
+        });
+    }
+}
+/** `npm stage approve` — the one consequential step, gated by npm's own interactive 2FA prompt. */
+async function npmStageApprove(stagedId) {
+    const result = await execa('npm', ['stage', 'approve', stagedId], { reject: false, stdio: 'inherit' });
+    if (result.failed) {
+        throw new UserError(`\`npm stage approve ${stagedId}\` did not succeed.`, {
+            command: `npm stage approve ${stagedId}`,
+            why: 'the owner completes this interactively, behind npm’s own 2FA prompt',
+        });
+    }
+}
+/**
+ * The one release Prismatica knows about right now, wherever it is in its
+ * lifecycle — an open lane not yet merged, or a merged contract with no
+ * release record yet. "One release in flight at a time" (the plan's own
+ * assumption) is what makes this unambiguous.
+ */
+async function findReleaseInFlight(mainRoot) {
+    for (const change of await listOpenChanges(mainRoot)) {
+        const { data: contract } = readContract(change.home, change.id);
+        if (contract.releaseVersion) {
+            return { contractId: change.id, version: contract.releaseVersion, home: change.home, kind: 'lane' };
+        }
+    }
+    for (const id of listContractIds(mainRoot)) {
+        const { data: contract } = readContract(mainRoot, id);
+        if (contract.releaseVersion && !releaseExists(mainRoot, contract.releaseVersion)) {
+            return { contractId: id, version: contract.releaseVersion, home: mainRoot, kind: 'merged' };
+        }
+    }
+    return null;
+}
+/**
+ * The most recently merged release contract, regardless of whether it has
+ * already been recorded — what `release publish` targets. Unlike
+ * `findReleaseInFlight` (which stops caring about a release the instant it is
+ * recorded, so `release prepare`'s preflight correctly allows a fresh one to
+ * start), `publish` must still recognise a JUST-finished release long enough
+ * to answer "already live and recorded" instead of the less honest "nothing
+ * to publish". `listContractIds` sorts ascending by id, and ids are
+ * date-prefixed, so the last match is the newest.
+ */
+function latestMergedReleaseContract(mainRoot) {
+    const ids = listContractIds(mainRoot);
+    for (let i = ids.length - 1; i >= 0; i -= 1) {
+        const { data: contract } = readContract(mainRoot, ids[i]);
+        if (contract.releaseVersion) {
+            return { contractId: ids[i], version: contract.releaseVersion };
+        }
+    }
+    return null;
+}
+async function mainIsCurrent(mainRoot, mainBranch) {
+    const upstream = `origin/${mainBranch}`;
+    if (!(await git.refExists(mainRoot, upstream))) {
+        return true; // no remote to be behind
+    }
+    return (await git.behindCount(mainRoot, mainBranch, upstream)) === 0;
+}
+/** Same filter `frame.ts` applies: Prismatica's own records are expected dirty between commands. */
+async function mainIsClean(mainRoot) {
+    const dirtyCode = (await git.dirtyPaths(mainRoot)).filter((file) => !file.startsWith('.prismatica/'));
+    return dirtyCode.length === 0;
+}
+async function gatherPreflightFacts(mainRoot, mainBranch, pkgName, targetVersion, mainVersion, unfinishedReleaseInFlight) {
+    const mainClean = await mainIsClean(mainRoot);
+    const mainCurrent = await mainIsCurrent(mainRoot, mainBranch);
+    const targetTagExists = await git.tagExists(mainRoot, `v${targetVersion}`);
+    const registry = await queryRegistry(pkgName);
+    return {
+        targetVersion,
+        mainVersion,
+        mainClean,
+        mainCurrent,
+        registryReachable: registry.reachable,
+        publicVersions: registry.publicVersions,
+        distTags: registry.distTags,
+        stagedCandidates: registry.stagedCandidates,
+        targetTagExists,
+        unfinishedReleaseInFlight,
+    };
+}
+function preflightRefusal(verdict) {
+    if (verdict.reason === 'target-staged') {
+        return new UserError(verdict.detail, {
+            command: `npm stage reject ${verdict.stagedCandidate.id}`,
+            why: 'continue that release with `prismatica release publish`, or reject it (owner-interactive, 2FA) and rerun `release prepare`',
+        });
+    }
+    if (verdict.reason === 'unfinished-release') {
+        return new UserError(verdict.detail, {
+            command: 'prismatica next',
+            why: 'finish the release in flight with `release publish`, close a merged-but-unpublished one with `release prepare --supersede`, or `abandon` an unmerged lane that targeted the wrong version',
+        });
+    }
+    return new UserError(verdict.detail);
+}
+function supersedeRefusal(verdict) {
+    if (verdict.reason === 'target-staged') {
+        return new UserError(verdict.detail, {
+            command: `npm stage reject ${verdict.stagedCandidate.id}`,
+            why: 'reject the stage (owner-interactive, 2FA), then rerun `release prepare --supersede`',
+        });
+    }
+    if (verdict.reason === 'target-public') {
+        return new UserError(verdict.detail, {
+            command: 'prismatica release publish',
+            why: 'the version is already public — record it, never supersede it',
+        });
+    }
+    return new UserError(verdict.detail);
+}
+// ── Flow Report: only when impact demands it, and only what is derivable ───
+async function ensureFlowReport(home, contract) {
+    const changedFiles = await git.changedFilesSince(home, contract.baseline.commit, git.EXCLUDE_RECORDS);
+    const { flows } = listFlows(home);
+    const impact = assessImpact(changedFiles, flows);
+    const existing = reportExists(home, contract.id) ? readFlowReport(home, contract.id).data : null;
+    if (reportGaps(impact, existing).length === 0) {
+        return;
+    }
+    await runFlowReport({ cwd: home, contractId: contract.id, auto: true });
+    const after = reportExists(home, contract.id) ? readFlowReport(home, contract.id).data : null;
+    const gaps = reportGaps(impact, after);
+    if (gaps.length > 0) {
+        throw new UserError(`This release's diff needs a person's answer before it can proceed: ${gaps.join('; ')}`, {
+            command: 'prismatica flow report --flow <id> --status unchanged --reason "..."',
+            why: 'no file diff can establish whether behaviour changed — `--auto` already recorded everything it honestly could',
+        });
+    }
+}
+// ── Check: skip only when a passing check still binds the current HEAD ─────
+async function checkAlreadyBinds(home, contract) {
+    const mine = readLedger(home).entries.filter((entry) => entry.contractId === contract.id && entry.event === 'check_run');
+    const latest = mine.at(-1);
+    if (!latest || !latest.pass || !latest.checkedHead) {
+        return false;
+    }
+    return checkStillBinds(home, contract, latest.checkedHead);
+}
+export async function runReleasePrepare(options) {
+    const mainRoot = await git.mainRepoRoot(options.cwd);
+    const config = loadConfig(mainRoot);
+    const pkgName = readPackageJson(mainRoot).name;
+    if (options.supersede) {
+        return runSupersede(mainRoot, pkgName);
+    }
+    if (!options.target) {
+        throw new UserError('Tell release prepare what to bump: `patch`, `minor`, `major`, or `--version X.Y.Z`.', {
+            command: 'prismatica release prepare minor',
+            why: 'there is no default bump kind',
+        });
+    }
+    const mainVersion = readPackageJson(mainRoot).version;
+    let targetVersion;
+    try {
+        targetVersion = resolveTargetVersion(mainVersion, options.target);
+    }
+    catch (error) {
+        throw new UserError(error instanceof Error ? error.message : String(error));
+    }
+    const inFlight = await findReleaseInFlight(mainRoot);
+    const resuming = inFlight?.kind === 'lane' && inFlight.version === targetVersion;
+    let home;
+    let contract;
+    if (resuming) {
+        home = inFlight.home;
+        ({ data: contract } = readContract(home, inFlight.contractId));
+    }
+    else {
+        const facts = await gatherPreflightFacts(mainRoot, config.mainBranch, pkgName, targetVersion, mainVersion, inFlight !== null);
+        const verdict = classifyPreflight(facts);
+        if (!verdict.ok) {
+            throw preflightRefusal(verdict);
+        }
+        const framed = await runFrame({
+            cwd: mainRoot,
+            title: `Release ${targetVersion}`,
+            issue: `release/${targetVersion}`,
+            allowedPaths: ['package.json', 'package-lock.json'],
+            acceptanceChecks: [
+                { id: 'ac-1', description: `npm publishes ${targetVersion}`, test: 'manual:OWNER' },
+            ],
+            answers: { touchesAuth: false, touchesPayments: false, touchesSavedData: false, copyOnly: false },
+            tierOverride: 'light',
+            installHook: false,
+            now: options.now,
+        });
+        home = framed.worktree;
+        contract = { ...framed.contract, releaseVersion: targetVersion };
+        writeContract(home, contract, renderContractBody(contract));
+    }
+    // `npm version` — idempotent: skip once the working tree already reads the target.
+    if (readPackageJson(home).version !== targetVersion) {
+        const bumped = await execa('npm', ['version', targetVersion, '--no-git-tag-version', '--allow-same-version'], { cwd: home, reject: false });
+        if (bumped.failed) {
+            throw new UserError(`\`npm version ${targetVersion}\` failed: ${(bumped.stderr || bumped.stdout).trim()}`);
+        }
+    }
+    await ensureFlowReport(home, contract);
+    // Exact-path checkpoint commit — every Check input this release-prepare
+    // transaction produced (package.json, package-lock.json if npm touched it,
+    // the framed contract, the Flow report if one was written).
+    const checkpoint = await nonExemptDirtyPaths(home, contract);
+    if (checkpoint.blocked) {
+        throw new UserError('A rename or unmerged conflict sits among this release’s own uncommitted files.', { command: `git -C ${home} status`, why: 'a checkpoint commit cannot safely resolve either automatically' });
+    }
+    if (checkpoint.paths.length > 0) {
+        await git.commitPaths(home, checkpoint.paths, `release: checkpoint ${targetVersion}`);
+    }
+    if (!(await checkAlreadyBinds(home, contract))) {
+        await ensureLaneDependencies(home);
+        const checked = await runCheck({ cwd: home, contractId: contract.id });
+        if (!checked.result.pass) {
+            throw new UserError('Check failed — fix what failed, then rerun `release prepare`.', {
+                command: `prismatica check ${contract.id}`,
+                why: 'a release only ever ships proven work',
+            });
+        }
+    }
+    // Exact-path record commit — ONLY Check's own durable outputs (the
+    // evidence file, the appended ledger line, the contract's stage bump to
+    // `prove`), never a general "whatever is dirty" sweep: a stray file in the
+    // lane must never ride into this commit. `dirtyEntries`, never
+    // `dirtyPaths`: a brand-new evidence directory (this lane's FIRST check)
+    // collapses to one porcelain line for the directory itself under plain
+    // `dirtyPaths`, hiding the individual evidence file `isCheckEvidenceFile`
+    // needs to see.
+    const contractRel = laneRelative(home, contractPath(home, contract.id));
+    const ledgerRel = laneRelative(home, ledgerPath(home));
+    const recordPaths = (await git.dirtyEntries(home))
+        .map((entry) => entry.path)
+        .filter((p) => isCheckEvidenceFile(home, contract.id, p) || p === ledgerRel || p === contractRel);
+    if (recordPaths.length > 0) {
+        await git.commitPaths(home, recordPaths, `release: check evidence for ${targetVersion}`);
+    }
+    const shipReport = await runShip({ cwd: home, contractId: contract.id });
+    if (!shipReport.shipped) {
+        throw new UserError('The gate is not satisfied yet — see the requirements above.', {
+            command: `prismatica gate ${contract.id}`,
+            why: 'release prepare ships through the same gate every change does',
+        });
+    }
+    return { action: 'shipped', contractId: contract.id, version: targetVersion, prUrl: shipReport.prUrl };
+}
+async function runSupersede(mainRoot, pkgName) {
+    const inFlight = await findReleaseInFlight(mainRoot);
+    if (!inFlight || inFlight.kind !== 'merged') {
+        throw new UserError('There is no merged, unfinished release to supersede.', {
+            command: 'prismatica next',
+            why: 'supersede closes a release that has already merged but never published — an unmerged lane is closed with `abandon` instead',
+        });
+    }
+    if (releaseExists(mainRoot, inFlight.version)) {
+        throw new UserError(`A release record for ${inFlight.version} already exists — releases are write-once.`);
+    }
+    const registry = await queryRegistry(pkgName);
+    const facts = {
+        targetVersion: inFlight.version,
+        publicVersions: registry.publicVersions,
+        stagedCandidates: registry.stagedCandidates,
+    };
+    const verdict = classifySupersede(facts);
+    if (!verdict.ok) {
+        throw supersedeRefusal(verdict);
+    }
+    const release = ReleaseSchema.parse({
+        version: inFlight.version,
+        contractId: inFlight.contractId,
+        outcome: 'superseded',
+        at: new Date().toISOString(),
+        recoveryRoutes: [],
+        prismaticaVersion: prismaticaVersion(),
+    });
+    writeRelease(mainRoot, release, renderReleaseBody(release));
+    return { action: 'superseded', contractId: inFlight.contractId, version: inFlight.version };
+}
+export function printReleasePrepareReport(report) {
+    if (report.action === 'superseded') {
+        console.log(ui.ok(`✓ ${report.version} superseded`));
+        console.log(`  ${ui.bold('contract')}  ${report.contractId}`);
+        console.log('');
+        console.log(ui.dim(`  commit the release record: git add .prismatica/releases/${report.version}.md`));
+        return;
+    }
+    console.log(ui.ok(`✓ release ${report.version} shipped`));
+    console.log(`  ${ui.bold('contract')}  ${report.contractId}`);
+    if (report.prUrl) {
+        console.log(`  ${ui.bold('PR')}        ${report.prUrl}`);
+    }
+    console.log('');
+    console.log(ui.dim('  gate → merge → close, then `prismatica release publish` once it is on main.'));
+}
+async function verifyPureVersionBump(mainRoot, contract, expectedVersion) {
+    const changed = await git.diffNames(mainRoot, contract.baseline.commit, 'HEAD', git.EXCLUDE_RECORDS);
+    const oldPkgText = await git.showFile(mainRoot, contract.baseline.commit, 'package.json');
+    const newPkgText = await git.showFile(mainRoot, 'HEAD', 'package.json');
+    const touchesLock = changed.includes('package-lock.json');
+    const oldLockText = touchesLock ? await git.showFile(mainRoot, contract.baseline.commit, 'package-lock.json') : null;
+    const newLockText = touchesLock ? await git.showFile(mainRoot, 'HEAD', 'package-lock.json') : null;
+    const verdict = classifyVersionBumpDiff({
+        changedNonRecordFiles: changed,
+        oldPackageJson: oldPkgText ? JSON.parse(oldPkgText) : null,
+        newPackageJson: newPkgText ? JSON.parse(newPkgText) : null,
+        oldLock: oldLockText ? JSON.parse(oldLockText) : null,
+        newLock: newLockText ? JSON.parse(newLockText) : null,
+        expectedVersion,
+    });
+    if (!verdict.pure) {
+        throw new UserError(`The merged diff for "${contract.id}" is not a pure version bump: ${verdict.reason}`, {
+            command: `git diff ${contract.baseline.commit}..HEAD -- . ':(exclude).prismatica'`,
+            why: 'a release only ever tags a commit whose non-record diff is exactly the version transformation',
+        });
+    }
+}
+async function reconstructRecord(mainRoot, contract, version, pkgName, evidence) {
+    const query = await npmPublicIntegrity(pkgName, version);
+    if (query.state !== 'present') {
+        throw new UserError(`${pkgName}@${version} is not confirmed public yet — fails closed.`, {
+            command: `npm view ${pkgName}@${version} dist.integrity`,
+            why: 'the terminal record is only written once the registry itself confirms the artifact',
+        });
+    }
+    if (evidence.tier === 'staged-approval') {
+        if (query.integrity !== evidence.expectedIntegrity) {
+            throw new UserError(`${pkgName}@${version}'s public dist.integrity does not match the staged artifact re-proved before approval — fails closed.`, {
+                command: `npm view ${pkgName}@${version} dist.integrity`,
+                why: 'the exact staged artifact re-proved before owner 2FA approval must be the exact artifact npm confirms public afterward',
+            });
+        }
+    }
+    else {
+        // No staged digest survives past `stage approve` — the staged candidate
+        // disappears the instant it succeeds. The only honest proof left is
+        // downloading the now-public tarball and re-hashing it ourselves; trusting
+        // the registry's own report of its digest would be exactly the unproven
+        // claim this recovery path exists to avoid.
+        const tarballPath = await downloadPublicTarball(pkgName, version);
+        await reproveTarball(mainRoot, tarballPath, 'public');
+        const computed = sha512Sri(tarballPath);
+        if (computed !== query.integrity) {
+            throw new UserError(`${pkgName}@${version}'s downloaded tarball hashes to ${computed}, which does not match the registry's reported dist.integrity (${query.integrity}) — fails closed.`, {
+                command: `npm pack ${pkgName}@${version} --pack-destination <dir> --json`,
+                why: 'the approved-unrecorded recovery path only writes a record for an artifact it has independently re-proved, never one it merely read a report of',
+            });
+        }
+    }
+    const distTags = await npmDistTags(pkgName);
+    if (!distTags || distTags.latest !== version) {
+        throw new UserError(`${pkgName}'s "latest" dist-tag does not confirm ${version} — fails closed.`, {
+            command: `npm view ${pkgName} dist-tags`,
+            why: 'the record only claims what the registry itself has already made true',
+        });
+    }
+    const tag = `v${version}`;
+    if (!(await git.tagExists(mainRoot, tag))) {
+        throw new UserError(`${tag} does not exist — fails closed.`, {
+            command: `git tag -l ${tag}`,
+            why: 'a published release record must bind to the immutable Git tag/commit that produced it, never to npm publicity alone',
+        });
+    }
+    const commit = await git.revParse(mainRoot, tag);
+    const manifestText = await git.showFile(mainRoot, commit, 'package.json');
+    const manifestVersion = manifestText ? JSON.parse(manifestText).version : null;
+    if (manifestVersion !== version) {
+        throw new UserError(`${tag} resolves to a commit whose package.json version ("${String(manifestVersion)}") does not match ${version} — fails closed.`, {
+            command: `git show ${tag}:package.json`,
+            why: 'the tag, its commit and the published version must all agree before a published record is written',
+        });
+    }
+    const release = ReleaseSchema.parse({
+        version,
+        contractId: contract.id,
+        outcome: 'published',
+        commit,
+        tag,
+        integrity: query.integrity,
+        distTag: 'latest',
+        at: new Date().toISOString(),
+        recoveryRoutes: [],
+        prismaticaVersion: prismaticaVersion(),
+    });
+    writeRelease(mainRoot, release, renderReleaseBody(release));
+    return {
+        action: 'reconstruct-record-from-public',
+        version,
+        detail: `${pkgName}@${version} is public — release record written`,
+        release,
+    };
+}
+async function awaitApproval(mainRoot, contract, version, staged, pkgName, poll) {
+    const tarballPath = await downloadStagedTarball(mainRoot, staged.id);
+    await reproveTarball(mainRoot, tarballPath, 'staged');
+    const digest = sha512Sri(tarballPath);
+    console.log(ui.bold('Staged release evidence'));
+    console.log(`  ${ui.bold('version')}    ${version}`);
+    console.log(`  ${ui.bold('stage')}      ${staged.id} (tagged ${staged.tag ?? '(unreadable)'})`);
+    console.log(`  ${ui.bold('digest')}     ${digest}`);
+    console.log('');
+    await npmStageApprove(staged.id);
+    // Bounded wait for public visibility WHILE `digest` — the staged artifact's
+    // own re-proved integrity — stays in scope. Approval already succeeded:
+    // returning normally here would silently discard the one fact that makes
+    // the eventual record honest, and a LATER rerun could never recompute it
+    // (the staged candidate disappears the instant approval succeeds). A
+    // mismatch found mid-poll refuses immediately, via `reconstructRecord`,
+    // rather than being retried away.
+    for (let attempt = 0; attempt < poll.attempts; attempt += 1) {
+        const registry = await queryRegistry(pkgName);
+        if (registry.publicVersions?.includes(version)) {
+            return reconstructRecord(mainRoot, contract, version, pkgName, {
+                tier: 'staged-approval',
+                expectedIntegrity: digest,
+            });
+        }
+        if (attempt < poll.attempts - 1) {
+            await sleep(poll.delayMs);
+        }
+    }
+    throw new UserError(`${pkgName}@${version} was approved but has not shown public after a bounded wait — fails closed.`, {
+        command: `npm view ${pkgName}@${version} dist.integrity`,
+        why: 'confirm the version is public before rerunning `prismatica release publish` — a rerun while it is still propagating may re-dispatch the release workflow rather than recover; once the registry shows it public, rerunning independently re-proves the artifact rather than trusting a digest this process can no longer hold',
+    });
+}
+export async function runReleasePublish(options) {
+    const mainRoot = await git.mainRepoRoot(options.cwd);
+    const config = loadConfig(mainRoot);
+    const pkgName = readPackageJson(mainRoot).name;
+    const poll = options.poll ?? DEFAULT_POLL;
+    const latest = latestMergedReleaseContract(mainRoot);
+    if (!latest) {
+        throw new UserError('No merged release is waiting to be published.', {
+            command: 'prismatica release prepare <patch|minor|major>',
+            why: 'release publish only ever continues a release that has already merged',
+        });
+    }
+    const { data: contract } = readContract(mainRoot, latest.contractId);
+    const version = latest.version;
+    const tag = `v${version}`;
+    const registry = await queryRegistry(pkgName);
+    const facts = {
+        version,
+        intendedTag: 'latest',
+        tagExists: await git.tagExists(mainRoot, tag),
+        publicVersions: registry.publicVersions,
+        distTags: registry.distTags,
+        stagedCandidates: registry.stagedCandidates,
+        recordExists: releaseExists(mainRoot, version),
+    };
+    const next = deriveReleaseNextAction(facts);
+    switch (next.action) {
+        case 'already-recorded':
+            throw new UserError(`${version} is already live and recorded.`, {
+                command: `cat ${releasePath(mainRoot, version)}`,
+                why: 'releases are write-once',
+            });
+        case 'query-uncertain':
+            throw new UserError(next.detail);
+        case 'create-tag-and-dispatch': {
+            await verifyPureVersionBump(mainRoot, contract, version);
+            const headSha = await git.revParse(mainRoot, 'HEAD');
+            await git.createTag(mainRoot, tag, headSha);
+            const pushed = await git.pushTag(mainRoot, 'origin', tag);
+            if (!pushed.ok) {
+                throw new UserError(`Could not push tag ${tag}: ${pushed.detail}`);
+            }
+            await dispatchReleaseWorkflow(mainRoot, config.mainBranch, version);
+            return { action: 'create-tag-and-dispatch', version, detail: `tagged and dispatched ${tag}` };
+        }
+        case 'dispatch-workflow': {
+            // No staged candidate is visible. That alone is not proof nothing is
+            // happening: a run this release already dispatched may still be
+            // queued/running, may have just finished and not yet be visible as
+            // staged, or may already have been approved (consumed) in an earlier,
+            // interrupted invocation. `resolveDispatchDecision` re-derives which,
+            // from the matching run's own state — a rerun must never fire another
+            // dispatch while one it already triggered may still be working.
+            const decision = await resolveDispatchDecision(mainRoot, pkgName, version, poll);
+            if (decision === 'proceed') {
+                return runReleasePublish(options); // fresh facts, never act on what's now stale
+            }
+            await dispatchReleaseWorkflow(mainRoot, config.mainBranch, version);
+            return {
+                action: 'dispatch-workflow',
+                version,
+                detail: `re-dispatched the release workflow for ${version}`,
+            };
+        }
+        case 'refuse-wrong-stage':
+            throw new UserError(next.detail, {
+                command: `npm stage reject ${next.stagedCandidate.id}`,
+                why: 'reject the wrong-tagged stage (owner-interactive, 2FA), then rerun to re-dispatch',
+            });
+        case 'await-approval':
+            return awaitApproval(mainRoot, contract, version, next.stagedCandidate, pkgName, poll);
+        case 'reconstruct-record-from-public':
+            return reconstructRecord(mainRoot, contract, version, pkgName, { tier: 'recovery-without-staged-artifact' });
+    }
+}
+export function printReleasePublishReport(report) {
+    const done = report.action === 'reconstruct-record-from-public';
+    console.log(done ? ui.ok(`✓ ${report.version} published and recorded`) : ui.warn(`… ${report.version}: ${report.action}`));
+    console.log(`  ${report.detail}`);
+    if (report.release) {
+        console.log(`  ${ui.bold('integrity')}  ${report.release.integrity ?? '(none)'}`);
+    }
+}
+//# sourceMappingURL=release.js.map