toolroll 0.9.92 → 0.9.94

package/dist/release-approval.js

@@ -0,0 +1,382 @@
+/**
+ * One-tap release approval (docs/plans/trusted-release-reports.md, slice A v3): the plane's side of one push, one
+ * screen and one proof for a release a person must approve.
+ *
+ * - `releaseApprovalCard`: the authoritative card snapshot of a release task waiting for its person, for the sheet
+ *   (`/t/<id>/release`) and `toolroll release approve`: either sealed form (release terms or a release check's purpose),
+ *   the change list, GitHub CI as the coordinator last read it on the exact commit, why it can't be approved now (shown,
+ *   never hidden) and the card digest, which binds all of it.
+ * - `approveReleaseCard`: the one wrapper both doors call. It rebuilds the card, compares the digest the person saw,
+ *   re-reads the store's parts inside one transaction and only then passes THAT snapshot's scope digest into the
+ *   unchanged transactional `approve()` the caller hands in. The digest is never swapped after the person was asked.
+ * - The notification's whole life: `noteReleaseReady` (one per task and scope digest, older ones resolved), the push
+ *   class derived at send time from the plane's own state (`releasePushOf`), `noteReleaseStopped` for a manual
+ *   release's stop, and the coordinator's CI snapshots (`recordReleaseCi`).
+ * Nothing here proves a person, widens a proof or seals anything itself.
+ */
+import { createHash } from "node:crypto";
+import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { permissionPlainWords } from "./chat-terms.js";
+import { approvalTermsOf, releaseAccessWords, releaseCardOf, releaseSealOf } from "./release-card.js";
+import { releaseCiHoldOf, releaseCiHoldWords } from "./release-ci-hold.js";
+import { approvalOf } from "./scope.js";
+import { releaseProgressFor } from "./store.js";
+import { taskArchived } from "./task-archive.js";
+import { cleanTerminalLine } from "./terminal-text.js";
+const SHA = /^[0-9a-f]{40}$/;
+const DIGEST = /^[0-9a-f]{64}$/;
+/** A scope digest as scope.ts writes it. */
+const SCOPE_DIGEST = /^[0-9a-f]{32,64}$/;
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+// ---- GitHub CI as the coordinator read it -------------------------------------------------------------------------
+/** The ledger act holding the coordinator's latest reading of the pull request's CI on the exact candidate. */
+export const RELEASE_CI_SEEN_ACTION = "release CI observed";
+const ciName = (value) => cleanTerminalLine(String(value ?? "")).trim().slice(0, 120);
+/**
+ * Record what the coordinator just read of the pull request's CI on `candidate` (its verdict and every check's newest
+ * attempt), when it differs from the last reading recorded: the sheet and the CLI show it, and the card digest binds
+ * it. The coordinator is Toolroll's own runtime reading GitHub through the plane's recorded repository.
+ */
+export function recordReleaseCi(store, input) {
+    if (!SHA.test(input.candidate) || store.lookupRef(input.taskId) === null)
+        return false;
+    // The newest attempt of each check (the adapter lists attempts oldest first), by name.
+    const latest = new Map();
+    for (const run of input.runs.slice(0, 2_000)) {
+        const name = ciName(run.name);
+        if (name === "")
+            continue;
+        latest.set(name, { id: typeof run.id === "number" && Number.isSafeInteger(run.id) ? run.id : null, name, status: ciName(run.status).slice(0, 40), conclusion: run.conclusion === null ? null : ciName(run.conclusion).slice(0, 40) });
+    }
+    const runs = [...latest.values()].sort((a, b) => a.name.localeCompare(b.name)).slice(0, 200);
+    const detail = JSON.stringify({ v: 1, candidate: input.candidate, state: input.state, failed: input.failed.map(ciName).slice(0, 50), runs });
+    const last = store.handle.prepare("SELECT detail FROM action_ledger WHERE task_id = ? AND action = ? ORDER BY id DESC LIMIT 1").get(input.taskId, RELEASE_CI_SEEN_ACTION);
+    if (last !== undefined && last["detail"] === detail)
+        return false;
+    store.recordAction({ at: input.now.toISOString(), actor: "toolroll", repo: store.lookupRef(input.taskId)?.repo ?? null, taskId: input.taskId, runId: null,
+        action: RELEASE_CI_SEEN_ACTION, outcome: input.state, source: "work", detail });
+    return true;
+}
+/** The coordinator's latest CI reading for this task on exactly `candidate`, or null (not read yet, or another commit). */
+export function releaseCiOf(store, taskId, candidate) {
+    const row = store.handle.prepare("SELECT detail, at FROM action_ledger WHERE task_id = ? AND action = ? ORDER BY id DESC LIMIT 1").get(taskId, RELEASE_CI_SEEN_ACTION);
+    if (row === undefined)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(String(row["detail"]));
+    }
+    catch {
+        return null;
+    }
+    const one = parsed;
+    if (one.v !== 1 || one.candidate !== candidate || !["passed", "running", "failed"].includes(String(one.state)) || !Array.isArray(one.failed) || !Array.isArray(one.runs))
+        return null;
+    return { candidate, at: String(row["at"]), state: one.state, failed: one.failed.map(ciName),
+        runs: one.runs.map(run => { const r = run; return { id: typeof r["id"] === "number" ? r["id"] : null, name: ciName(r["name"]), status: ciName(r["status"]), conclusion: r["conclusion"] == null ? null : ciName(r["conclusion"]) }; }) };
+}
+/** What of a CI reading the card binds: its state and each check's attempt, whether it finished, and how. Queued and
+ * in progress read alike (neither is finished); the time it was read is not bound. */
+export function ciBinding(ci) {
+    return ci === null ? null : { candidate: ci.candidate, state: ci.state, failed: ci.failed, runs: ci.runs.map(run => [run.id, run.name, run.status === "completed", run.conclusion]) };
+}
+/** GitHub CI in one line, as the sheet and the CLI say it. */
+export function ciWords(ci, candidate) {
+    const short = candidate.slice(0, 7);
+    if (ci === null)
+        return `GitHub CI on ${short} hasn't been read yet.`;
+    if (ci.state === "passed")
+        return `GitHub CI passed on ${short}.`;
+    if (ci.state === "failed")
+        return `GitHub CI failed on ${short}: ${ci.failed.join(", ") || "a check"}.`;
+    const finished = ci.runs.filter(run => run.status === "completed").length;
+    return `GitHub CI is running on ${short}: ${finished} of ${ci.runs.length} checks finished.`;
+}
+/** The release check failed on this task already (the coordinator's record): nobody approves it again here. */
+function checkFailed(store, taskId) {
+    return store.handle.prepare("SELECT 1 FROM release_step WHERE task_id = ? AND step = 'check' AND state = 'failed' LIMIT 1").get(taskId) !== undefined;
+}
+/** Why a release can't be approved now, from the plane's own state, or null. */
+function refusalOf(store, taskId, scope, ci) {
+    if (taskArchived(store, taskId))
+        return "This release is put away. Restore it before approving.";
+    const hold = releaseCiHoldOf(store, taskId);
+    if (hold !== null)
+        return releaseCiHoldWords(hold);
+    if (ci?.state === "failed")
+        return `${ciWords(ci, scope.candidate)} Fix the branch or rerun the failed job on GitHub, then release again.`;
+    if (checkFailed(store, taskId))
+        return "The release check already failed on this commit. Fix the branch and release the new commit.";
+    if (scope.approvedAt !== null && scope.approvedDigest !== scope.digest)
+        return "The release's terms changed after an earlier approval. Read them again.";
+    return null;
+}
+/** A release task from the plane's own state: a sealed form (terms or a release check's purpose) whose repository is the
+ * task's project and whose approved commit is the scope's candidate. Never from a title or a task id. */
+export function releaseTaskOf(store, taskId) {
+    const ref = store.lookupRef(taskId);
+    const scope = store.getScope(taskId);
+    const seal = releaseSealOf(scope);
+    if (ref === null || ref.repo === null || scope === null || seal === null || scope.candidate == null || scope.candidate !== seal.identity.approvedSha || seal.identity.repo !== ref.repo)
+        return null;
+    return { ref: { id: ref.id, repo: ref.repo }, scope, seal };
+}
+/** The authoritative card for a release task waiting for its person, or why there is none. Reads only. */
+export function releaseApprovalCard(store, taskId, options = {}) {
+    const found = releaseTaskOf(store, taskId);
+    if (found === null)
+        return { ok: false, why: "This isn't a release waiting for approval." };
+    const { ref, scope, seal } = found;
+    const terms = approvalTermsOf(store, scope, { profile: permissionPlainWords });
+    const card = releaseCardOf(store, scope, scope.digest, { profile: permissionPlainWords }, options.read);
+    const ci = releaseCiOf(store, taskId, scope.candidate);
+    const approval = approvalOf(scope);
+    const approved = approval.approved ? { by: approval.by, at: approval.at } : null;
+    const refusal = approved === null ? refusalOf(store, taskId, scope, ci) : null;
+    const progress = releaseProgressFor(store, taskId);
+    const stopped = progress?.stopped == null ? null : { step: progress.stopped.step, message: cleanTerminalLine(progress.stopped.message).slice(0, 300) };
+    const digest = sha256(`release-sheet:v1:${JSON.stringify([card.digest, scope.digest, ciBinding(ci), refusal, approved])}`);
+    return { ok: true, card: { taskId, taskRef: ref.id, repo: ref.repo, scope, seal, card, terms, ci, refusal, approved, stopped, digest } };
+}
+/** What approving does, in the sheet's and the CLI's words: the consequence, the check's access, and whether later
+ * commits carry. */
+export function releaseConsequence(card) {
+    const id = card.seal.identity;
+    const carries = card.seal.kind === "terms" && card.seal.terms.policy.carry;
+    return [
+        `Approving runs the release check on ${id.approvedSha.slice(0, 7)}, then deploys, merges, tags and publishes once GitHub CI and the check pass.`,
+        ...(releaseAccessWords(id.access) === null ? [] : [releaseAccessWords(id.access)]),
+        carries ? "Later commits that only change tests, docs or the changelog carry this approval." : "Every later commit asks again.",
+    ];
+}
+/**
+ * The one card-approval wrapper (Codex round 2, finding 2): rebuild the authoritative card and compare the digest the
+ * person saw; then, in one transaction, re-read the store's parts (the scope digest, the CI reading, the refusal state)
+ * and refuse on any change; then hand THAT snapshot's scope digest to `approveNow`, the caller's unchanged
+ * transactional `approve()`, which proves the person and seals. Nothing here proves anyone.
+ */
+export function approveReleaseCard(store, input) {
+    if (!DIGEST.test(input.cardDigest))
+        return { ok: false, reason: "changed", message: "This release changed while you were reading it. Read it again." };
+    const built = releaseApprovalCard(store, input.taskId, input.read === undefined ? {} : { read: input.read });
+    if (!built.ok)
+        return { ok: false, reason: "not-release", message: built.why };
+    const card = built.card;
+    if (card.digest !== input.cardDigest)
+        return { ok: false, reason: "changed", message: "This release changed while you were reading it. Read it again." };
+    if (card.approved !== null)
+        return { ok: false, reason: "approved", message: `Already approved by ${card.approved.by}.` };
+    if (card.refusal !== null)
+        return { ok: false, reason: "refused", message: card.refusal };
+    return store.transact(() => {
+        const scope = store.getScope(input.taskId);
+        if (scope === null || scope.digest !== card.scope.digest || approvalOf(scope).approved)
+            return { ok: false, reason: "changed", message: "This release changed while you were reading it. Read it again." };
+        const ci = releaseCiOf(store, input.taskId, card.scope.candidate);
+        const refusal = refusalOf(store, input.taskId, scope, ci);
+        if (JSON.stringify(ciBinding(ci)) !== JSON.stringify(ciBinding(card.ci)) || refusal !== card.refusal) {
+            return { ok: false, reason: "changed", message: "This release changed while you were reading it. Read it again." };
+        }
+        const result = input.approveNow(card.scope.digest);
+        return result.ok ? { ok: true, scope: result.scope } : { ok: false, reason: "approve", result };
+    });
+}
+// ---- notifications --------------------------------------------------------------------------------------------
+export const RELEASE_READY_KIND = "release-ready";
+export const RELEASE_STOPPED_KIND = "release-stopped";
+/** The one push phrase for a release waiting on its person (push.ts PUSH_WORDS.release). */
+export const RELEASE_PUSH_WORDS = "A release is ready for your approval";
+const READY_KEY = /^release-ready:([1-9][0-9]{0,14}):([0-9a-f]{32,64})$/;
+/** The sheet's own address for a task (the in-app link; a push carries the opaque `/approve/<task ref>` instead). */
+export const releaseSheetHref = (taskId) => `/t/${encodeURIComponent(taskId)}/release`;
+/**
+ * The coordinator asked a person (on entering the approval step, a fresh filing or a resumed one): one notification per
+ * task and stable scope digest, so a crash between filing and asking is healed by the next run and a repeat says nothing
+ * new. Every older `release-ready` row of the project (another task or digest) is resolved first. Nothing when the task
+ * isn't a release waiting for a person.
+ */
+export function noteReleaseReady(store, input) {
+    return store.transact(() => {
+        const found = releaseTaskOf(store, input.taskId);
+        if (found === null || approvalOf(found.scope).approved || taskArchived(store, input.taskId))
+            return false;
+        const key = `release-ready:${found.ref.id}:${found.scope.digest}`;
+        store.handle.prepare("UPDATE notification SET resolved_at = ? WHERE kind = ? AND resolved_at IS NULL AND project = ? AND dedupe_key <> ?")
+            .run(input.now.toISOString(), RELEASE_READY_KIND, found.ref.repo, key);
+        const id = found.seal.identity;
+        const short = id.approvedSha.slice(0, 7);
+        const ci = releaseCiOf(store, input.taskId, id.approvedSha);
+        const body = ci?.state === "passed"
+            ? `GitHub CI passed on ${short}. Approve to run the release check, deploy, merge and publish.`
+            : `Release ${id.packageVersion} (${short}) is ready to approve. You can approve now: Toolroll runs the release check after your yes, and deploys, merges and publishes only once GitHub CI and the check pass. You're told if something fails.`;
+        return store.enqueueNotification({ dedupeKey: key, kind: RELEASE_READY_KIND, pushClass: "decision", link: releaseSheetHref(input.taskId), source: { taskRef: found.ref.id },
+            subject: `Release ${id.packageVersion} is ready for your approval`, body }, input.now);
+    });
+}
+/** Resolve a task's `release-ready` rows (it was approved, or the release stopped): a push not sent yet never is. */
+export function retireReleaseReady(store, taskRef, now) {
+    return Number(store.handle.prepare("UPDATE notification SET resolved_at = ? WHERE kind = ? AND resolved_at IS NULL AND task_ref = ?").run(now.toISOString(), RELEASE_READY_KIND, taskRef).changes);
+}
+/**
+ * The push class `release` and its link, derived at send time from the plane's own state, never from a title, a task id,
+ * the stored link or the stored class: the row is a `release-ready` row for exactly its task ref and a scope digest, and
+ * that task is a release scope (terms or a release check's purpose, its candidate the approved commit), not put away,
+ * not approved, at that same digest. Null otherwise.
+ */
+export function releasePushOf(store, notification) {
+    if (notification.kind !== RELEASE_READY_KIND || notification.taskRef === null || notification.resolvedAt !== null)
+        return null;
+    const key = READY_KEY.exec(notification.dedupeKey);
+    if (key === null || Number(key[1]) !== notification.taskRef)
+        return null;
+    const ref = store.refForId(notification.taskRef);
+    if (ref === null || ref.backend !== "built-in")
+        return null;
+    const found = releaseTaskOf(store, ref.externalId);
+    if (found === null || found.ref.id !== notification.taskRef)
+        return null;
+    if (found.scope.digest !== key[2] || approvalOf(found.scope).approved || taskArchived(store, ref.externalId))
+        return null;
+    return { link: `/approve/${notification.taskRef}` };
+}
+/** A `release-ready` row that no longer stands (the push pass resolves it instead of sending it). */
+export function releaseReadyObsolete(store, notification) {
+    return notification.kind === RELEASE_READY_KIND && releasePushOf(store, notification) === null;
+}
+/**
+ * A person's release stopped (CI failed, the check failed, the deploy, the merge, the tag or publication failed, or it
+ * stopped waiting): one attention notification per task, step and reason, with the stop's words in the app (the push
+ * says only the fixed attention phrase). Its `release-ready` row is resolved, except while it only stopped waiting
+ * for the approval (the sheet still approves it then).
+ */
+export function noteReleaseStopped(store, input) {
+    const ref = store.lookupRef(input.taskId);
+    if (ref === null)
+        return false;
+    const step = /^[a-z-]{1,20}$/.test(input.step) ? input.step : "release";
+    const reason = /^[a-z-]{1,40}$/.test(input.reason) ? input.reason : "error";
+    return store.transact(() => {
+        if (!(step === "approval" && reason === "timeout"))
+            retireReleaseReady(store, ref.id, input.now);
+        const seal = releaseSealOf(store.getScope(input.taskId));
+        const words = cleanTerminalLine(input.message).replace(/\s+/g, " ").trim().slice(0, 600);
+        return store.enqueueNotification({ dedupeKey: `release-stopped:${ref.id}:${step}:${reason}`, kind: RELEASE_STOPPED_KIND, pushClass: "attention",
+            link: `/t/${encodeURIComponent(input.taskId)}`, source: { taskRef: ref.id },
+            subject: `Release${seal === null ? "" : ` ${seal.identity.packageVersion}`} stopped at ${step}`, body: words === "" ? "The release stopped. Open it to see why." : words }, input.now);
+    });
+}
+// ---- the terminal -------------------------------------------------------------------------------------------------
+/** The card as the CLI prints it, every line control-free (src/terminal-text.ts). */
+export function releaseCardLines(card) {
+    const id = card.seal.identity;
+    const changes = card.card.changes;
+    const lines = [
+        `Release ${id.packageVersion} · pull request #${id.pr} · ${id.branch}`,
+        `Commit ${id.approvedSha}`,
+        ciWords(card.ci, id.approvedSha),
+        ...releaseConsequence(card),
+        ...(card.stopped === null ? [] : [`The release isn't running (it stopped at ${card.stopped.step}). After you approve, run \`toolroll release ${id.branch}\`.`]),
+        "",
+        changes.commits === null
+            ? `What changed couldn't be read${changes.why === undefined ? "" : ` (${changes.why})`}.`
+            : changes.baseline === null ? `Pull request #${id.pr}'s commits (${changes.commits.length}):` : `Changes since the last verified release (${changes.baseline.slice(0, 7)}), ${changes.commits.length}:`,
+        ...(changes.commits ?? []).map(one => `  ${one.sha.slice(0, 7)} ${one.subject}`),
+        "",
+        "Every term:",
+        ...card.terms.map(line => `  ${line.label}: ${line.value}`),
+        ...(card.refusal === null ? [] : ["", `Can't approve now: ${card.refusal}`]),
+    ];
+    return lines.map(cleanTerminalLine);
+}
+const BRANCH = /^[A-Za-z0-9._/-]{1,255}$/;
+const TASK_ID = /^[A-Za-z0-9._-]{1,200}$/;
+const VERSION = /^\d+\.\d+\.\d+$/;
+/** A journal's own fields, strictly; null when any is missing or not its exact shape. */
+export function readWaitingJournal(file, raw, expectedFile) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const j = raw;
+    const task = j["task"];
+    const candidate = j["candidate"];
+    if (j["version"] !== 1 || (j["step"] !== "approval" && j["step"] !== "gate"))
+        return null;
+    if (typeof j["branch"] !== "string" || !BRANCH.test(j["branch"]) || j["branch"].startsWith("-") || j["branch"].includes(".."))
+        return null;
+    if (typeof j["checkout"] !== "string" || !j["checkout"].startsWith("/") || typeof j["packageVersion"] !== "string" || !VERSION.test(j["packageVersion"]))
+        return null;
+    if (typeof j["pr"] !== "number" || !Number.isSafeInteger(j["pr"]) || j["pr"] < 1)
+        return null;
+    if (task === null || typeof task !== "object" || typeof task["id"] !== "string" || !TASK_ID.test(task["id"]) || typeof task["scopeDigest"] !== "string" || !SCOPE_DIGEST.test(task["scopeDigest"]))
+        return null;
+    if (candidate === null || typeof candidate !== "object" || typeof candidate["sha"] !== "string" || !SHA.test(candidate["sha"]))
+        return null;
+    // The file must be the one its own branch maps to: two branches that map to one file name never stand in for each other.
+    if (expectedFile(j["branch"]) !== file)
+        return null;
+    return { file, branch: j["branch"], checkout: j["checkout"], taskId: task["id"], scopeDigest: task["scopeDigest"], candidate: candidate["sha"], version: j["packageVersion"], pr: j["pr"] };
+}
+const real = (path) => { try {
+    return realpathSync(path);
+}
+catch {
+    return null;
+} };
+/**
+ * Whether a journal (discovery only) names exactly the release the plane sealed: the task is a release scope whose
+ * sealed identity has this exact branch, version, pull request and candidate at this scope digest, and the journal's
+ * checkout, the task's project and the sealed repository are one real folder (`repo` too, when given). Why not, in words.
+ */
+export function journalMatchesPlane(store, journal, repo) {
+    const found = releaseTaskOf(store, journal.taskId);
+    if (found === null)
+        return { ok: false, why: `${journal.branch}'s release task isn't a release this plane can approve` };
+    const id = found.seal.identity;
+    if (id.branch !== journal.branch || id.packageVersion !== journal.version || id.pr !== journal.pr || id.approvedSha !== journal.candidate) {
+        return { ok: false, why: `${journal.branch}'s journal doesn't name the release the plane sealed (branch ${id.branch}, ${id.packageVersion}, #${id.pr}, ${id.approvedSha.slice(0, 7)})` };
+    }
+    if (found.scope.digest !== journal.scopeDigest)
+        return { ok: false, why: `the release's terms changed since ${journal.branch} was filed; run \`toolroll release\` again` };
+    const checkout = real(journal.checkout), project = real(found.ref.repo), sealed = real(id.repo);
+    if (checkout === null || project === null || checkout !== project || sealed !== project)
+        return { ok: false, why: `${journal.branch}'s checkout isn't the project the release was sealed for` };
+    if (repo !== null && real(repo) !== project)
+        return { ok: false, why: `${journal.branch} isn't a release of ${repo}` };
+    return { ok: true };
+}
+/** Every release journal in the state folder, read strictly; unreadable ones are counted, never guessed at. */
+export function waitingJournals(stateDir, expectedFile) {
+    const folder = join(stateDir, "releases");
+    let names = [];
+    try {
+        names = readdirSync(folder).filter(name => name.endsWith(".json"));
+    }
+    catch {
+        return { journals: [], unreadable: [] };
+    }
+    const journals = [], unreadable = [];
+    for (const name of names.sort()) {
+        const file = join(folder, name);
+        let raw;
+        try {
+            if (!lstatSync(file).isFile()) {
+                unreadable.push(name);
+                continue;
+            }
+            raw = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            unreadable.push(name);
+            continue;
+        }
+        const step = raw?.step;
+        if (step !== "approval" && step !== "gate")
+            continue;
+        const read = readWaitingJournal(file, raw, expectedFile);
+        if (read === null)
+            unreadable.push(name);
+        else
+            journals.push(read);
+    }
+    return { journals, unreadable };
+}

