Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 15 additions & 5 deletions docs/mutation-cache.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,7 @@ exact lockfile with `npm ci --ignore-scripts`; we do not recursively hash
`node_modules`.

The only noninputs are named root documentation files, Markdown under `docs/`,
the prose files `fuzz/README.md` and `scripts/schemas/cyclonedx-1.5/README.md`,
governance files, the four named runtime
architecture scanner/test scripts and `tests/runtime-architecture/` fixtures,
the Copilot instructions, and the parent `ci.yml`. These SAST-only files are not
Expand Down Expand Up @@ -169,8 +170,10 @@ parser or artifact authentication client is maintained.

Admission diagnostics distinguish `native-baseline-missing`,
`native-baseline-incompatible`, `native-baseline-corrupt-or-unauditable`, and
`native-baseline-unreadable`. All four mean no admitted report and require fresh
full execution through the applicable route; none bypasses the gate. A compatible
`native-baseline-unreadable`. A rejected own-PR envelope can still fall back to
the already downloaded authenticated main baseline. If neither report is admitted,
fresh full execution is required through the applicable route; no rejection
bypasses the gate. A compatible
report is logged as `native-same-input-reuse`. Explicit full mode, an unavailable
input fingerprint, or a supplied `NODE_OPTIONS` is logged as `native-full-required`.

Expand All @@ -184,6 +187,12 @@ used. Admission requires a successful restore with an exact cache hit, matching
`prIdentity` and input key, and the existing report audit. The ordinary suite and
native discovery/coverage still run; changed declared inputs still run full.

The own-PR report is preferred when admitted. If it fails admission, the runner
tries the already downloaded main envelope through the same key, source identity
and current-policy audit before selecting a cold route. A missing or invalid
authenticated main SHA cannot authorize this fallback. `audit.json` records the
source actually admitted: the main commit or the own-PR identity.

This is an **own-PR optimization, not authenticated producer provenance**.
`prIdentity`/`audit.execution.baselinePR` name its scope; they are not a producing
commit or a successful whole-CI attestation. A selected main artifact's SHA is
Expand All @@ -199,9 +208,10 @@ With hosted routing enabled, an own-PR cache can be saved after a successful nat
run that admitted a compatible baseline; the matrix does not seed it.

Restore/save failures, eviction, partial/corrupt files or incompatible reports
fall back to full execution. Native caches are immutable: an unusable exact-key
entry cannot be repaired in place and may remain cold until eviction or a
reviewed key-namespace change. No cache failure skips tests or weakens the gate.
require full execution only when no compatible baseline is admitted. Native
caches are immutable: an unusable exact-key entry cannot be repaired in place,
but it does not prevent reuse of an authenticated compatible main baseline.
No cache failure skips tests or weakens the gate.
See GitHub's [cache-scope restrictions](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching#restrictions-for-accessing-a-cache).

The new envelope is not compatible with the old schema3 cache. The first hosted
Expand Down
2 changes: 2 additions & 0 deletions scripts/mutation-cache-inputs.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ export function isMutationInput(path) {
path === 'node_modules' ||
passive.test(path) ||
/^docs\/.*\.md$/.test(path) ||
path === 'fuzz/README.md' ||
path === 'scripts/schemas/cyclonedx-1.5/README.md' ||
path.startsWith('governance/') ||
path.startsWith('tests/runtime-architecture/') ||
architectureOnly.has(path) ||
Expand Down
23 changes: 15 additions & 8 deletions scripts/mutation-cache.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,13 @@ function selectRunnerPolicy(source) {
ts.isCallExpression(statement.expression.expression) &&
statement.expression.expression.expression.getText(parsed);
const guards = statements.filter(ts.isIfStatement);
const callsReadCache = (node) =>
(ts.isCallExpression(node) && node.expression.getText(parsed) === 'readCache') ||
ts.forEachChild(node, callsReadCache);
const fallback = guards.filter(callsReadCache);
assert.equal(fallback.length, 1, 'Expected one main-baseline fallback guard');
assert.ok(admission.at(-1).end < fallback[0].end);
admission.push(fallback[0]);
const promotion = guards.filter(
(statement) => callName(statement.thenStatement) === 'promoteCache',
);
Expand Down Expand Up @@ -409,13 +416,13 @@ test('the runner admission policy fragment distinguishes full mode, PR hits and
MUTATION_PR_CACHE_RESTORED: 'true',
};
for (const [delta, args, expected] of [
[{}, [], 'pr:42:7'],
[{ MUTATION_PR_CACHE_RESTORED: 'false' }, [], commit],
[{ MUTATION_PR_CACHE_RESTORED: '' }, [], commit],
[{ GITHUB_EVENT_NAME: 'push' }, [], commit],
[{ GITHUB_EVENT_NAME: 'pull_request_target' }, [], commit],
[{ GITHUB_REF: 'refs/heads/release' }, [], commit],
[{}, ['--full'], null],
[{}, [], ['pr:42:7', commit]],
[{ MUTATION_PR_CACHE_RESTORED: 'false' }, [], [commit]],
[{ MUTATION_PR_CACHE_RESTORED: '' }, [], [commit]],
[{ GITHUB_EVENT_NAME: 'push' }, [], [commit]],
[{ GITHUB_EVENT_NAME: 'pull_request_target' }, [], [commit]],
[{ GITHUB_REF: 'refs/heads/release' }, [], [commit]],
[{}, ['--full'], []],
]) {
const calls = [];
await runInNewContext(
Expand All @@ -437,7 +444,7 @@ test('the runner admission policy fragment distinguishes full mode, PR hits and
);
assert.deepEqual(
calls.map((values) => values[2]),
expected ? [expected] : [],
expected,
);
}
});
Expand Down
43 changes: 43 additions & 0 deletions scripts/mutation-editorial-inputs.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
import assert from 'node:assert/strict';
import { execFileSync } from 'node:child_process';
import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { fingerprint, mutationInputs } from './mutation-cache-inputs.mjs';

test('only the two proven editorial paths preserve the mutation input key', async (t) => {
const root = await mkdtemp(join(tmpdir(), 'mutation-editorial-'));
t.after(() => rm(root, { recursive: true, force: true }));
execFileSync('git', ['init', '-q', root]);
const cases = [
['fuzz/README.md', true],
['scripts/schemas/cyclonedx-1.5/README.md', true],
['fuzz/seeds/raw/example.bin', false],
['fuzz/regressions/raw/example.bin', false],
['scripts/schemas/cyclonedx-1.5/bom-1.5.schema.json', false],
['scripts/schemas/cyclonedx-1.5/spdx.schema.json', false],
['scripts/schemas/cyclonedx-1.5/jsf-0.82.schema.json', false],
['fuzz/NOTES.md', false],
['scripts/schemas/cyclonedx-1.5/NOTES.md', false],
['src/README.md', false],
];
for (const [path] of cases) {
await mkdir(dirname(join(root, path)), { recursive: true });
await writeFile(join(root, path), 'initial');
}
const capture = async () => fingerprint(await mutationInputs(root, {}, {}));
const before = await capture();
for (const [path, editorial] of cases) {
await t.test(path, async () => {
await writeFile(join(root, path), 'changed');
try {
const after = await capture();
if (editorial) assert.equal(after, before);
else assert.notEqual(after, before);
} finally {
await writeFile(join(root, path), 'initial');
}
});
}
});
Loading
Loading