Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix: run structural pregate guards before broad suites (#13259)

Adam Eivy1bbebb3af6f0
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index fd0a6201b8..24e4ac3dd0 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -91,7 +91,8 @@ Pregate first checks installed package versions against all four workspace lockf
Pregate proves only the stages it runs, and it says which it did not. A scoped
plan runs every suite CI would run for it, in CI's dependency order and with
-CI's environment: the hidden-content scan, lint, server and client tests, the
+CI's environment: the hidden-content scan, early structural guards, lint,
+server and client tests, the
client build plus the API Explorer bundle pin, the boot smoke, the
cross-workspace browser suites (smoke profile), and the serial `portos_test`
DB suite last and alone — never concurrently with the other suites, and never
@@ -120,6 +121,13 @@ that was validated — untracked and uncommitted files included, so a later
commit of that state yields the same `HEAD^{tree}`. A green summary never
claims a suite it skipped; required CI checks still apply.
+Always-run and diff-selected structural guards run before broad test stages
+and browser/database prerequisite probes. Their successful results are reused
+only within that run while the working tree, index, HEAD and refs are unchanged;
+the receipt records guard outcomes and reuse proofs. This leaves the persistent
+test memo's stricter rules intact. `--guards-only` and downgraded full plans
+run that same guard selection once.
+
Interrupting pregate (Ctrl-C or SIGTERM) does not leave tests running behind
it: the running stage — including the test runner's npm and Vitest
processes, which share that stage's process group — gets the signal and a
diff --git a/docs/GITHUB_ACTIONS.md b/docs/GITHUB_ACTIONS.md
index fd544117a8..38fa111e79 100644
--- a/docs/GITHUB_ACTIONS.md
+++ b/docs/GITHUB_ACTIONS.md
@@ -172,7 +172,8 @@ CI run that never needed it — they keep the documented skip.
`scripts/pregate.js` runs the same planner over the committed and uncommitted
diff and hands its plan to the same runners, so a scoped plan is reproduced
-locally stage for stage: hidden-content scan, lint, server and client tests,
+locally: hidden-content scan, early server and client structural guards, lint,
+server and client tests,
the client build and its API Explorer bundle pin, the boot smoke, the browser
suites (smoke profile, prerequisites required rather than skipped), and the
serial `portos_test` DB suite last and alone. Each stage receives the
@@ -187,6 +188,15 @@ shipped prompt-history guard runs locally when selected; the Windows job and
the Linux worker-containment job are the two suites only CI can prove. Details and the receipt
contract: `docs/CONTRIBUTING.md`.
+The early guards use the same always-run and diff-selected structural selection
+as CI and `--guards-only`. They run before broad tests and resource probes.
+Successful guards are reused within this invocation only when the working tree,
+index, HEAD and refs remain unchanged; otherwise the broad runner executes them
+again. The receipt records guard outcomes and reuse proofs. Persistent test
+memo rules, required stages and worker caps remain the same. Downgraded full
+plans and `--guards-only` run the guard selection once; `--full` runs it before
+the full suites.
+
The fixed `pregate:merged` package script advertises support for
`node scripts/pregate.js --guards-only --merged-with <base-sha>` to the quality
snapshot publisher. It validates the exact published head and fetched default
@@ -204,6 +214,7 @@ Repositories without
this capability retain their existing snapshot merge behavior; arbitrary scripts
are never executed as a substitute.
+
### Pregate attestation
A green pregate on this machine runs the same planner, runners, environment
diff --git a/scripts/lib/pregateReport.js b/scripts/lib/pregateReport.js
index 7cc01bcf4a..99f6ca50a6 100644
--- a/scripts/lib/pregateReport.js
+++ b/scripts/lib/pregateReport.js
@@ -12,6 +12,7 @@
* checkouts its own tests build.
*/
import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
import { copyFileSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join, resolve } from 'node:path';
@@ -51,6 +52,26 @@ export function validatedTreeHash(cwd, { env = process.env } = {}) {
}
}
+// This cache lives only for one pregate invocation. Tree scanners deliberately
+// cannot use the persistent module memo: their inputs include the index and Git
+// refs as well as every working-tree file. Any unreadable input means no reuse.
+export function guardInputSnapshot(cwd) {
+ try {
+ const digest = createHash('sha256').update(validatedTreeHash(cwd));
+ for (const args of [
+ ['rev-parse', 'HEAD'], ['ls-files', '--stage', '-z'],
+ ['status', '--porcelain=v1', '-z', '--untracked-files=all'],
+ ['for-each-ref', '--format=%(refname) %(objectname)'],
+ ]) {
+ digest.update(execFileSync('git', args, { cwd, maxBuffer: 32 * 1024 * 1024,
+ env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } }));
+ }
+ return digest.digest('hex');
+ } catch {
+ return null;
+ }
+}
+
/**
* Shape the receipt. Pure: every input is a value the gate already holds.
*
@@ -73,8 +94,10 @@ export function buildPregateReport({
finishedAt,
downgraded = false,
}) {
- const stageRecords = stages.map(({ name, suite, command, status, durationMs, exitCode = null, signal = null }) => ({
+ const stageRecords = stages.map(({ name, suite, command, status, durationMs, exitCode = null, signal = null, guard, files, guardReuse }) => ({
name, suite, command, status, durationMs, exitCode, signal,
+ ...(guard ? { guard: true, files } : {}),
+ ...(guardReuse ? { guardReuse } : {}),
}));
const passed = stageRecords.length > 0 && stageRecords.every((stage) => stage.status === 'passed');
return {
diff --git a/scripts/pregate.js b/scripts/pregate.js
index b98b5da25b..26d8c3d036 100644
--- a/scripts/pregate.js
+++ b/scripts/pregate.js
@@ -16,8 +16,8 @@
* boot smoke, the browser suites and the serial `portos_test` suite), so a
* green pregate means the Linux jobs are green for the same reasons — never
* a second, drifting opinion about which tests matter. Stages run in CI's
- * dependency order, with the DB suite last and alone: it is serial and its
- * per-case budgets assume no concurrent suite (docs/CONTRIBUTING.md).
+ * dependency order after early structural guards, with the DB suite last and
+ * alone: its per-case budgets assume no concurrent suite (docs/CONTRIBUTING.md).
*
* node scripts/pregate.js [--base <ref>] [--full] [--skip-lint] [--plan-only]
* [--skip-db] [--skip-browser] [--skip-build] [--skip-smoke]
@@ -63,7 +63,7 @@ import { assertNodeVersion } from './checkNodeVersion.js';
import { isDirectlyInvoked } from './lib/directInvocation.js';
import { needsBrowserFidelity } from './lib/browserFidelity.js';
import { cosWorkerBudget } from './lib/cosWorkerBudget.js';
-import { buildPregateReport, PREGATE_REPORT_PATH, validatedTreeHash, writePregateReport } from './lib/pregateReport.js';
+import { buildPregateReport, guardInputSnapshot, PREGATE_REPORT_PATH, validatedTreeHash, writePregateReport } from './lib/pregateReport.js';
import { dependencyConsistencyProblems } from './lib/workspaceDependencies.js';
const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -191,13 +191,13 @@ export function describeStageCommand(stage) {
* The hidden-content scan always runs first, even if lint/tests select no
* work, and the shipped prompt-history guard (CI's `prompt-history` job: one
* git-history read, seconds locally) follows it when selected. Order after
- * that follows CI's own dependency order: lint, unit tests, the client build
- * and its bundle pin, the boot smoke, the browser suites, and the DB suite
+ * that runs the shared structural guards first, then CI's dependency order:
+ * lint, unit tests, the client build and its bundle pin, the boot smoke, the browser suites, and the DB suite
* last and alone. `skip` holds the suites that stay with CI
* (see `uncoveredSuites`); `databaseEnv` is the pinned `portos_test`
* environment from scripts/lib/pregateResources.js.
*/
-export function resolvePlanStages(plan, { skipLint = false, baseSha, skip = {}, databaseEnv = {} } = {}) {
+export function resolvePlanStages(plan, { skipLint = false, baseSha, skip = {}, databaseEnv = {}, guardPlan = null } = {}) {
const base = baseSha ? { CI_BASE_SHA: baseSha } : {};
const stages = [{
name: 'hidden-content scan',
@@ -211,6 +211,21 @@ export function resolvePlanStages(plan, { skipLint = false, baseSha, skip = {},
stages.push({ name: 'shipped prompt history', suite: 'prompt-history', script: 'migrations/check-shipped-prompt-history.js', args: [], env: {} });
}
+ const scopeEnv = { server: { PORTOS_CI_BROWSER_OWNER: 'unit', PORTOS_TEST_QUIET: '1' }, client: {} };
+ if (guardPlan) {
+ for (const scope of ['server', 'client']) {
+ const selected = plan[scope];
+ const files = selected.mode === 'skip' ? [] : guardPlan[scope].files
+ .filter(file => selected.mode === 'full' || selected.files.includes(file));
+ if (files.length === 0) continue;
+ stages.push({
+ name: `${scope} structural guards`, suite: scope, guard: true, files,
+ script: 'run-ci-tests.js', args: [scope],
+ env: { ...scopeEnv[scope], ...base, CI_TEST_MODE: 'files', CI_TEST_FILES: JSON.stringify(files), CI_TEST_SOURCES: '[]', PORTOS_PREGATE_GUARDS: '' },
+ });
+ }
+ }
+
if (!skipLint && plan.lint.mode !== 'skip') {
stages.push({
name: 'client/server lint',
@@ -223,7 +238,6 @@ export function resolvePlanStages(plan, { skipLint = false, baseSha, skip = {},
// Same env the Linux unit jobs set: the registered browser suites belong to
// the browser stage below, and passing output stays signal-dense.
- const scopeEnv = { server: { PORTOS_CI_BROWSER_OWNER: 'unit', PORTOS_TEST_QUIET: '1' }, client: {} };
['server', 'client'].forEach((scope) => {
const scoped = plan[scope];
if (scoped.mode === 'skip') return;
@@ -237,6 +251,7 @@ export function resolvePlanStages(plan, { skipLint = false, baseSha, skip = {},
CI_TEST_MODE: scoped.mode,
CI_TEST_FILES: JSON.stringify(scoped.files),
CI_TEST_SOURCES: JSON.stringify(scoped.sources),
+ PORTOS_PREGATE_GUARDS: '',
// Same base the planner just used. The import-growth guard fails
// closed without it; omitting it here would make pregate compare
// against a different ref than CI.
@@ -323,6 +338,7 @@ export function downgradeFullPlan(plan, trackedFiles, changedFiles = []) {
const git = (args) => execFileSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8' }).trim();
+
const gitPaths = (args, cwd = REPO_ROOT) => execFileSync('git', args, { cwd, encoding: 'utf8' })
.split('\0')
.filter(Boolean);
@@ -742,23 +758,24 @@ async function main() {
console.log(`📋 ${raw.changed_files.length} changed file(s) — ${plan.reason}.`);
const downgraded = plan.full && !options.full && !options.guardsOnly;
+ const guardPlan = downgradeFullPlan(plan, git(['ls-files', '-z']).split('\0').filter(Boolean), changedFiles);
if (options.guardsOnly) {
- plan = downgradeFullPlan(plan, git(['ls-files', '-z']).split('\0').filter(Boolean), changedFiles);
+ plan = guardPlan;
Object.assign(plan, { lint: { mode: 'skip', files: [] }, browser: { files: [] }, db: false, windows: false, build: false, smoke: false, promptHistory: false, linuxContainment: false, supercolliderLive: false, dockerContainmentLive: false });
}
if (downgraded) {
- plan = downgradeFullPlan(plan, git(['ls-files']).split('\n').filter(Boolean), changedFiles);
+ plan = guardPlan;
console.log('⚠️ CI will run the FULL suite for this diff — running always-run and diff-selected structural guards only. Pass --full to run everything, including the build, smoke, browser and DB suites.');
}
- describeBrowserSelection(plan.browser.files).forEach((line) => console.log(line));
+ describeBrowserSelection(plan.browser.files).forEach((line) => { console.log(line); });
/** Stages for the suites that stay here, after the uncovered ones are announced. */
const planStages = (prerequisites, databaseEnv) => {
const uncovered = uncoveredSuites(plan, { options, downgraded, prerequisites });
- announceUncovered(uncovered);
const skip = Object.fromEntries(uncovered.map(({ suite }) => [suite, true]));
- const stages = resolvePlanStages(plan, { skipLint: options.skipLint, baseSha, skip, databaseEnv });
+ const stages = resolvePlanStages(plan, { skipLint: options.skipLint, baseSha, skip, databaseEnv,
+ guardPlan: options.guardsOnly || downgraded ? null : guardPlan });
return { uncovered, stages: options.guardsOnly
? stages.filter(stage => stage.suite === 'server' || stage.suite === 'client')
.map(stage => ({ ...stage, env: { ...stage.env, PORTOS_TEST_MEMO: 'off' } }))
@@ -767,7 +784,9 @@ async function main() {
if (options.planOnly) {
// Prerequisites are probed at run time; here every selected suite is a stage.
- planStages({}, {}).stages.forEach((stage) => {
+ const { uncovered, stages } = planStages({}, {});
+ announceUncovered(uncovered);
+ stages.forEach((stage) => {
console.log(`• ${stage.name}: ${describeStageCommand(stage)}`);
});
process.exit(0);
@@ -801,8 +820,7 @@ async function main() {
}
console.log('✅ Dependency consistency preflight passed (installed package versions match workspace locks).');
- const { prerequisites, databaseEnv } = await probeResourceSuites(plan, { options, downgraded });
- const { uncovered, stages } = planStages(prerequisites, databaseEnv);
+ let { uncovered, stages } = planStages({}, {});
const headSha = git(['rev-parse', 'HEAD']);
// The receipt hashes the tree the stages validate. It is taken once the
@@ -817,12 +835,27 @@ async function main() {
};
const startedAt = new Date().toISOString();
- const results = stages.map((stage) => ({ ...stage, command: describeStageCommand(stage), status: 'not-run', durationMs: 0 }));
+ const stageResult = (stage) => ({ ...stage, command: describeStageCommand(stage), status: 'not-run', durationMs: 0 });
+ const results = stages.map(stageResult);
let exitCode = 0;
let failure = null;
const owner = installOwnerCancellation();
- for (const result of results) {
+ const passedGuards = new Map();
+ let probed = false;
+ for (let index = 0; index < results.length; index += 1) {
if (failure || owner.signal) break;
+ let result = results[index];
+ // Even prerequisite probes may start Chrome. Defer them until every early
+ // guard has passed, retaining not-run resource stages on an early failure.
+ if (!probed && !result.guard && !['scan', 'prompt-history'].includes(result.suite)) {
+ const { prerequisites, databaseEnv } = await probeResourceSuites(plan, { options, downgraded });
+ ({ uncovered, stages } = planStages(prerequisites, databaseEnv));
+ announceUncovered(uncovered);
+ results.splice(index, results.length - index, ...stages.slice(index).map(stageResult));
+ probed = true;
+ result = results[index];
+ if (!result || owner.signal) break;
+ }
if (result.suite !== 'scan') {
try {
hashTree();
@@ -832,6 +865,12 @@ async function main() {
break;
}
}
+ const beforeGuards = result.guard ? guardInputSnapshot(REPO_ROOT) : null;
+ const passed = passedGuards.get(result.suite);
+ if (!result.guard && passed && guardInputSnapshot(REPO_ROOT) === passed.snapshot) {
+ result.guardReuse = passed;
+ result.env = { ...result.env, PORTOS_PREGATE_GUARDS: JSON.stringify(passed) };
+ }
console.log(`▶️ ${result.name}`);
const started = Date.now();
const outcome = await runStage(result, owner);
@@ -864,6 +903,9 @@ async function main() {
} else {
result.status = 'passed';
result.exitCode = 0;
+ if (beforeGuards && guardInputSnapshot(REPO_ROOT) === beforeGuards) {
+ passedGuards.set(result.suite, { snapshot: beforeGuards, files: result.files });
+ }
console.log(`✔️ ${result.name} passed in ${formatDuration(result.durationMs)}.`);
}
}
diff --git a/scripts/pregate.test.js b/scripts/pregate.test.js
index f9c10df1bb..15fbb1bc44 100644
--- a/scripts/pregate.test.js
+++ b/scripts/pregate.test.js
@@ -84,6 +84,7 @@ describe('resolvePlanStages', () => {
CI_TEST_MODE: 'related',
CI_TEST_FILES: '["server/lib/a.test.js"]',
CI_TEST_SOURCES: '["server/lib/a.js"]',
+ PORTOS_PREGATE_GUARDS: '',
});
});
@@ -120,6 +121,28 @@ describe('resolvePlanStages', () => {
);
expect(stages.map((stage) => stage.name)).toEqual(['hidden-content scan', 'server tests']);
});
+
+ it.each(['related', 'full'])('runs shared guards before every costly %s stage without changing the broad selection', (mode) => {
+ const tracked = ['server/lib/index.test.js', ALWAYS_RUN_TESTS[0], 'client/src/fooConventions.test.js'];
+ const plan = planWith({
+ server: { mode, files: tracked.slice(0, 2), sources: ['server/lib/helper.js'] },
+ client: { mode, files: tracked.slice(2), sources: [] },
+ lint: { mode: 'full', files: [] },
+ build: true, smoke: true, db: true, browser: { files: BROWSER_SUITES.slice(0, 1) },
+ });
+ const stages = resolvePlanStages(plan, { guardPlan: downgradeFullPlan(plan, tracked, ['server/lib/helper.js']) });
+ expect(stages.map(stage => stage.name)).toEqual([
+ 'hidden-content scan', 'server structural guards', 'client structural guards',
+ 'client/server lint', 'server tests', 'client tests', 'client build',
+ 'API Explorer bundle pin', 'boot smoke', 'browser suites', 'DB provision (portos_test)', 'DB suite (portos_test)',
+ ]);
+ for (const scope of ['server', 'client']) {
+ expect(stages.find(stage => stage.name === `${scope} tests`).env).toMatchObject({
+ CI_TEST_MODE: mode, CI_TEST_FILES: JSON.stringify(plan[scope].files), CI_TEST_SOURCES: JSON.stringify(plan[scope].sources),
+ });
+ }
+ expect(stages.filter(stage => stage.guard).flatMap(stage => stage.files).sort()).toEqual(tracked.sort());
+ });
});
// These regressions need the actual CLI and Git, not mocked stage dispatch:
@@ -190,6 +213,7 @@ describe('pregate hidden-content invocation', () => {
// before the test snapshots its bytes, or the CLI's ordinary Git reads
// appear to mutate the index even when they only notice the copy.
git('update-index', '--refresh');
+ base = git('rev-parse', 'HEAD');
});
afterEach(async () => {
@@ -200,6 +224,115 @@ describe('pregate hidden-content invocation', () => {
if (template?.scratch) await destroyGitSandbox(template.scratch);
});
+ function prepareGuardFixture({ browser = false } = {}) {
+ write('server/lib/index.js', 'export {};\n');
+ write('server/lib/README.md', '# Shared helpers\n');
+ // This fixture guard pins the catalog failure at the CLI boundary; the real
+ // catalog suite separately owns the complete barrel/README contract.
+ write('server/lib/index.test.js', `
+ import { appendFileSync, existsSync, readFileSync } from 'fs';
+ appendFileSync('.cache/events', 'catalog\\n');
+ if (existsSync('server/lib/helper.js') &&
+ (!readFileSync('server/lib/index.js', 'utf8').includes('helper') ||
+ !readFileSync('server/lib/README.md', 'utf8').includes('helper'))) {
+ throw new Error('Missing helper barrel/catalog registration');
+ }
+ `);
+ write('server/lib/expensive.test.js', 'export {};\n');
+ write('scripts/run-ci-tests.js', `
+ import { appendFileSync } from 'fs';
+ import { resolve } from 'path';
+ import { pathToFileURL } from 'url';
+ const files = JSON.parse(process.env.CI_TEST_FILES);
+ const excluded = JSON.parse(process.env.PORTOS_PREGATE_GUARDS || '{}').files || [];
+ const broad = process.env.CI_TEST_MODE !== 'files' || files.includes('server/lib/expensive.test.js');
+ appendFileSync('.cache/events', JSON.stringify({ broad, excluded }) + '\\n');
+ if (files.includes('server/lib/index.test.js') && !excluded.includes('server/lib/index.test.js')) {
+ await import(pathToFileURL(resolve('server/lib/index.test.js')));
+ }
+ `);
+ write('scripts/run-ci-lint.js', `
+ import { appendFileSync, existsSync, writeFileSync } from 'fs';
+ appendFileSync('.cache/events', 'lint\\n');
+ if (existsSync('.cache/mutate')) writeFileSync('server/lib/helper.js', 'export const helper = 2;\\n');
+ `);
+ write('scripts/smoke-boot.js', `
+ import { appendFileSync } from 'fs';
+ appendFileSync('.cache/events', 'smoke\\n');
+ `);
+ if (browser) {
+ write(BROWSER_SUITES[0], 'export {};\n');
+ write('scripts/lib/pregateResources.js', `
+ import { writeFileSync } from 'fs';
+ writeFileSync('.cache/probe-started', 'unexpected probe');
+ throw new Error('Resource probe ran before structural refusal');
+ `);
+ }
+ git('add', '--all');
+ git('commit', '-qm', 'structural gate fixture');
+ base = git('rev-parse', 'HEAD');
+ mkdirSync(join(root, '.cache'), { recursive: true });
+ write('.cache/events', '');
+ write('server/lib/helper.js', 'export const helper = 1;\n');
+ if (browser) write(BROWSER_SUITES[0], 'export const changed = true;\n');
+ }
+
+ it('prints the selected guard, broad and browser stages without starting any process', () => {
+ prepareGuardFixture({ browser: true });
+ const result = run('--plan-only');
+ expect(result.status, result.stderr).toBe(0);
+ expect(result.stdout).toContain('Planning against');
+ expect(result.stdout).toContain('changed file');
+ expect(result.stdout).toContain('server structural guards');
+ expect(result.stdout).toContain('server tests');
+ expect(result.stdout).toContain('Browser suites: 1 selected');
+ expect(readFileSync(join(root, '.cache/events'), 'utf8')).toBe('');
+ expect(existsSync(join(root, '.cache/probe-started'))).toBe(false);
+ expect(existsSync(join(root, PREGATE_REPORT_PATH))).toBe(false);
+ });
+
+ // A structural refusal must precede both related-test dispatch and Chrome's
+ // prerequisite probe, with the unfinished broad stages preserved in the receipt.
+ it('refuses a missing helper catalog registration before broad tests or browser probes start', () => {
+ prepareGuardFixture({ browser: true });
+ const result = run('--skip-lint');
+ expect(result.status).not.toBe(0);
+ expect(result.stderr).toContain('Missing helper barrel/catalog registration');
+ const events = readFileSync(join(root, '.cache/events'), 'utf8');
+ expect(events).not.toContain('"broad":true');
+ expect(existsSync(join(root, '.cache/probe-started'))).toBe(false);
+ const report = JSON.parse(readFileSync(join(root, PREGATE_REPORT_PATH), 'utf8'));
+ expect(report.passed).toBe(false);
+ expect(report.stages.find(stage => stage.guard)).toMatchObject({ status: 'failed', files: ['server/lib/index.test.js'] });
+ expect(report.stages.filter(stage => ['server tests', 'browser suites'].includes(stage.name)))
+ .toEqual(expect.arrayContaining([
+ expect.objectContaining({ name: 'server tests', status: 'not-run' }),
+ expect.objectContaining({ name: 'browser suites', status: 'not-run' }),
+ ]));
+ });
+
+ // Unlike the persistent module memo, this reuse includes tree scanners. A
+ // modification between stages invalidates it even when the test file is stable.
+ it.each([false, true])('rechecks guard inputs before broad dispatch (changed: %s)', (changed) => {
+ prepareGuardFixture();
+ write('server/lib/index.js', "export { helper } from './helper.js';\n");
+ write('server/lib/README.md', '# Shared helpers\nhelper\n');
+ if (changed) write('.cache/mutate', 'mutate during lint');
+ const result = run();
+ expect(result.status, result.stderr).toBe(0);
+ const events = readFileSync(join(root, '.cache/events'), 'utf8').trim().split('\n');
+ expect(events.filter(event => event === 'catalog')).toHaveLength(changed ? 2 : 1);
+ expect(events.indexOf('catalog')).toBeLessThan(events.indexOf('lint'));
+ expect(events.at(-1)).toBe('smoke');
+ const broad = events.filter(event => event.startsWith('{')).map(event => JSON.parse(event)).find(event => event.broad);
+ expect(broad.excluded).toEqual(changed ? [] : ['server/lib/index.test.js']);
+ const report = JSON.parse(readFileSync(join(root, PREGATE_REPORT_PATH), 'utf8'));
+ expect(report.stages.every(stage => stage.status === 'passed')).toBe(true);
+ expect(report.treeStable).toBe(!changed);
+ expect(report.stages.find(stage => stage.name === 'server tests').guardReuse?.files)
+ .toEqual(changed ? undefined : ['server/lib/index.test.js']);
+ });
+
// A branch and base can each be green while their combined route inventory fails.
it('runs guards on the exact merged tree, propagates failure, and preserves caller state and receipt', () => {
git('config', 'core.autocrlf', 'true');
@@ -856,25 +989,6 @@ describe('the gate end to end', () => {
}
});
- // `--base HEAD` rather than the default remote branch: CI clones at depth 2
- // with no `origin/main` ref, so the default would abort here on a fetch the
- // gate is right to demand of a human and wrong to demand of this test. HEAD
- // is its own merge base in any checkout, and the run still exercises every
- // stage — argument parsing, merge-base resolution, spawning the real planner,
- // mapping its plan to stages — on an empty diff.
- it('plans this checkout and names its stages without running them', () => {
- const output = execFileSync(
- process.execPath,
- [join(REPO_ROOT, 'scripts', 'pregate.js'), '--plan-only', '--base', 'HEAD'],
- { cwd: REPO_ROOT, encoding: 'utf8' },
- );
- expect(output).toMatch(/Planning against HEAD/);
- expect(output).toMatch(/changed file/);
- // An empty diff still selects the always-run guards, so the gate must name
- // real work rather than reporting there is nothing to do.
- expect(output).toMatch(/server tests/);
- });
-
it('refuses a base this checkout cannot resolve instead of planning against nothing', () => {
const run = () => execFileSync(
process.execPath,
@@ -958,12 +1072,7 @@ describe('describeBrowserSelection', () => {
.not.toContain('Fidelity cases');
});
- it('shows the selection in --plan-only output', () => {
- const out = execFileSync(process.execPath, [join(REPO_ROOT, 'scripts', 'pregate.js'), '--plan-only', '--skip-lint', '--base', 'HEAD'], {
- cwd: REPO_ROOT, encoding: 'utf8',
- });
- expect(out).toContain('Browser suites:');
- });
+
});
describe('resource suite stages', () => {
diff --git a/scripts/run-ci-tests.js b/scripts/run-ci-tests.js
index cfca7e83c9..42c88d1e05 100644
--- a/scripts/run-ci-tests.js
+++ b/scripts/run-ci-tests.js
@@ -18,6 +18,7 @@ import {
memoSummaryLine, passedTestFiles, planTestMemo, readVitestDependencies, recordTestMemo, writeSelectionFile,
} from './lib/testMemoRunner.js';
import { resolveMemoDir } from './lib/testMemoStore.js';
+import { guardInputSnapshot } from './lib/pregateReport.js';
import { TEST_SCOPES, workspaceOf } from './lib/workspaceTests.js';
const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -427,6 +428,9 @@ async function main() {
const workspace = workspaceOf(scope);
const { script } = TEST_SCOPES[scope];
+ const guardProof = JSON.parse(process.env.PORTOS_PREGATE_GUARDS || 'null');
+ // A proof is for this runner only, never a nested invocation from its tests.
+ delete process.env.PORTOS_PREGATE_GUARDS;
const mode = process.env.CI_TEST_MODE || 'full';
const inputFiles = JSON.parse(process.env.CI_TEST_FILES || '[]');
const repoFiles = process.env.PORTOS_BROWSER_TEST_PROFILE !== undefined
@@ -463,7 +467,7 @@ async function main() {
// finish flushing. Setting exitCode lets Node drain normally once main()
// returns.
const memoDir = resolveMemoDir();
- if (mode === 'full' && !memoDir && !shard) {
+ if (mode === 'full' && !memoDir && !shard && !guardProof) {
process.exitCode = await spawnNpm(workspace, script, [], label, { name: scope });
return;
}
@@ -483,6 +487,15 @@ async function main() {
for (const { test, via } of plan.skipped) console.log(`🧠 skipped ${test} (${via} key)`);
}
}
+ // Pregate supplies only guards that passed earlier in this invocation, after
+ // rechecking their repository snapshot. Keep normal memo selection/sharding.
+ const excluded = new Set(guardProof && Array.isArray(guardProof.files)
+ && guardProof.files.every(file => typeof file === 'string')
+ && typeof guardProof.snapshot === 'string' && guardInputSnapshot(repoRoot) === guardProof.snapshot
+ ? guardProof.files : []);
+ const reused = plan.run.filter(test => excluded.has(test));
+ plan.run = plan.run.filter(test => !excluded.has(test));
+ if (reused.length > 0) console.log(`♻️ Reused ${reused.length} structural guards from this pregate run (inputs unchanged).`);
if (plan.run.length === 0) {
console.log(`No ${scope} tests left to run${shard ? ' in this shard' : ''}.`);
process.exitCode = 0;
diff --git a/scripts/run-ci-tests.test.js b/scripts/run-ci-tests.test.js
index 11847d9df7..c85fa1fa4a 100644
--- a/scripts/run-ci-tests.test.js
+++ b/scripts/run-ci-tests.test.js
@@ -24,6 +24,7 @@ import * as nodeFs from 'node:fs';
import * as nodePath from 'node:path';
import { computeTestMemoKeys, createDiskFs, relatedTests } from './lib/testMemo.js';
import { vitestShardSlice } from './lib/testMemoRunner.js';
+import { guardInputSnapshot } from './lib/pregateReport.js';
import { toWorkspacePath } from './lib/workspaceTests.js';
import { OWNER_FILE, STALE_ROOT_AGE_MS } from './lib/vitestStaleRunRoots.js';
import { workflowJobs } from './lib/workflowJobs.js';
@@ -221,6 +222,31 @@ describe('test memo through the real runner', () => {
}, 120_000);
});
+it.each(['files', 'full'])('validates the guard proof before the actual %s Vitest selection with the persistent memo off', (mode) => {
+ const fixture = mkdtempSync(join(tmpdir(), 'portos-early-guards-'));
+ try {
+ installFakeNpm(fixture, 'if (process.env.PORTOS_PREGATE_GUARDS) throw new Error("Guard proof leaked to test process");\n' + REPORTING_NPM);
+ const guard = 'server/lib/index.test.js';
+ const result = spawnSync(process.execPath, [join(import.meta.dirname, 'run-ci-tests.js'), 'server'], {
+ encoding: 'utf8', timeout: 120000,
+ env: { ...process.env, PATH: `${fixture}${delimiter}${process.env.PATH}`, CI_SHARD: '',
+ CI_TEST_MODE: mode, CI_TEST_FILES: JSON.stringify([guard, 'scripts/example.test.js']),
+ CI_TEST_SOURCES: '["scripts/lib/directInvocation.js"]',
+ PORTOS_PREGATE_GUARDS: JSON.stringify({ files: [guard], snapshot: mode === 'files' ? guardInputSnapshot(join(import.meta.dirname, '..')) : 'stale' }),
+ PORTOS_TEST_MEMO: 'off', GITHUB_ENV: '', GITHUB_STEP_SUMMARY: '' },
+ });
+ expect(result.status, result.stderr).toBe(0);
+ if (mode === 'files') expect(result.stdout).toContain('Reused 1 structural guards');
+ else expect(result.stdout).not.toContain('Reused');
+ const { selection } = JSON.parse(result.stdout.split('\n').find(line => line.startsWith('{"args"')));
+ if (mode === 'files') expect(selection.include).not.toContain('lib/index.test.js');
+ else expect(selection.include).toContain('lib/index.test.js');
+ expect(selection.include).toContain('../scripts/example.test.js');
+ } finally {
+ rmSync(fixture, { recursive: true, force: true });
+ }
+});
+
it('rejects empty browser coverage except explicitly deferred smoke-only inputs', () => {
for (const [profile, files, expected] of [
['fidelity', [], 1], ['fidelity', ['server/lib/filmLook.browser.test.js'], 1],