package/dist/release-auto.js

@@ -18,8 +18,8 @@ import { fullCheckProblem, projectGitDir } from "./check-report.js";
 import { sealedRun } from "./release-recheck.js";
 import { runCheckLevel } from "./check-levels.js";
 import { readVerifiedCommit, verifiedBlobs, verifiedTreeDiff, verifiedTreeEntries } from "./commit-extract.js";
-import { EVAL_HOOK_FILES, evalHookProblem, storeRewriteProblem } from "./eval-hooks.js";
-import { mightName, testInfrastructure } from "./test-infra.js";
+import { EVAL_HOOK_FILES, evalHookProblem, LEARNING_HOOK_FILES, learningHookProblem, storeRewriteProblem } from "./eval-hooks.js";
+import { isTestPath, mightName, testImportProblem, testInfrastructure } from "./test-infra.js";
 import { chatControlHref } from "./chat-controls.js";
 import { INFRA_RERUNS_PER_CANDIDATE, REQUIRED_PR_CHECKS, REQUIRED_PR_CHECKS_WORKFLOW, prChecksVerdict } from "./release.js";
 import { releaseCheckStanding } from "./check-failure.js";
@@ -185,8 +185,11 @@ const TEST_FILE = /^(?!.*(^|\/)fixtures?\/)[^]*\.test\.ts$/;
  * accounting readings evals trust (reported-usage.ts, run-efficiency.ts). Where they are called from, and the store's
  * accounting reads, are held by eval-hooks.ts instead (evalHookProblem). Results routing's policy is here too
  * (docs/plans/results-routing.md, Protection 1): the record evaluator, the rules, the one writer module, this scan's
