diff --git a/bin/gstack-pregate b/bin/gstack-pregate index 1dd04f857..90a21a52b 100755 --- a/bin/gstack-pregate +++ b/bin/gstack-pregate @@ -32,6 +32,7 @@ import { describeDraft, draftConfig } from '../lib/pregate/init-draft'; import { buildContext, defaultUserConfigPath, describeRefusal, loadedDotenvFiles } from '../lib/pregate/context'; import { CHECKS, CHECK_IDS, PREGATE_OUT_REL, PREGATE_TIER2, clearDecision, clearObligation, readPregateFile, renderTable, runPregate, verifyPregate, writePregateFile, type RunCheck } from '../lib/pregate/index'; import { ghRunDeps } from '../lib/run-evidence'; +import { wtreeFingerprint } from '../lib/script-invocation'; import { describeLane, discoverLanes } from '../lib/pregate/workflows'; import { REMOTE_GATE_LANE } from '../lib/pregate/checks/lanes'; import { describeSubstitution } from '../lib/pregate/remote-receipt'; @@ -223,7 +224,7 @@ function cmdClear(root: string, rest: string[]): number { const runUrl = flag(rest, '--run-url'); const bundleLane = flag(rest, '--bundle-lane'); const checked = runs.length || runUrl || bundleLane ? runCheck(root, lane, rest.includes('--allow-repo-commands')) : undefined; - if (checked && 'error' in checked && (runs.length || checked.profiled)) { process.stderr.write(`gstack-pregate clear: ${checked.error}${checked.profiled ? `; the base branch declares a run profile for ${lane}, so it clears only with --run` : ''}\n`); return EXIT.fail; } + if (checked && 'error' in checked && (runs.length || checked.profiled)) { process.stderr.write(`gstack-pregate clear: ${checked.error}${checked.profiled ? `; ${lane} may have a run profile on the base branch, so it clears only with a verified --run` : ''}\n`); return EXIT.fail; } const evidence = checked && !('error' in checked) ? checked : undefined; const decision = clearDecision(read.file, lane, { runUrl, runs, bundleLane, receiptPath: flag(rest, '--receipt'), evidence }, root); if ('refused' in decision) { @@ -244,16 +245,20 @@ function cmdClear(root: string, rest: string[]): number { function runCheck(root: string, lane: string, allowRepoCommands: boolean): RunCheck | { error: string; profiled?: boolean } { const base = resolveBaseBranch(root); const loaded = loadConfigFromBase(root, base); - if (isConfigUnavailable(loaded)) return { error: `the base branch's ${PREGATE_CONFIG_PATH} is unreadable (${loaded.detail}); run profiles come only from the base` }; - if (loaded.errors.length) return { error: `the base branch's ${PREGATE_CONFIG_PATH} is invalid: ${loaded.errors.map(e => `${e.path}: ${e.message}`).join('; ')}` }; + // Unknown profiles are treated as present: a lane is cleared unverified only once the base shows it has no profile. + if (isConfigUnavailable(loaded)) return { error: `the base branch's ${PREGATE_CONFIG_PATH} is unreadable (${loaded.detail}); run profiles come only from the base`, profiled: true }; + if (loaded.errors.length) return { error: `the base branch's ${PREGATE_CONFIG_PATH} is invalid: ${loaded.errors.map(e => `${e.path}: ${e.message}`).join('; ')}`, profiled: true }; const repo = /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/.exec(gitOut(root, ['remote', 'get-url', 'origin']) ?? '')?.[1]; if (!repo) return { error: 'origin is not a github.com repository; run evidence is read from GitHub Actions', profiled: lane === REMOTE_GATE_LANE ? !!loaded.config.remote_gate_runs : !!loaded.config.run_profiles[lane] }; return { repo, deps: ghRunDeps(repo, root), profiles: loaded.config.run_profiles, gateRuns: loaded.config.remote_gate_runs, now: new Date(), - inventory: command => { + inventory: (command, tree) => { if (!allowRepoCommands) return { error: 'the inventory command is a pin-file command; pass --allow-repo-commands' }; + const at = () => { const fp = wtreeFingerprint({ cwd: root }); return 'tree' in fp ? fp.tree : null; }; + if (at() !== tree) return { error: `the working tree is not pregate.json's tree ${tree.slice(0, 12)}; the inventory must list that tree's gate files` }; const r = spawnSync('bash', ['-c', command], { cwd: root, encoding: 'utf8', timeout: 300_000, maxBuffer: 64 * 1024 * 1024 }); if (r.status !== 0 || r.error) return { error: `${command} exited ${r.status ?? r.error}: ${(r.stderr ?? '').trim().slice(0, 200)}` }; + if (at() !== tree) return { error: `the working tree changed while ${command} ran` }; return [...new Set(r.stdout.split('\n').map(l => l.trim()).filter(Boolean))]; }, }; diff --git a/docs/pregate.md b/docs/pregate.md index 8df0fbc7a..861f88399 100644 --- a/docs/pregate.md +++ b/docs/pregate.md @@ -607,54 +607,70 @@ run executed), `tests` (the count) and, with `os`, the runner OS. **What `clear --run` checks** (`lib/run-evidence.ts`), for every run, online, once: -- The run belongs to this repository and ran for a same-repository head. - Its workflow file and event are the profile's, and it completed with success. - The API answers with the newest attempt, so an earlier green attempt under a - newer red one is refused. +- The run belongs to this repository and ran for a same-repository head. Its + workflow file is the profile's, its event is `push` or `workflow_dispatch` + (a `pull_request` run tests the merge commit, not the head tree, so no + profile may accept it), and it completed with success. The API answers with + the newest attempt, so an earlier green attempt under a newer red one is + refused, and the run is read again after the evidence is collected: a new + attempt meanwhile is `run_changed`. - Every job the profile names appears exactly once in that attempt and - succeeded. -- `tree.json` names this run, attempt, event and head. It is not a reuse + succeeded. Jobs and runs are read across every page. +- `tree.json` (an artifact of at most 8 MiB) names this run, attempt, event and + head (`sha` and `head_sha`, each checked when present). It is not a reuse record (a reuse is never evidence). Its tree equals the tree git computes for - the run's head commit. + the run's head commit. `files` is a list of paths and `tests` a + non-negative integer when present; without `tests` the file count stands in. - No run of the same workflow on that head, or on pregate.json's own head, whose newest attempt started after this run was created failed, was cancelled or is still running (`run_started_at`, so a red re-run of an older run counts, and re-running this run does not hide a failure in between). -- Its event is `push` or `workflow_dispatch`. A `pull_request` run tests the - merge commit, not the head tree, so no profile may accept it. - The run finished within `max_age_hours`, and on the profile's OS when it names one. -- For `pregate.json/remote_gate`: there is exactly one verified run per - `remote_gate_runs` profile, all on one tree. Every file the `inventory` - command prints for this tree appears in some run's `files`. The command is a - pin-file command, so it runs only with `--allow-repo-commands`, and an empty - or failing inventory refuses. -- The run tree is pregate.json's tree, or a stamp-only predecessor of it under - exactly the rule [above](#remote-gate-stamp-only) (a policy whose + +Then, for the lane: + +- pregate.json was recorded against this repository's base, whose profiles + apply (`base_mismatch` otherwise). +- Each profile gets its own run (a run id given twice is a usage error), and + every run verifies under its profile. The assignment is searched, so a run + valid for two profiles cannot starve the other. A lane with a profile needs + one run; `pregate.json/remote_gate` needs one per `remote_gate_runs` + profile. +- All runs tested one tree: pregate.json's tree, or a stamp-only predecessor of + it under exactly the rule [above](#remote-gate-stamp-only) (a policy whose `stamp_sensitive_gates` names `tests` refuses that substitution). +- Every run executed something (`no_tests` names one that did not), and the + runs' `files` together cover the obligation's selected test files, plus, for + the remote gate, every file the `inventory` command prints. The inventory is + a pin-file command, so it runs only with `--allow-repo-commands`, and only + while the working tree is pregate.json's tree (checked before and after it + runs); an empty or failing inventory refuses. Any API or git error refuses. Each refusal prints `REUSE: refused reason= — …` as `PREGATE_RECEIPT_INVALID`, and a run that fails verification is named with its own reason (`fork_run`, `event_mismatch`, `run_not_success`, `job_missing`, `artifact_mismatch`, `artifact_reused`, -`tree_mismatch`, `newer_run_vetoes`, `run_stale`, `os_mismatch`, `api_error`, -…); the clear-level codes are `no_verified_run`, `tree_mismatch` (runs on -different trees), `tree_not_stamp_only`, `inventory_failed`, `inventory_empty`, -`inventory_uncovered` and `no_tests`. A wrong run count or a lane with no -profile is a usage error (exit 2), not a REUSE refusal. When the base config or -the GitHub origin cannot be read, `--run` fails, and so do `--run-url` and -`--bundle-lane` for a lane the base profiles; any other lane is recorded as -before, with a warning naming the cause. Accepted, `clear` prints `REUSE: accepted `, and -the receipt reads -`remote-gate tree= tests= runs=/,… profiles=

,… +`tree_mismatch`, `newer_run_vetoes`, `run_changed`, `run_stale`, +`os_mismatch`, `api_error`, …); the clear-level codes are `base_mismatch`, +`no_verified_run`, `tree_mismatch` (runs on different trees), +`tree_not_stamp_only`, `no_tests`, `inventory_failed`, `inventory_empty` and +`inventory_uncovered`. A wrong run count, a repeated run or a lane with no +profile is a usage error (exit 2), not a REUSE refusal. + +Accepted, `clear` prints `REUSE: accepted `, and the receipt +reads `remote-gate tree= tests= runs=/,… profiles=

,… heads= verified=