toolroll 0.9.103 → 0.9.105

package/dist/nightly-check.js

@@ -1,19 +1,3 @@
-/**
- * The nightly full check on main (docs/plans/release-once.md, part 3): a safety net for accidental omissions, not a
- * deadline.
- *
- * - A scheduled flow (flow-schedule.ts) whose standing order names `check: main-full`. A person approves it once, with
- *   their password: the approval binds the release check grant (id and digest), the fenced check access and the
- *   check-only capability, for future main commits. Each firing files `nightly-<date>-<sha7>` at main's head — never a
- *   release branch — sealed with basis `schedule`; that task can't deploy, merge or complete.
- * - A failing nightly writes one `main_check_failure` row per failed item (each failed identity, each group or version,
- *   or the whole part for a part-level outcome) and sends one attention notification.
- * - A row clears only when a qualifying full pass covers that exact item: intended mode full and coverage full, on a
- *   commit that contains the failed main commit (verified ancestry), the item or its whole part ran and passed there.
- *   A composed result never clears anything; a pass that covers one item never clears another.
- * - Open rows refuse targeted planning and block the deploy and merge of a composed release (scope.ts liveReleaseOf).
- * - A missed, stalled or disabled nightly gives no signal but its flow's own health notice after 26 hours.
- */
 import { createHash } from "node:crypto";
 import { projectGitDir } from "./check-report.js";
 import { readVerifiedCommit, verifiedFirstParentWalk } from "./commit-extract.js";
@@ -23,31 +7,19 @@ import { failedIdentities, sealedRun } from "./release-recheck.js";
 import { verificationEvidence } from "./verification-evidence.js";
 import { BUILT_IN, TRUSTED_MAIN_ACTION, forgetTrustedMain, recordTrustedMain, trustedRemoteIdentity } from "./store.js";
 import { teardownGit } from "./teardown-git.js";
-/** Where the project's Git store keeps the objects of the remote main the plane read (they matter, the ref doesn't). */
 const NIGHTLY_MAIN_REF = "refs/toolroll/remote-main";
 import { RemoteMains } from "./remote-main.js";
 import { run } from "./exec.js";
-/** How long a nightly may be missing before its flow says so. */
 export const NIGHTLY_MISSED_MS = 26 * 60 * 60_000;
 export const NIGHTLY_STEM = "nightly";
-/** What every nightly firing files: fixed here, never read from the trigger's settings. */
 export const NIGHTLY_GOAL = "Run the full release check on main's head.";
 export const NIGHTLY_NOT = "Changing anything: this is a check only.";
 export const NIGHTLY_ACCEPTANCE = Object.freeze([{ id: "c1", statement: "The full release check passes on main", how: null, evidence: ["check"] }]);
-/** The ledger act that records a person's approval of a nightly check, keyed by its trigger. */
 export const NIGHTLY_APPROVED = "nightly check approved";
-/** The ledger act that records a person turning GitHub's nightly into release debt for a project (nightly-github.ts). */
 export const GITHUB_NIGHTLY_ON = "github nightly debt on";
-/** The digest a person's approval of the nightly signs: the trigger, the project, the schedule, the check-only terms
- * and the fixed words each firing files. */
 export function nightlyDigestOf(trigger, repo, schedule, check) {
     return createHash("sha256").update(`nightly-check:${JSON.stringify({ trigger, repo, schedule, check, goal: NIGHTLY_GOAL, not: NIGHTLY_NOT, acceptance: NIGHTLY_ACCEPTANCE })}`).digest("hex").slice(0, 32);
 }