- * manifest and the record contract; their callers and pinned bodies are route-hooks.ts's (routingHookProblem). */
-const EVAL_POLICY = /^(evals\/|src\/evals[^/]*\.ts$|src\/eval-[^/]*\.ts$|src\/reviewer-evals\.ts$|src\/nightly-github\.ts$|src\/contracts\/evals[^/]*\.ts$|src\/reported-usage\.ts$|src\/run-efficiency\.ts$|src\/route-(?:results|rules|store|hooks)\.ts$|src\/contracts\/route-results\.ts$)/;
+ * manifest and the record contract; their callers and pinned bodies are route-hooks.ts's (routingHookProblem). The
+ * learning-loops policy modules are here whole (docs/plans/learning-loops.md, Protection 1): check facts, flaky tests
+ * (local and CI), lesson notes, memory use and tidy-up; their callers, pinned bodies and SQL writers are eval-hooks.ts's
+ * (learningHookProblem). */
+const EVAL_POLICY = /^(evals\/|src\/evals[^/]*\.ts$|src\/eval-[^/]*\.ts$|src\/reviewer-evals\.ts$|src\/nightly-github\.ts$|src\/contracts\/evals[^/]*\.ts$|src\/reported-usage\.ts$|src\/run-efficiency\.ts$|src\/route-(?:results|rules|store|hooks)\.ts$|src\/contracts\/route-results\.ts$|src\/(?:check-facts|flaky|flaky-ci|lesson-notes|memory-use|memory-tidy)\.ts$)/;
 /** Build or type configuration anywhere: a person approves it. */
 const BUILD_CONFIG = /(^|\/)(tsconfig[^/]*\.json|[^/]*\.config\.[cm]?[jt]s|\.npmrc|\.nvmrc|\.node-version)$/;
 /**
@@ -212,7 +215,7 @@ export function autoPathProblem(path) {
     // Test files under test/ carry the same trust as src's (Alex: test authors are trusted) — only the `.test.ts` files
     // themselves, never a helper, fixture, setup or config file beside them, nor one inside a fixtures folder.
     if (EVAL_POLICY.test(normal))
-        return "it's eval, nightly or model routing policy code";
+        return "it's eval, nightly, model routing or learning policy code";
     if (testUnderTest)
         return null;
     if (BUILD_CONFIG.test(normal))
@@ -343,6 +346,12 @@ function changeProblem(repo, base, candidate) {
     const routing = routingHookProblem({ candidate: routingAt(after.value.tree), base: routingAt(before.value.tree) }, { paths: changed, candidate: changedAt(after.value.tree), base: changedAt(before.value.tree) });
     if (routing !== null)
         return `${routing}: a person decides`;
+    // Learning loops (eval-hooks.ts learningHookProblem): the calls that record a check's facts, the strictly pinned
+    // memory and check bodies the base holds, and no changed file writing a learning-loops table outside its writers.
+    const learningAt = (tree) => { const blobs = verifiedBlobs(gitDir, tree, LEARNING_HOOK_FILES); return (file) => blobs.ok ? blobs.value.get(file)?.bytes ?? null : null; };
+    const learning = learningHookProblem({ candidate: learningAt(after.value.tree), base: learningAt(before.value.tree) }, { paths: changed, candidate: changedAt(after.value.tree), base: changedAt(before.value.tree) });
+    if (learning !== null)
+        return `${learning}: a person decides`;
     for (const change of diff.value) {
         const modes = [change.before?.mode, change.after?.mode].filter((one) => one !== undefined);
         if (modes.includes("120000") || modes.includes("160000"))
@@ -350,18 +359,18 @@ function changeProblem(repo, base, candidate) {
         // Taking a test away is never automatic, wherever it lives.
         if (change.kind === "deleted" && TEST_FILE.test(rulePath(change.path)))
             return `${change.path} was deleted (removing a test needs a person)`;
-        if (change.before !== null && TEST_FILE.test(rulePath(change.path))) {
-            // Counts cannot prove that an assertion survived: replacing it, commenting it out, or skipping its case can
-            // leave the counts unchanged. Only append-only additions preserve the existing code without interpretation.
-            // Both copies come from verified trees; no report or candidate-provided file list decides this permission.
-            const was = verifiedBlobs(gitDir, before.value.tree, [change.path]);
-            const now = verifiedBlobs(gitDir, after.value.tree, [change.path]);
-            if (!was.ok || !now.ok)
-                return `${change.path}'s existing test code couldn't be read (a person decides)`;
-            const original = was.value.get(change.path)?.bytes, revised = now.value.get(change.path)?.bytes;
-            if (original === undefined || revised === undefined || !revised.subarray(0, original.length).equals(original)) {
-                return `${change.path} changes existing test code (removing or rewriting tests needs a person)`;
-            }
+        // Counts cannot prove that an assertion survived, and an appended line can disarm what it follows (`vi.mock` hoists,
+        // a top-level hook reaches every case): a test file that was there stays exactly as it was (H4).
+        if (change.before !== null && TEST_FILE.test(rulePath(change.path)))
+            return `${change.path} changes existing test code (new tests go in a new file; rewriting tests needs a person)`;
+        // A new test may not reach into another: it would run that file's code, and its mocks, here. From the verified tree.
+        // Any test extension: `src/` passes autoPathProblem whatever the file is called, so `.test.ts` alone would miss `.test.tsx`.
+        if (change.kind === "added" && isTestPath(rulePath(change.path))) {
+            const read = verifiedBlobs(gitDir, after.value.tree, [change.path]);
+            const bytes = read.ok ? read.value.get(change.path)?.bytes : undefined;
+            const why = bytes === undefined ? `${change.path}'s test code couldn't be read` : testImportProblem(change.path, bytes.toString("utf8"));
+            if (why !== null)
+                return `${why} (a person decides)`;
         }
         const why = autoPathProblem(change.path);
         if (why !== null)

package/dist/release-card.d.ts

@@ -1,6 +1,6 @@
-import { type ReleaseTerms } from "./contracts/release-terms.js";
+import { type ReleaseCheckPurpose, type ReleaseTerms } from "./contracts/release-terms.js";
 import type { Scope } from "./scope.js";
-import type { Store } from "./store.js";
+import { type Store } from "./store.js";
 /** One signed term as the card says it. `key` names the scope field or the release term's path. */
 export type TermLine = {
     key: string;
@@ -29,6 +29,23 @@ export declare const SCOPE_TERM_LABELS: {
 /** Every field of the release terms, by its path in the terms (contracts/release-terms.ts), against the schema's
  * own leaves: the contract test checks every one has a label. */
 export declare const RELEASE_TERM_LABELS: Readonly<Record<string, string>>;
+/** Every field of a release check's purpose (contracts/release-terms.ts releaseCheckPurposeSchema): the sealed form
+ * Toolroll's own releases take while their checks run outside the sandbox. A contract test checks every leaf has one. */
+export declare const RELEASE_CHECK_LABELS: Readonly<Record<string, string>>;
+/** What a release scope sealed, either form: release terms (later test-only commits may carry) or a release check's
+ * purpose (every later commit asks again). The identity both share is read from here, never from a title or an id. */
+export type ReleaseSeal = {
+    kind: "terms";
+    terms: ReleaseTerms;
+    identity: ReleaseTerms;
+} | {
+    kind: "check";
+    purpose: ReleaseCheckPurpose;
+    identity: ReleaseCheckPurpose;
+};
+export declare function releaseSealOf(scope: Pick<Scope, "releaseTerms" | "releaseCheck"> | null): ReleaseSeal | null;
+/** What an unsandboxed (or sign-ins) release check means, said before anyone approves it. Null in the sandbox. */
+export declare function releaseAccessWords(access: ReleaseTerms["access"]): string | null;
 /** The leaf paths of a zod object schema (nested objects joined with dots). */
 export declare function schemaLeaves(schema: unknown, prefix?: string): string[];
 /** Every signed term of `scope`, its release terms included, one line each. Reads only. */
@@ -48,6 +65,9 @@ export type ChangeList = {
     digest: string;
     /** A release is on the record but its merge commit can't be read (eval-harness review 2, finding 4). */
     baselineUnreadable?: true;
+    /** Why the list couldn't be read whole (Codex round 2, finding 6): the pull request moved, or it is longer than
+     * GitHub lists. Part of the digest; never a shortened list. */
+    why?: string;
 };
 /**
  * The plane's own record of the last verified release of `repo`: the merge commit GitHub answered with, recorded once
@@ -70,8 +90,57 @@ export declare function commitsBetween(repo: string, from: string, to: string):
     sha: string;
     subject: string;
 }[] | null;
-/** What changed since the last verified release, for a release's terms, from Toolroll's records only. */
-export declare function releaseChangeList(store: Store, terms: ReleaseTerms): ChangeList;
+/** GitHub lists at most this many of a pull request's commits; a longer one is never shown as complete. */
+export declare const PULL_REQUEST_COMMITS_MAX = 250;
+/** A commit subject is someone else's text: one line, control-free (src/terminal-text.ts), bounded. The card digest
+ * binds this cleaned text, so every surface shows exactly what was bound (Codex round 2, finding 7). */
+export declare const subjectText: (subject: string) => string;
+/** How the plane reads GitHub for a pull request's commits (a seam for tests). */
+export type PullRequestReader = (args: readonly string[]) => {
+    status: number | null;
+    stdout: string;
+};
+/**
+ * A pull request's own commits from GitHub, for the recorded owner/name, complete and bound to the candidate (Codex
+ * round 2, finding 6): every page (`--paginate`), accepted only when the pull request's head is `head`, the newest
+ * listed commit is `head` and the count is the pull request's own count. Otherwise why, never a shortened list.
+ */
+export declare function pullRequestCommits(slug: string, pr: number, head: string, read?: PullRequestReader): {
+    ok: true;
+    commits: {
+        sha: string;
+        subject: string;
+    }[];
+} | {
+    ok: false;
+    why: string;
+};
+/** The ledger act that records a verified release (the merged tree proved equal to the approved one). */
+export declare const RELEASE_VERIFIED_ACTION = "release verified";
+/**
+ * Record a verified release (Codex round 2, finding 1: verified release history apart from carrying). The coordinator
+ * calls it once main's merge commit was proved to hold the approved tree; the plane proves it again here, from its own
+ * records only: the task is a release scope of a project, and `merge` read as a verified Git object from the project's
+ * recorded Git directory has exactly the sealed approved tree. False when anything doesn't hold (nothing written).
+ */
+export declare function recordVerifiedRelease(store: Store, input: {
+    taskId: string;
+    merge: string;
+    now: Date;
+}): boolean;
+/**
+ * The last verified release of `repo`, from either record: a merged release authority's succeeded merge, or a verified
+ * release row (recordVerifiedRelease). The newer stands. Shaped as releaseBaselineRecord.
+ */
+export declare function verifiedReleaseBaseline(store: Store, repo: string): {
+    recorded: false;
+} | {
+    recorded: true;
+    sha: string | null;
+};
+/** What changed since the last verified release, for a release's sealed identity (terms or a release check's purpose),
+ * from Toolroll's records only. */
+export declare function releaseChangeList(store: Store, terms: Pick<ReleaseTerms, "repo" | "approvedSha" | "pr">, read?: PullRequestReader): ChangeList;
 export type ReleaseCard = {
     /** Binds the scope digest, the plan form's digest, the baseline and the change list. */
     digest: string;
@@ -82,7 +151,6 @@ export type ReleaseCard = {
 };
 /** The card digest: everything the person is shown that can change under them. */
 export declare function cardDigestOf(scopeDigest: string, formDigest: string, changes: Pick<ChangeList, "baseline" | "digest">): string;
-/** The release card for a deploy gate, against the live records now. */
 export declare function releaseCardOf(store: Store, scope: Scope, formDigest: string, words: {
     profile: (profile: Scope["profile"]) => string | null;
-}): ReleaseCard;
+}, read?: PullRequestReader): ReleaseCard;