prismatica 0.2.0

package/dist/commands/ready.js

@@ -0,0 +1,931 @@
+/**
+ * Durable bookkeeping for the agent-driven Get Change Ready loop.
+ *
+ * This command starts no agent, calls no model, reads no chat and decides no
+ * verdict. It appends validated facts supplied through strict JSON, then a
+ * read-only status call reconstructs the owner card from those events and Git.
+ *
+ * The events live in `.prismatica/ready.jsonl`, beside the assurance ledger and
+ * never in it. Assurance consumers therefore cannot see them at all, rather
+ * than seeing them and filtering: a baseline reader parses every LEDGER line
+ * with `LedgerEntrySchema`, so a Ready event appended after a Check made that
+ * file malformed at exactly the position `latestCheckStanding` fails closed on.
+ *
+ * ORDER between the two files is never consulted, which is what makes two files
+ * safe. The single question that needed it — "is this Check inside the run?" —
+ * is answered by the boundary's own `checkRunsBefore`, an index into this
+ * contract's check rows that a partition cannot move.
+ */
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { stripVTControlCharacters } from 'node:util';
+import { isCheckEvidenceFile, laneRelative } from '../assurance/proofinputs.js';
+import { listOpenChanges, resolveChangeHome, resolveContractId } from '../change.js';
+import { loadConfig } from '../config.js';
+import { UserError } from '../errors.js';
+import * as git from '../git.js';
+import { appendReadyEvent, migrateReadyEvents, readLedger, readReadyLog } from '../ledger.js';
+import { ledgerPath, readyLogPath } from '../paths.js';
+import { readAnswerFile } from '../planning/context.js';
+import { contractExists, parseMarkdownRecord, readContract, readReview, reviewPath, } from '../records/store.js';
+import { CheckEvidenceSchema, READY_RECORD_FORMAT, ReadyCheckAttemptEventSchema, ReadyRecordImportSchema, ReadyReviewAttemptEventSchema, ReadyReviewDraftedEventSchema, ReadyRunStartedEventSchema, ReadyStoppedEventSchema, ReviewSchema, } from '../records/types.js';
+import * as ui from '../ui.js';
+const MAX_ATTEMPTS = 3;
+function readRunLog(home, contractId) {
+    const ready = readReadyLog(home);
+    const ledger = readLedger(home);
+    const named = (file) => (line) => ({
+        file: laneRelative(home, file),
+        lineNumber: line.lineNumber,
+    });
+    return {
+        events: ready.events.filter((event) => event.contractId === contractId),
+        checks: ledger.entries.filter((entry) => entry.contractId === contractId && entry.event === 'check_run'),
+        ledgerEntries: ledger.entries.length,
+        malformed: [
+            ...ledger.malformed.map(named(ledgerPath(home))),
+            ...ready.malformed.map(named(readyLogPath(home))),
+        ],
+    };
+}
+function samePlan(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function parseImport(raw, importFile) {
+    const parsed = ReadyRecordImportSchema.safeParse(raw);
+    if (parsed.success)
+        return parsed.data;
+    throw new UserError(`The ready record is invalid:\n${parsed.error.issues
+        .map((issue) => `  - ${issue.path.join('.') || '<root>'}: ${issue.message}`)
+        .join('\n')}`, {
+        command: `prismatica ready record --import ${importFile}`,
+        why: 'ready records are strict JSON; unknown, missing or wrongly typed fields are refused before the ledger changes',
+    });
+}
+/**
+ * The last event that speaks for a run's STATE, or `null`.
+ *
+ * `ready_review_drafted` is excluded for the reason `statusAt` states at its own
+ * call site: `review` writes it, not the controller, and it carries a
+ * `stopState` it does not thereby CLAIM. One implementation, because the card,
+ * the rollover guard and the boundary-chain audit must agree about whether a run
+ * has stopped — a rollover permitted on a state the card calls `running` would
+ * be exactly the contradiction the budget counters were repaired to avoid.
+ */
+function latestStateEvent(events, runId) {
+    return (events
+        .filter((event) => event.runId === runId && event.event !== 'ready_review_drafted')
+        .at(-1) ?? null);
+}
+function requireRunRunning(events, start, contractId) {
+    const state = latestStateEvent(events, start.runId)?.stopState ?? 'running';
+    if (state !== 'running') {
+        throw new UserError(`Get Change Ready run ${start.runId} has stopped (${state}).`, {
+            command: `prismatica ready status ${contractId}`,
+            why: 'only the owner may open a new run; a stopped run accepts no further attempts',
+        });
+    }
+}
+/**
+ * The ACTIVE run's boundary — the last link of a verified chain — or `null`.
+ *
+ * A contract once held exactly ONE boundary and a second was refused outright as
+ * ambiguous. That refusal was the only thing standing between a hand-appended
+ * `ready_run_started` line and a reset attempt budget, so the owner-authorised
+ * rollover could not simply take "the latest one wins": that would hand fresh
+ * budgets to any second boundary, from any source, which is the limit removed
+ * rather than governed.
+ *
+ * So multiple boundaries are accepted only as a CHAIN the ledger itself can
+ * verify. The first names no predecessor; every later one must name the
+ * immediately-preceding boundary's `runId` in `supersedes`, and the run it
+ * replaces must actually have STOPPED — recomputed from that run's own events
+ * rather than asserted by the boundary that supersedes it. Anything else is
+ * still ambiguous and still fails closed, which is what keeps `ready status`,
+ * `check` and `review` from reading a forged line as a live run.
+ */
+function runStartFor(events, contractId) {
+    const starts = events.filter((event) => event.event === 'ready_run_started');
+    const ambiguous = (why) => new UserError(`The Get Change Ready log contains ${starts.length} boundaries for ${contractId}; the active run is ambiguous (${why}).`, {
+        command: 'prismatica ready status',
+        why: 'a restart must reuse one durable run, and only an owner-authorised rollover of a stopped run may open another',
+    });
+    starts.forEach((start, index) => {
+        const previous = starts[index - 1];
+        if (start.supersedes !== previous?.runId) {
+            throw ambiguous(previous
+                ? `boundary ${start.id} does not supersede run ${previous.runId}`
+                : `the first boundary ${start.id} names a superseded run`);
+        }
+        if (previous && latestStateEvent(events, previous.runId)?.stopState === 'running') {
+            throw ambiguous(`run ${previous.runId} had not stopped when ${start.id} replaced it`);
+        }
+    });
+    return starts.at(-1) ?? null;
+}
+/**
+ * Every run this contract has finished, oldest first — history the rollover must
+ * not erase (principle 5). Counts only, plus the state each ended in: the
+ * attempts themselves stay in the ledger exactly as they were written, and the
+ * card's job here is to say that a previous run happened and what became of it.
+ */
+function previousRunsFor(events) {
+    const starts = events.filter((event) => event.event === 'ready_run_started');
+    return starts.slice(0, -1).map((start) => {
+        const own = events.filter((event) => event.runId === start.runId);
+        return {
+            runId: start.runId,
+            startedAt: start.at,
+            boundaryHead: start.boundary.head,
+            stopState: latestStateEvent(events, start.runId)?.stopState ?? 'running',
+            checkAttempts: own.filter((event) => event.event === 'ready_check_attempt').length,
+            reviewAttempts: own.filter((event) => event.event === 'ready_review_attempt').length,
+        };
+    });
+}
+/**
+ * Both logs, never just one. A corrupt lifecycle line hides part of the run;
+ * a corrupt ledger line hides a Check that may have spent budget. Either way
+ * the run cannot be reconstructed, and principle 6 decides the rest.
+ */
+function refuseMalformed(malformed) {
+    if (malformed.length === 0)
+        return;
+    throw new UserError(`There are unreadable line(s): ${malformed.map((line) => `${line.file}:${line.lineNumber}`).join(', ')}. No ready event was appended.`, {
+        command: 'prismatica ready status',
+        why: 'an append-only run cannot be resumed safely while part of its possible history is unreadable',
+    });
+}
+function relativeEvidencePath(home, contractId, supplied) {
+    const normal = supplied.split(path.sep).join('/');
+    if (supplied !== normal ||
+        path.posix.isAbsolute(normal) ||
+        path.posix.normalize(normal) !== normal ||
+        !isCheckEvidenceFile(home, contractId, normal)) {
+        throw new UserError(
+        // `plain` for the same reason the card uses it: this is the imported
+        // document's own text, and a refusal prints to the same terminal.
+        `Evidence path "${plain(supplied)}" is not an exact Check evidence path for ${contractId}.`, {
+            command: 'prismatica ready record --import <event.json>',
+            why: 'the contract id fixes the evidence directory; the imported document cannot choose another destination',
+        });
+    }
+    return normal;
+}
+function readExactCheckEvidence(home, contractId, evidencePath, check) {
+    const absolute = path.join(home, ...evidencePath.split('/'));
+    if (!fs.existsSync(absolute)) {
+        throw new UserError(`Check evidence does not exist at ${evidencePath}.`, {
+            command: 'prismatica ready record --import <event.json>',
+            why: 'the run event must point to the exact evidence produced by the Check it records',
+        });
+    }
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(absolute, 'utf8'));
+    }
+    catch {
+        throw new UserError(`Check evidence at ${evidencePath} is not valid JSON.`);
+    }
+    const parsed = CheckEvidenceSchema.safeParse(raw);
+    if (!parsed.success ||
+        parsed.data.contractId !== contractId ||
+        parsed.data.event !== 'check_run' ||
+        parsed.data.at !== check.at ||
+        parsed.data.pass !== check.pass ||
+        JSON.stringify(parsed.data.outcomes) !== JSON.stringify(check.checks)) {
+        throw new UserError(`Check evidence at ${evidencePath} does not match ledger entry ${check.id}.`, {
+            command: 'prismatica ready record --import <event.json>',
+            why: 'a ready attempt is bookkeeping for one actual Check, never a substitute for Check evidence',
+        });
+    }
+}
+function sightingKey(sighting) {
+    return [sighting.patchId, sighting.createdAt].join(' ');
+}
+/**
+ * Every distinct review record this run has produced, read from Git and the
+ * working tree rather than from the run's own bookkeeping.
+ *
+ * A `ready record` event is written AFTER the work it records, which is
+ * principle 4 and stays that way — but it means the controller can do the work
+ * and die before recording it, and a budget rebuilt from recorded events alone
+ * would report that attempt as never spent. So the budget is rebuilt from what
+ * the ATTEMPT ITSELF left behind, which no controller has to survive to write:
+ * `review` writes `reviews/<id>.md`, and the safe rejection checkpoint commits
+ * it. In-run commits are the ones reachable from HEAD but not from the run
+ * boundary; the working tree is included because the current draft may never
+ * have been committed at all.
+ *
+ * This is the SECOND of two independent sources, not the only one. A draft that
+ * was never committed and is then overwritten in place leaves nothing here to
+ * see, which is why `review` also appends a `ready_review_drafted` event the
+ * instant it writes the record — the durable half, written before anything can
+ * replace it. Both are keyed by `sightingKey`, so the same attempt seen twice
+ * counts once.
+ *
+ * THE RECORD AS OF THE BOUNDARY IS EXCLUDED, and it has to be excluded by
+ * IDENTITY rather than by date. A change that was already reviewed before the
+ * run started carries that review in the working tree unchanged, so counting it
+ * would spend a fresh run's budget on pre-run history — the mirror of the
+ * `checkRunsBefore` boundary the Check side gets from its ledger index for
+ * free. A timestamp comparison cannot do this job: `createdAt` is the record's
+ * own, and a review drafted seconds before a boundary is indistinguishable from
+ * one drafted seconds after by clock alone. Residual, and it fails closed: a
+ * pre-run draft that was never COMMITTED has no boundary version to match, so
+ * it counts.
+ *
+ * Unreadable is deliberately not counted. It is not evidence a review happened,
+ * and `historicalReviews` already reports it to the owner as a record problem.
+ */
+async function reviewSightings(home, contractId, boundaryHead) {
+    const rel = laneRelative(home, reviewPath(home, contractId));
+    const sighting = (text) => {
+        try {
+            const review = parseMarkdownRecord(text, ReviewSchema).data;
+            return review.id === contractId && review.contractId === contractId
+                ? { patchId: review.patchId, createdAt: review.createdAt }
+                : null;
+        }
+        catch {
+            return null; // not a readable review record — see above
+        }
+    };
+    const sightings = [];
+    const add = (text) => {
+        const found = sighting(text);
+        if (found)
+            sightings.push(found);
+    };
+    let boundaryKey = null;
+    try {
+        const boundaryText = await git.showFileStrict(home, boundaryHead, rel);
+        const atBoundary = boundaryText === null ? null : sighting(boundaryText);
+        boundaryKey = atBoundary === null ? null : sightingKey(atBoundary);
+        const beforeRun = new Set(await git.commitsTouching(home, rel, boundaryHead));
+        for (const commit of await git.commitsTouching(home, rel, 'HEAD')) {
+            if (beforeRun.has(commit))
+                continue;
+            const text = await git.showFileStrict(home, commit, rel);
+            if (text !== null)
+                add(text);
+        }
+    }
+    catch {
+        // A boundary Git can no longer resolve. `historicalReviews` reports that as
+        // a record problem and the run may only be stopped, so the working tree
+        // below is still read and nothing here is silently treated as absent.
+    }
+    const working = reviewPath(home, contractId);
+    if (fs.existsSync(working))
+        add(fs.readFileSync(working, 'utf8'));
+    return sightings.filter((found) => sightingKey(found) !== boundaryKey);
+}
+/**
+ * How many attempts of each kind this run has SPENT — never merely how many it
+ * recorded. THE ONE ANSWER: the card reads it and so does the budget guard, so
+ * a controller can never be refused a display it is then allowed to exceed, or
+ * the reverse.
+ *
+ * Recorded attempts count once each, plus every attempt whose own durable
+ * output exists with no recording beside it: a `check_run` ledger row appended
+ * after the run boundary (`check` writes it, and it carries the id a recorded
+ * attempt would cite), and a review record drafted since the boundary that no
+ * recorded attempt names.
+ *
+ * "After the boundary" is `boundary.checkRunsBefore`, an INDEX into this
+ * contract's own check rows, never a position in a merged log. That is what
+ * lets the lifecycle events live in their own file: the ledger's check rows
+ * keep their order and their count whatever else is partitioned away from
+ * them, so the same rows fall inside the run before and after the migration.
+ *
+ * It rounds UP on purpose. A Check the owner ran themselves inside the run
+ * window spends run budget, because it is an attempt at this diff whichever
+ * hand started it. Principle 6 decides which way that uncertainty falls, and
+ * the alternative — treating real work as unspent because the bookkeeping is
+ * missing — is exactly how a restarted controller came to hand out a fourth
+ * attempt.
+ */
+async function spentIn(home, contractId, log, start, recordedChecks, recordedReviews) {
+    const recordedCheckIds = new Set(recordedChecks.map((event) => event.check.ledgerEntryId));
+    const unrecordedChecks = log.checks
+        .slice(start.boundary.checkRunsBefore)
+        .filter((entry) => !recordedCheckIds.has(entry.id)).length;
+    const recordedReviewKeys = new Set(recordedReviews.map((event) => sightingKey(event.review)));
+    const contractEvents = log.events;
+    const drafted = contractEvents
+        .filter((event) => event.event === 'ready_review_drafted' && event.runId === start.runId)
+        .map((event) => sightingKey(event.review));
+    // A draft a PREVIOUS run already spent its budget on is that run's history,
+    // not this one's attempt. The git-boundary test above excludes the review
+    // COMMITTED at the boundary, which is the pre-run case it was written for and
+    // is not enough after a rollover: a dead run's last draft is routinely still
+    // uncommitted, so it has no boundary version to match and would open the new
+    // run with one review already spent — contradicting the fresh budgets a
+    // rollover exists to grant. Identity, never a date, for the reason
+    // `reviewSightings` gives: `review` stamps a fresh `createdAt` on every draft,
+    // so two runs can only share a key when it is literally the same record.
+    const spentByPreviousRuns = new Set(contractEvents.flatMap((event) => event.runId !== start.runId &&
+        (event.event === 'ready_review_attempt' || event.event === 'ready_review_drafted')
+        ? [sightingKey(event.review)]
+        : []));
+    const unrecordedReviews = new Set([
+        ...drafted,
+        ...(await reviewSightings(home, contractId, start.boundary.head)).map(sightingKey),
+    ].filter((key) => !recordedReviewKeys.has(key) && !spentByPreviousRuns.has(key)));
+    return {
+        checks: recordedChecks.length + unrecordedChecks,
+        reviews: recordedReviews.length + unrecordedReviews.size,
+    };
+}
+async function historicalReviews(home, contractId, ref) {
+    const rel = laneRelative(home, reviewPath(home, contractId));
+    let commits;
+    try {
+        commits = await git.commitsTouching(home, rel, ref);
+    }
+    catch (error) {
+        return {
+            reviews: [],
+            problem: `Git cannot read run boundary ${ref}, so committed pre-run review history cannot be reconstructed (${error instanceof Error ? error.message : String(error)})`,
+        };
+    }
+    const reviews = [];
+    for (const commit of commits) {
+        let text;
+        try {
+            text = await git.showFileStrict(home, commit, rel);
+        }
+        catch {
+            reviews.push({ commit, verdict: 'unreadable', findings: null });
+            continue;
+        }
+        if (text === null)
+            continue;
+        try {
+            const review = parseMarkdownRecord(text, ReviewSchema).data;
+            if (review.id !== contractId ||
+                review.contractId !== contractId ||
+                review.state !== 'sealed') {
+                continue;
+            }
+            reviews.push({
+                commit,
+                verdict: review.verdict ?? 'not_recorded',
+                // Historical Review records have no findings field. Do not mine commit
+                // messages or reconstruct prose that the repository never recorded.
+                findings: null,
+            });
+        }
+        catch {
+            reviews.push({ commit, verdict: 'unreadable', findings: null });
+        }
+    }
+    return { reviews, problem: null };
+}
+async function resolvedHome(options) {
+    const mainRoot = await git.mainRepoRoot(options.cwd);
+    const config = loadConfig(mainRoot);
+    const contractId = await resolveContractId(options.cwd, config.mainBranch, options.contractId);
+    const home = await resolveChangeHome(options.cwd, contractId);
+    if (!contractExists(home, contractId)) {
+        throw new UserError(`No contract "${contractId}" to record a ready run for.`);
+    }
+    readContract(home, contractId); // strict read: the destination must be a valid contract
+    return { contractId, home };
+}
+async function statusAt(home, contractId) {
+    const log = readRunLog(home, contractId);
+    const start = runStartFor(log.events, contractId);
+    const runEvents = start ? log.events.filter((event) => event.runId === start.runId) : [];
+    const checks = runEvents.filter((event) => event.event === 'ready_check_attempt');
+    const reviews = runEvents.filter((event) => event.event === 'ready_review_attempt');
+    const problems = [];
+    if (start) {
+        for (const event of runEvents) {
+            if (!samePlan(event.plan, start.plan)) {
+                problems.push(`event ${event.id} carries a different run plan`);
+            }
+        }
+        // Attempt numbers must ADVANCE, not be consecutive: an attempt whose
+        // recording never happened leaves a real gap, and reporting that gap as a
+        // corrupt record would send the owner looking for tampering that is
+        // actually a crashed controller — the case `spentIn` exists to survive.
+        const advancing = (kind, events) => {
+            let previous = 0;
+            for (const event of events) {
+                if (event.attempt <= previous || event.attempt > MAX_ATTEMPTS) {
+                    problems.push(`${kind} attempt ${event.attempt} is out of sequence`);
+                }
+                previous = event.attempt;
+            }
+        };
+        advancing('Check', checks);
+        advancing('review', reviews);
+    }
+    // The run's state comes from what the CONTROLLER recorded, never from
+    // `review`'s own drafted-attempt event. `ReadyEventBase` obliges that event
+    // to carry a `stopState` and a `nextOwnerAction` — it does not thereby CLAIM
+    // either, and it is written by a command the controller may not even have
+    // started. Reading state off it would let an ordinary `review` report a run
+    // stopped at `review_budget_exhausted` as `running` again: a card
+    // contradicting an enforcement that still, correctly, refuses the attempt.
+    // It stays in `runEvents` for the plan check and for `spentIn`, which is
+    // what it is evidence OF, and an unrecorded draft still reaches the owner
+    // through `recordProblems`.
+    const latest = start ? latestStateEvent(runEvents, start.runId) : null;
+    const ref = start?.boundary.head ?? 'HEAD';
+    const history = await historicalReviews(home, contractId, ref);
+    if (history.problem)
+        problems.push(history.problem);
+    const budgets = start
+        ? await spentIn(home, contractId, log, start, checks, reviews)
+        : { checks: 0, reviews: 0 };
+    if (budgets.checks > checks.length) {
+        problems.push(`${budgets.checks - checks.length} Check run(s) in this run were never recorded as attempts; they still spend the budget`);
+    }
+    if (budgets.reviews > reviews.length) {
+        problems.push(`${budgets.reviews - reviews.length} drafted review(s) in this run were never recorded as attempts; they still spend the budget`);
+    }
+    return {
+        contractId,
+        runId: start?.runId ?? null,
+        boundary: start?.boundary ?? null,
+        plan: start?.plan ?? null,
+        checkAttempts: checks,
+        reviewAttempts: reviews,
+        checkAttemptsSpent: Math.min(MAX_ATTEMPTS, budgets.checks),
+        reviewAttemptsSpent: Math.min(MAX_ATTEMPTS, budgets.reviews),
+        checkAttemptsRemaining: Math.max(0, MAX_ATTEMPTS - budgets.checks),
+        reviewAttemptsRemaining: Math.max(0, MAX_ATTEMPTS - budgets.reviews),
+        preRunCheckRuns: start?.boundary.checkRunsBefore ?? log.checks.length,
+        preRunReviews: history.reviews,
+        previousRuns: previousRunsFor(log.events),
+        stopState: latest?.stopState ?? 'not_started',
+        nextOwnerAction: latest?.nextOwnerAction ?? null,
+        malformedLogLines: log.malformed.map((line) => `${line.file}:${line.lineNumber}`),
+        recordProblems: problems,
+    };
+}
+export async function runReadyStatus(options) {
+    const { contractId, home } = await resolvedHome(options);
+    return statusAt(home, contractId);
+}
+/** Refuse work that would exceed an active Get Change Ready run's budget. */
+export async function requireReadyAttemptAvailable(home, contractId, kind) {
+    const log = readRunLog(home, contractId);
+    const start = runStartFor(log.events, contractId);
+    if (!start)
+        return;
+    refuseMalformed(log.malformed);
+    requireRunRunning(log.events, start, contractId);
+    const history = await historicalReviews(home, contractId, start.boundary.head);
+    if (history.problem) {
+        throw new UserError(`${history.problem}. No further ${kind} attempt may start.`, {
+            command: `prismatica ready status ${contractId}`,
+            why: 'the active run budget cannot be reconstructed from an unreadable boundary',
+        });
+    }
+    const runEvents = log.events.filter((event) => event.runId === start.runId);
+    const checks = runEvents.filter((event) => event.event === 'ready_check_attempt');
+    const reviews = runEvents.filter((event) => event.event === 'ready_review_attempt');
+    const spent = await spentIn(home, contractId, log, start, checks, reviews);
+    requireAttemptNumber(kind, (kind === 'Check' ? spent.checks : spent.reviews) + 1, contractId);
+}
+/**
+ * Spend a review attempt at the moment its record exists — the durable half of
+ * `ready_review_attempt`, and the one thing no controller has to survive to
+ * write.
+ *
+ * `review` calls this immediately after writing the draft, which is principle 4
+ * exactly: the step being recorded (a review record now exists) has already
+ * succeeded. The verdict is NOT recorded here and cannot be — nobody has read
+ * the diff yet — so the two events stay separate: this one says an attempt was
+ * started, the later one says what it concluded.
+ *
+ * A NO-OP outside a run. Ordinary `review`, `review --agent`, `review --copy`
+ * against a change with no Get Change Ready boundary appends nothing and is
+ * byte-for-byte the command it always was; the budget only exists where a run
+ * declared one. Every piece of ready-schema knowledge — copying the run's plan,
+ * the stop state, the owner's next action — lives here rather than in `review`,
+ * so there is one writer of these events and one place that knows their shape.
+ */
+export function recordReviewDrafted(home, contractId, review) {
+    // A WRITE path, so it is one of the two places the partition is completed —
+    // see `runReadyRecord`. A repository with nothing legacy to move writes
+    // nothing here.
+    migrateReadyEvents(home);
+    const start = runStartFor(readRunLog(home, contractId).events, contractId);
+    if (!start)
+        return;
+    appendReadyEvent(home, ReadyReviewDraftedEventSchema.parse({
+        format: READY_RECORD_FORMAT,
+        id: randomUUID(),
+        contractId,
+        event: 'ready_review_drafted',
+        at: new Date().toISOString(),
+        runId: start.runId,
+        plan: start.plan,
+        stopState: 'running',
+        nextOwnerAction: `record the reviewer verdict with prismatica ready record ${contractId} --import <review.json>`,
+        review: {
+            path: laneRelative(home, reviewPath(home, contractId)),
+            patchId: review.patchId,
+            createdAt: review.createdAt,
+        },
+    }));
+}
+/**
+ * The WRITE path's destination must be a LIVE LANE.
+ *
+ * `resolveChangeHome` falls back to the current checkout and then to main,
+ * which is right for `pack` and wrong here for exactly the reason it is wrong
+ * for `propose --import`: a contract archived on main would silently retarget
+ * a lane's run bookkeeping at main's own ledger. With no lane there is no run
+ * to record, so nothing legitimate is refused. Reading keeps the general
+ * resolver — a card about a change whose lane has already been removed is
+ * still worth printing.
+ */
+async function requireLane(cwd, contractId, home) {
+    const open = await listOpenChanges(cwd);
+    if (!open.some((change) => change.id === contractId && change.home === home)) {
+        throw new UserError(`There is no open lane for ${contractId} to record a ready run in.`, {
+            command: `prismatica ready status ${contractId}`,
+            why: 'a run event belongs to the lane the run happened in; without one there is nothing to append to but main',
+        });
+    }
+}
+function requireRun(events, contractId, runId) {
+    const start = runStartFor(events, contractId);
+    if (!start) {
+        throw new UserError(`No Get Change Ready run has started for ${contractId}.`, {
+            command: 'prismatica ready record --import <start.json>',
+            why: 'the CLI-generated run boundary must exist before an attempt can spend its budget',
+        });
+    }
+    if (start.runId !== runId) {
+        throw new UserError(`Run ${runId} is not the durable run for ${contractId}.`, {
+            command: `prismatica ready status ${contractId}`,
+            why: 'a restart reuses the recorded run id; supplying another one may not reset the attempt counters',
+        });
+    }
+    return start;
+}
+/**
+ * The attempt number this event gets, or a refusal.
+ *
+ * `position` is what `spentIn` already counted INCLUDING the attempt now being
+ * recorded, so the number is read off the run's spent budget rather than off
+ * how many events happen to have been written. That is the whole point: an
+ * attempt whose recording never happened has already spent its place, so the
+ * next one is numbered past it and a fourth is refused.
+ */
+function requireAttemptNumber(kind, position, contractId) {
+    if (position > MAX_ATTEMPTS) {
+        throw new UserError(`${kind} attempt budget for ${contractId} is exhausted (${MAX_ATTEMPTS}/${MAX_ATTEMPTS}).`, {
+            command: `prismatica ready status ${contractId}`,
+            why: 'restarting a controller does not create a new run or reset its three-attempt limit, and an attempt nothing recorded still spent one',
+        });
+    }
+    return position;
+}
+export async function runReadyRecord(options) {
+    if (!options.importFile) {
+        throw new UserError('`ready record` needs a strict JSON event to import.', {
+            command: 'prismatica ready record --import <event.json>',
+            why: 'findings and run state are file content, never command-line text',
+        });
+    }
+    const { contractId, home } = await resolvedHome(options);
+    await requireLane(options.cwd, contractId, home);
+    const input = parseImport(readAnswerFile(options.importFile, {
+        command: 'prismatica ready record --import <event.json>',
+        why: 'the event is strict JSON so multiline findings never pass through a shell',
+    }), options.importFile);
+    // The partition is completed HERE, on a write path, and never on a read one:
+    // `check` and `review` reach this bookkeeping through
+    // `requireReadyAttemptAvailable`, and a repository upgrading mid-run must keep
+    // its budget enforcement without a status call rewriting records underneath
+    // it. `readReadyLog` reads legacy rows in place until this moves them, so the
+    // run is identical either side of the move.
+    migrateReadyEvents(home);
+    const log = readRunLog(home, contractId);
+    refuseMalformed(log.malformed);
+    const now = (options.now ?? new Date()).toISOString();
+    const makeId = options.makeId ?? randomUUID;
+    if (input.kind === 'start') {
+        const existing = runStartFor(log.events, contractId);
+        if (options.newRun) {
+            // The OWNER's decision, refused for an agent executor at the CLI's one
+            // authority hook (`executor.ts`'s `OWNER_ONLY_INVOCATIONS`). Everything
+            // below is about whether the LEDGER permits it; who asked is settled
+            // before this function is reached.
+            if (!existing) {
+                throw new UserError(`There is no Get Change Ready run for ${contractId} to replace.`, {
+                    command: `prismatica ready record ${contractId} --import <start.json>`,
+                    why: 'a first run is an ordinary start; --new-run only ever follows a run that has stopped',
+                });
+            }
+            // The SAME state the card prints, deliberately: a rollover permitted on a
+            // run the owner is being shown as `running` would be the two halves
+            // disagreeing, which is the defect the attempt counters were repaired for.
+            const current = await statusAt(home, contractId);
+            if (current.stopState === 'running') {
+                throw new UserError(`Run ${existing.runId} is still running; it must stop before a new run can start.`, {
+                    command: `prismatica ready record ${contractId} --import <stop.json>`,
+                    why: 'fresh attempt budgets follow a terminal run — never a live one, which would simply be a fourth attempt',
+                });
+            }
+        }
+        else if (existing) {
+            if (!samePlan(existing.plan, input.plan)) {
+                throw new UserError(`Get Change Ready already has a different durable run plan for ${contractId}.`, {
+                    command: `prismatica ready status ${contractId}`,
+                    why: 'a restart must reuse the provider, model, effort, run id and attempt budgets already recorded',
+                });
+            }
+            return { appended: false, status: await statusAt(home, contractId) };
+        }
+        const event = ReadyRunStartedEventSchema.parse({
+            format: READY_RECORD_FORMAT,
+            id: makeId(),
+            contractId,
+            event: 'ready_run_started',
+            at: now,
+            runId: makeId(),
+            plan: input.plan,
+            stopState: 'running',
+            nextOwnerAction: input.nextOwnerAction,
+            // Written by the CLI from the ledger it just read, never from the imported
+            // document: the chain is what makes a second boundary auditable, so a
+            // caller must not be able to spell one.
+            ...(options.newRun && existing ? { supersedes: existing.runId } : {}),
+            boundary: {
+                head: await git.revParse(home, 'HEAD'),
+                ledgerRecordsBefore: log.ledgerEntries,
+                checkRunsBefore: log.checks.length,
+            },
+        });
+        appendReadyEvent(home, event);
+        return { appended: true, status: await statusAt(home, contractId) };
+    }
+    const start = requireRun(log.events, contractId, input.runId);
+    const history = await historicalReviews(home, contractId, start.boundary.head);
+    if (history.problem && !(input.kind === 'stop' && input.stopState === 'blocked')) {
+        throw new UserError(`${history.problem}. Only a strict blocked stop event may be appended.`, {
+            command: `prismatica ready record ${contractId} --import <blocked-stop.json>`,
+            why: 'only a strict blocked stop event may extend a run whose original Git boundary is unreadable',
+        });
+    }
+    const runEvents = log.events.filter((event) => event.runId === start.runId);
+    const recordedChecks = runEvents.filter((event) => event.event === 'ready_check_attempt');
+    const recordedReviews = runEvents.filter((event) => event.event === 'ready_review_attempt');
+    if (input.kind === 'check') {
+        // The Check's POSITION among this contract's own check rows, compared with
+        // the boundary's `checkRunsBefore`. Not a position in a merged log: the
+        // lifecycle events are a separate file, and this is the index that survives
+        // that — the rows before the boundary are pre-run history whatever else
+        // was written between them.
+        const checkIndex = log.checks.findIndex((entry) => entry.id === input.checkLedgerEntryId);
+        if (checkIndex < 0) {
+            throw new UserError(`${plain(input.checkLedgerEntryId)} is not a Check ledger entry.`);
+        }
+        if (checkIndex < start.boundary.checkRunsBefore) {
+            throw new UserError(`Check ${plain(input.checkLedgerEntryId)} is not an attempt from run ${start.runId}.`, {
+                command: `prismatica ready status ${contractId}`,
+                why: "checks before the run boundary are pre-run history and consume none of this run's budget",
+            });
+        }
+        const check = log.checks[checkIndex];
+        if (!check.checkedHead) {
+            throw new UserError(`Check ${check.id} predates checkedHead binding and cannot be recorded as a run attempt.`);
+        }
+        const evidencePath = relativeEvidencePath(home, contractId, input.evidencePath);
+        readExactCheckEvidence(home, contractId, evidencePath, check);
+        const existing = recordedChecks.find((event) => event.check.ledgerEntryId === check.id);
+        if (existing) {
+            if (existing.check.evidencePath !== evidencePath) {
+                throw new UserError(`Check ${check.id} is already recorded with different evidence.`);
+            }
+            return { appended: false, status: await statusAt(home, contractId) };
+        }
+        requireRunRunning(runEvents, start, contractId);
+        // This Check's own ledger row is already in the run window and not yet
+        // recorded, so `spentIn` counts it — the position it returns IS this
+        // attempt's number, gaps from unrecorded attempts included.
+        const budgets = await spentIn(home, contractId, log, start, recordedChecks, recordedReviews);
+        const attempt = requireAttemptNumber('Check', budgets.checks, contractId);
+        if (attempt === MAX_ATTEMPTS && !check.pass && input.stopState === 'running') {
+            throw new UserError('The third failed Check must record stopState "check_budget_exhausted".');
+        }
+        appendReadyEvent(home, ReadyCheckAttemptEventSchema.parse({
+            format: READY_RECORD_FORMAT,
+            id: makeId(),
+            contractId,
+            event: 'ready_check_attempt',
+            at: now,
+            runId: start.runId,
+            plan: start.plan,
+            stopState: input.stopState,
+            nextOwnerAction: input.nextOwnerAction,
+            attempt,
+            check: {
+                ledgerEntryId: check.id,
+                evidencePath,
+                checkedHead: check.checkedHead,
+                pass: check.pass,
+            },
+        }));
+        return { appended: true, status: await statusAt(home, contractId) };
+    }
+    if (input.kind === 'review') {
+        let review;
+        try {
+            review = readReview(home, contractId).data;
+        }
+        catch {
+            throw new UserError(`There is no readable review record for ${contractId}.`);
+        }
+        if (review.state !== 'draft') {
+            throw new UserError('Record the reviewer verdict before sealing it; the current review is not a draft.', {
+                command: 'prismatica ready record --import <review.json>',
+                why: 'the durable findings event must exist before the rejection checkpoint changes the review record',
+            });
+        }
+        if (review.patchId !== input.reviewPatchId) {
+            throw new UserError(`The imported patch id does not match the current review for ${contractId}.`);
+        }
+        const existing = recordedReviews.find((event) => event.review.patchId === review.patchId && event.review.createdAt === review.createdAt);
+        if (existing) {
+            if (existing.verdict !== input.verdict ||
+                JSON.stringify(existing.findings) !== JSON.stringify(input.findings)) {
+                throw new UserError('This review attempt is already recorded with different verdict text or findings.');
+            }
+            return { appended: false, status: await statusAt(home, contractId) };
+        }
+        requireRunRunning(runEvents, start, contractId);
+        // The draft on disk is this attempt's own durable output and no recorded
+        // attempt names it, so `spentIn` counts it — as it counts any earlier draft
+        // this run produced and never recorded.
+        const budgets = await spentIn(home, contractId, log, start, recordedChecks, recordedReviews);
+        const attempt = requireAttemptNumber('review', budgets.reviews, contractId);
+        if (attempt === MAX_ATTEMPTS &&
+            input.verdict === 'DO NOT SEAL' &&
+            input.stopState === 'running') {
+            throw new UserError('The third rejected review must record stopState "review_budget_exhausted".');
+        }
+        appendReadyEvent(home, ReadyReviewAttemptEventSchema.parse({
+            format: READY_RECORD_FORMAT,
+            id: makeId(),
+            contractId,
+            event: 'ready_review_attempt',
+            at: now,
+            runId: start.runId,
+            plan: start.plan,
+            stopState: input.stopState,
+            nextOwnerAction: input.nextOwnerAction,
+            attempt,
+            review: {
+                path: laneRelative(home, reviewPath(home, contractId)),
+                patchId: review.patchId,
+                createdAt: review.createdAt,
+            },
+            verdict: input.verdict,
+            findings: input.findings,
+        }));
+        return { appended: true, status: await statusAt(home, contractId) };
+    }
+    const last = runEvents.at(-1);
+    if (last?.event === 'ready_stopped' &&
+        last.stopState === input.stopState &&
+        last.nextOwnerAction === input.nextOwnerAction &&
+        last.detail === input.detail) {
+        return { appended: false, status: await statusAt(home, contractId) };
+    }
+    requireRunRunning(runEvents, start, contractId);
+    appendReadyEvent(home, ReadyStoppedEventSchema.parse({
+        format: READY_RECORD_FORMAT,
+        id: makeId(),
+        contractId,
+        event: 'ready_stopped',
+        at: now,
+        runId: start.runId,
+        plan: start.plan,
+        stopState: input.stopState,
+        nextOwnerAction: input.nextOwnerAction,
+        ...(input.detail === undefined ? {} : { detail: input.detail }),
+    }));
+    return { appended: true, status: await statusAt(home, contractId) };
+}
+/**
+ * Untrusted text on its way to a terminal.
+ *
+ * ONE rule, applied to every string this card prints: nothing that came from an
+ * imported document, a record on disk or Git output reaches the terminal
+ * carrying control sequences. Stripping only the fields someone judged risky is
+ * how `findings` came to be protected while `nextOwnerAction` — free text, from
+ * the same document, printed immediately above the "run record is incomplete or
+ * inconsistent" block an escape can scroll away — was not. The `ui.*` atoms are
+ * composed after this, so the card keeps its own colour.
+ *
+ * `stripVTControlCharacters` alone is NOT that rule: it removes ANSI/VT escape
+ * SEQUENCES, and measurably leaves carriage return, backspace, bell, NUL, DEL
+ * and the bidi overrides intact — every one of which rewrites or reorders text
+ * already on the line without an escape byte anywhere. So the sequences go
+ * first, then every remaining control (`Cc`) and format (`Cf`) character
+ * becomes a space. Newline is the one exception, kept because a multiline
+ * finding is printed as the lines the reviewer wrote and a new line cannot
+ * overwrite one already written. Nothing is dropped: a space holds the place,
+ * so the text still reads as what it said.
+ *
+ * This is a DISPLAY rule only. The record keeps the reviewer's bytes exactly —
+ * `findings` are stored as imported, which is what ac-7 requires.
+ */
+function plain(text) {
+    return stripVTControlCharacters(text).replace(/[\p{Cc}\p{Cf}]/gu, (character) => character === '\n' ? character : ' ');
+}
+function selectionText(selection) {
+    return `${plain(selection.provider)}, model ${plain(selection.model ?? 'provider default')}, effort ${plain(selection.effort ?? 'provider default')}`;
+}
+/**
+ * The same card as JSON — and terminal-safe by the same rule, reached a
+ * different way.
+ *
+ * `JSON.stringify` escapes the C0 controls and nothing else: DEL and every
+ * bidi override (U+202E and friends) are emitted RAW, so a finding imported
+ * with one reordered the terminal exactly as it would have on the human card.
+ * `plain`'s space substitution is the wrong cure here — this output is
+ * documented as the exact reconstructed record, and ac-7 requires findings kept
+ * byte-for-byte — so the character is ESCAPED instead: `\uXXXX` parses back to
+ * the identical value and cannot move a cursor.
+ *
+ * Newline is the one exception, and it is a structural one: with a two-space
+ * indent the only newlines outside a string literal are the pretty-printer's
+ * own, where an escape would not be JSON at all. Everything else in `Cc`/`Cf`
+ * sits inside a string literal, where the escape is exact.
+ *
+ * The escape is written per UTF-16 CODE UNIT, never per code point, and that
+ * distinction is the whole correctness of the claim above. `\p{Cf}` with the
+ * `u` flag matches a whole code point, so a supplementary-plane format
+ * character (U+E0001 LANGUAGE TAG, and every tag character after it) arrives
+ * here as a two-unit surrogate pair — and `\u` takes exactly four hex digits,
+ * so spelling the code point produced `1`, which JSON parses back as
+ * U+E000 followed by the digit "1". Byte-for-byte reconstruction, silently
+ * broken, on characters `findings` accepts like any other. Emitting one `\uXXXX`
+ * per code unit spells the surrogate pair JSON already understands, so the
+ * parsed value is the original code point exactly; a BMP character is one unit
+ * and its escape is unchanged.
+ */
+export function readyStatusJson(status) {
+    return JSON.stringify(status, null, 2).replace(/[\p{Cc}\p{Cf}]/gu, (character) => character === '\n'
+        ? character
+        : Array.from({ length: character.length }, (_unused, index) => `\\u${character.charCodeAt(index).toString(16).padStart(4, '0')}`).join(''));
+}
+export function printReadyStatus(status) {
+    console.log(ui.heading(`Get Change Ready — ${plain(status.contractId)}`));
+    console.log('');
+    if (!status.runId || !status.plan || !status.boundary) {
+        console.log(`  ${ui.warn('not started')}`);
+        console.log(`  pre-run Check history: ${status.preRunCheckRuns}`);
+        for (const review of status.preRunReviews) {
+            console.log(`  Pre-run review ${plain(review.commit).slice(0, 12)}: ${review.verdict}; findings not recorded`);
+        }
+        return;
+    }
+    // Before the active run, because it is what the run REPLACED: an owner
+    // reading a fresh 0/3 needs to see the exhausted run above it, or the card
+    // reads as a change that has been attempted once.
+    for (const previous of status.previousRuns) {
+        console.log(`  ${ui.dim('previous')}  ${plain(previous.runId)} (${previous.stopState}); Check ${previous.checkAttempts}, review ${previous.reviewAttempts} attempt(s) — kept, never reopened`);
+    }
+    console.log(`  ${ui.bold('run')}       ${plain(status.runId)}`);
+    console.log(`  ${ui.bold('boundary')}  ${plain(status.boundary.head)}`);
+    console.log(`  ${ui.bold('builder')}   ${selectionText(status.plan.builder)}`);
+    console.log(`  ${ui.bold('reviewer')}  ${selectionText(status.plan.reviewer)}`);
+    console.log(`  ${ui.bold('attempts')}  Check ${status.checkAttemptsSpent}/${MAX_ATTEMPTS} (${status.checkAttemptsRemaining} left), review ${status.reviewAttemptsSpent}/${MAX_ATTEMPTS} (${status.reviewAttemptsRemaining} left)`);
+    console.log(`  ${ui.bold('pre-run')}   ${status.preRunCheckRuns} Check run(s)`);
+    for (const check of status.checkAttempts) {
+        console.log(`  Check ${check.attempt}: ${check.check.pass ? 'pass' : 'FAIL'}; ledger ${plain(check.check.ledgerEntryId)}; HEAD ${plain(check.check.checkedHead)}; evidence ${plain(check.check.evidencePath)}`);
+    }
+    for (const review of status.reviewAttempts) {
+        console.log(`  Review ${review.attempt}: ${review.verdict}; ${plain(review.review.path)}; patch ${plain(review.review.patchId)}; created ${plain(review.review.createdAt)}`);
+        for (const finding of review.findings)
+            console.log(plain(finding));
+    }
+    for (const review of status.preRunReviews) {
+        console.log(`  Pre-run review ${plain(review.commit).slice(0, 12)}: ${review.verdict}; findings not recorded`);
+    }
+    console.log(`  ${ui.bold('state')}     ${status.stopState}`);
+    console.log(`  ${ui.bold('next')}      ${plain(status.nextOwnerAction ?? 'none recorded')}`);
+    if (status.malformedLogLines.length > 0 || status.recordProblems.length > 0) {
+        console.log('');
+        console.log(ui.bad('  run record is incomplete or inconsistent'));
+        if (status.malformedLogLines.length > 0) {
+            console.log(`  unreadable line(s): ${status.malformedLogLines.map(plain).join(', ')}`);
+        }
+        for (const problem of status.recordProblems)
+            console.log(`  ${plain(problem)}`);
+    }
+}
+//# sourceMappingURL=ready.js.map