-/**
- * The approval of a nightly check as the plane recorded it when a person proved themselves (createNightlyCheckFlow):
- * the newest ledger row for this trigger. The trigger's own settings never stand in for it — anyone who can edit them
- * could write one.
- */
 export function nightlyApprovalOf(store, trigger) {
     for (const row of store.handle.prepare("SELECT outcome, detail FROM action_ledger WHERE action = ? ORDER BY id DESC LIMIT 20").all(NIGHTLY_APPROVED)) {
         try {
@@ -64,17 +36,9 @@ export function nightlyApprovalOf(store, trigger) {
     }
     return null;
 }
-/** How often the watch loop reads each recorded remote's main again, and how old a read may be when a nightly fires
- * or debt is cleared against it (review round 2: one window, two refreshes wide, for both decisions). */
 export const TRUSTED_MAIN_REFRESH_MS = 30 * 60_000;
 export const TRUSTED_MAIN_FIRE_MS = 60 * 60_000;
 export const TRUSTED_MAIN_CLEAR_MS = TRUSTED_MAIN_FIRE_MS;
-/**
- * Main's head as Toolroll's own process last read it from the project's RECORDED remote (remote-main.ts: the recorded
- * URL, a private plane-owned Git directory, objects that arrive only by fetch) — never a ref in the project's Git
- * directory, which a build shares and can move (review round 1). Null when there is no read young enough, when the
- * last read failed, or when the read was of another remote than the one recorded now (review round 2).
- */
 export function trustedMainOf(store, repo, now, maxAgeMs) {
     const row = store.handle.prepare("SELECT outcome, at, detail FROM action_ledger WHERE repo = ? AND action = ? ORDER BY id DESC LIMIT 1").get(repo, TRUSTED_MAIN_ACTION);
     if (row === undefined || now.getTime() - Date.parse(String(row["at"])) > maxAgeMs)
@@ -93,11 +57,6 @@ export function trustedMainOf(store, repo, now, maxAgeMs) {
     }
     return sha;
 }
-/** The watch loop's read of each project's recorded remote main that the nightly check, GitHub's nightly (its runs count
- * only at commits on main's history) or main's debt needs, at most
- * every 30 minutes. Each read is a fresh fetch into a private directory. A failed read forgets the last one. A good
- * one hands its verified objects to the project's Git store (hardened git, content-addressed: git checks every object
- * against its hash, and filing verifies the commit again), so the nightly can check a merge the checkout never pulled. */
 export async function refreshTrustedMains(store, root, now, runner = run) {
     const repos = new Set([
         ...store.handle.prepare("SELECT DISTINCT repo FROM main_check_failure WHERE cleared_at IS NULL").all().map(row => String(row["repo"])),
@@ -124,10 +83,6 @@ export async function refreshTrustedMains(store, root, now, runner = run) {
     }
     return read;
 }
-/**
- * Set up the nightly full check for a project, approved by a person proved now (their password or a re-check; never a
- * lead or remote token). Its schedule starts paused unless `start`; turning it on is the flow's own switch.
- */
 export function createNightlyCheckFlow(store, input, now) {
     const proved = authenticateApprover(store, input.as, input.token, input.repo);
     if (!proved.ok || !personProof(proved.method))
@@ -138,7 +93,6 @@ export function createNightlyCheckFlow(store, input, now) {
     if (store.projectCheckAccess(input.repo) !== "sandboxed")
         return { ok: false, message: "The project's checks run outside the sandbox; the nightly check runs only inside it." };
     const check = { kind: "main-full", grant: { id: grant.id, digest: grant.digest }, access: "sandboxed" };
-    // The order carries no approval: the person's yes is the plane's own ledger row, written below.
     const order = {
         stem: NIGHTLY_STEM, goal: NIGHTLY_GOAL, outOfScope: NIGHTLY_NOT, touches: [], requirements: [], acceptance: [...NIGHTLY_ACCEPTANCE], budgetPerRunMicrousd: null, costCeilingUsd: null,
         singleFlight: true, filedBy: input.as, routine: null, approval: null, check,
@@ -157,12 +111,9 @@ export function createNightlyCheckFlow(store, input, now) {
         return { ok: true, flow, trigger };
     });
 }
-/** A nightly firing (fileStandingOrder routes here): the approval checked again, main's head read, one check-only task
- * filed and sealed by its standing order. */
 export function fileNightlyCheck(store, input, now) {
     const { order, repo } = input;
     const check = order.check;
-    // The approval is the plane's own record of the person's yes for this trigger; anything in the settings is ignored.
     const approval = nightlyApprovalOf(store, input.trigger);
     if (approval === null || approval.digest !== nightlyDigestOf(input.trigger, repo, input.schedule, check))
         return { made: "skipped", note: "Skipped: the nightly check isn't approved as it stands. Set it up again." };
@@ -177,7 +128,6 @@ export function fileNightlyCheck(store, input, now) {
     const blocker = store.standingOrderBlocker(input.trigger, order.routine, now);
     if (blocker !== null)
         return { made: "skipped", note: `Skipped: the last one (${blocker.taskId}, ${blocker.state}) hasn't finished.` };
-    // Main as the plane read it from the recorded remote, recently; never a ref in the shared Git directory.
     const trusted = trustedMainOf(store, repo, now, TRUSTED_MAIN_FIRE_MS);
     if (trusted === null)
         return { made: "skipped", note: "Skipped: main hasn't been read from the project's recorded remote lately." };
@@ -192,17 +142,13 @@ export function fileNightlyCheck(store, input, now) {
     const ref = store.refFor(BUILT_IN, taskId, "ours");
     store.placeTask(ref.id, repo, {}, now);
     store.recordAction({ at: now.toISOString(), actor: "toolroll", repo, taskId, runId: null, action: "task checks chosen", outcome: "full", source: "request", detail: "Checks for this task: Full" });
-    // Fixed words, never the trigger's: what the person approved is what files.
     propose(store, { taskId, goal: NIGHTLY_GOAL, outOfScope: NIGHTLY_NOT, candidate: head.sha, acceptance: [...NIGHTLY_ACCEPTANCE], now });
     const sealed = store.sealScopeApproval(taskId, approval.by, now, {}, { kind: "schedule", modeDigest: approval.digest }, "automation");
     store.handle.prepare("INSERT INTO nightly_check (repo, sha, task, at) VALUES (?, ?, ?, ?)").run(repo, head.sha, taskId, now.toISOString());
     return sealed ? { made: "filed", taskId, approved: true, note: `Checking main at ${head.sha.slice(0, 7)}.` }
         : { made: "filed", taskId, approved: false, note: "Its approval can't stand on its own here, so this one waits for approval." };
 }
-/** Whether a task is a nightly check of main (check only: it never deploys, merges or completes). */
 export const isNightlyTask = (store, taskId) => store.handle.prepare("SELECT 1 AS hit FROM nightly_check WHERE task = ?").get(taskId) !== undefined;
-/** Every item a failed check failed: each failed identity, each failed group or version, and the whole part for a
- * part that couldn't say which items (it stopped, never reported, or crashed). No report: every part. */
 export function failedItems(report) {
     if (report === null)
         return [partIdentity("all")];
@@ -219,7 +165,6 @@ export function failedItems(report) {
     }
     return [...items].sort();
 }
-/** The words of one failure notice: "2 unit files, app/pages". */
 export function failureSummary(items) {
     const files = new Set(items.flatMap(one => /^unit:(.+?)::/.exec(one)?.[1] ?? /^file:(.+)$/.exec(one)?.[1] ?? []));
     const groups = new Set(items.flatMap(one => { const m = /^(?:group|journey):(app|flows):(?:scripted|real):([^:]+?)(?:::|$)/.exec(one); return m === null ? [] : [`${m[1]}/${m[2]}`]; }));
@@ -230,11 +175,6 @@ export function failureSummary(items) {
         ...(versions.length === 0 ? [] : [`upgrade ${versions.join(", ")}`]), ...parts.map(one => one === "all" ? "the whole check" : `the ${one} part`),
     ].join(", ") || "the check";
 }
-/**
- * Whether a full run's report shows `item` itself ran and PASSED there (security review): a failed identity has to be
- * reported passed by name — missing, skipped, or a passing part around it never clears it. A part-level item clears
- * when that whole part ran and passed.
- */
 export function coversItem(report, item) {
     const part = (name) => report.parts.find(one => one.part === name);
     const passedPart = (name) => { const one = part(name); return one !== undefined && one.ran && one.code === 0; };
@@ -262,10 +202,6 @@ export function coversItem(report, item) {
         return report.parts.filter(one => one.selected).every(one => one.ran && one.code === 0) && report.exitCode === 0;
     return whole !== undefined && passedPart(whole);
 }
-/**
- * The plane's sweep (watch's follow-up checks): settle each finished nightly (failure rows and one attention notice),
- * then let each finished full release check clear the main failures it covers. Returns how many it settled.
- */
 export function settleReleaseChecks(store, root, now) {
     let settled = 0;
     for (const row of store.handle.prepare("SELECT * FROM nightly_check WHERE outcome IS NULL AND task IS NOT NULL ORDER BY id").all()) {
@@ -300,12 +236,9 @@ export function settleReleaseChecks(store, root, now) {
             store.handle.prepare("UPDATE release_check_attempt SET settled_at = ? WHERE run = ?").run(now.toISOString(), runId);
             if (repo === null || row["mode"] !== "full" || row["head_revision"] == null)
                 return;
-            // Only a full pass with coverage full clears anything; a composed result never does.
             const gate = verificationEvidence(store, root, runId);
             if (!gate.ok || gate.bytes === null)
                 return;
-            // A SUCCESSFUL executed full check only (review round 1): its receipt says it ran and passed, its coverage is full,
-            // and its own report exited 0. A failed full check clears nothing, whatever items it reports passed.
             let receipt;
             try {
                 receipt = JSON.parse(gate.bytes);
@@ -322,15 +255,11 @@ export function settleReleaseChecks(store, root, now) {
             if (gitDir === null)
                 return;
             const head = String(row["head_revision"]);
-            // The pass has to be on main (its head an ancestor of, or main's head itself) or the exact candidate of a release
-            // whose approval stands: a pass on a side branch clears nothing (security review).
             const task = store.refById(Number(row["task_ref"]))?.externalId ?? null;
             const main = trustedMainOf(store, repo, now, TRUSTED_MAIN_CLEAR_MS);
             const onMain = main !== null && (head === main || verifiedFirstParentWalk(gitDir, main, head, 5000).ok);
             const release = task === null ? null : liveReleaseOf(store, task, "dispatch", now);
             const candidate = task === null ? null : store.getScope(task)?.candidate ?? null;
-            // The run must have checked that very candidate: its head is the candidate, or the commit a prepared build recorded
-            // for it, holding exactly the candidate's verified tree.
             const sameTree = (a, b) => { const x = readVerifiedCommit(gitDir, a), y = readVerifiedCommit(gitDir, b); return x.ok && y.ok && x.value.tree === y.value.tree; };
             const releaseTip = release !== null && release.applies && release.ok && candidate !== null && release.authority.tipSha === candidate
                 && (head === candidate || sameTree(head, candidate));
@@ -349,8 +278,6 @@ export function settleReleaseChecks(store, root, now) {
     }
     return settled;
 }
-/** The nightly's flow health: "the nightly check hasn't run since …" after 26 hours without a firing. Null when it ran
- * recently, or the project has no nightly check. */
 export function nightlyHealthWords(store, repo, configuredAt, now) {
     const last = store.handle.prepare("SELECT at FROM nightly_check WHERE repo = ? ORDER BY id DESC LIMIT 1").get(repo);
     const since = last === undefined ? configuredAt : String(last["at"]);
@@ -359,7 +286,6 @@ export function nightlyHealthWords(store, repo, configuredAt, now) {
     return last === undefined ? `the nightly check hasn't run since it was set up (${since.slice(0, 16).replace("T", " ")})` : `the nightly check hasn't run since ${since.slice(0, 16).replace("T", " ")}`;
 }
 export { fileIdentity, groupIdentity, journeyIdentity, unitIdentity, versionIdentity };
-/** The items the nightly check of main found failing that are still open: a full check reports each by name. */
 export function openMainFailureItems(store, repo) {
     return store.handle.prepare("SELECT DISTINCT item FROM main_check_failure WHERE repo = ? AND cleared_at IS NULL ORDER BY item").all(repo).map(row => String(row["item"]));
 }