Turborepo Release Caching Grill Log

Context

The public stable and beta release commands enter Turbo.
The CLI publisher then runs build, release tests, and typecheck outside the Turbo task graph.
npm publication, npm dist-tag changes, Git tag changes, and GitHub release changes are external mutations and must remain uncached.
The current release retry skips deterministic verification when the npm version already exists.
The current release-test schedule runs four update shards in parallel, then runs the ordinary CLI suite.

Branch: Retry Routing

Q1

Prerequisites:

none

Question: What must an existing-version release retry do before reconciliation?

Accepted answer:

Preserve the current fast retry path.
When the version already exists in npm, skip deterministic verification and run external-state reconciliation.
For a new version, run deterministic verification and then query npm again immediately before publication.

Branch: Verification Cache Boundary

Q2

Prerequisites:

none

Question: Which deterministic tasks may use Turbo cache in the first delivery?

Accepted answer:

Aim to cache the full release-test suite except tests whose result still depends on unmodeled filesystem or other ambient state.
Keep the exception set uncached until those tests become isolated and deterministic.
Cache eligibility is assigned to a Turbo task. Tests with different cache policies must run in different tasks.

Branch: Release-Test Schedule

Q3

Prerequisites:

none

Question: Must release tests keep the current two-wave schedule?

Accepted answer:

Yes.
Run the four update shards in parallel, then run the ordinary CLI suite.
Typecheck may run in parallel with the test chain.

Branch: Test Assignment Policy

Q5

Prerequisites:

Question: How should cacheable and uncached tests be separated?

Accepted answer:

Every test file must belong to exactly one cacheable or uncached test task.
A new test file starts uncached until it is explicitly classified as cacheable.
A suite-coverage contract must reject missing and duplicate assignments.

Branch: Recovery Completeness

Q4

Prerequisites:

Question: Which external release state must reconciliation complete?

Accepted answer:

Reconciliation must complete all required npm dist-tags, the Git tag, and the GitHub release.
Reconciliation must not publish the same npm package version again.

Branch: Remote Cache Trust

Q7

Prerequisites:

Question: May the first delivery use shared remote cache results?

Accepted answer:

Yes.
Cache-eligible tasks may reuse results through the local and CI remote cache.
Remote cache identity must include every supported platform and toolchain value that can affect the result.

Branch: Cache Eligibility

Q6

Prerequisites:

Question: What proof makes a test task cache-eligible?

Accepted answer:

Use a declared-input contract as the normal proof.
Hash or control test code, application code, mocks, fixtures, relevant root files, platform, toolchain, and result-affecting environment.
Add focused host-state variation proof only for tests that deliberately access host state.

Branch: Channel Reconciliation

Q8

Prerequisites:

Question: What npm dist-tag state must stable and beta reconciliation enforce?

Accepted answer:

A stable release must make both latest and next point to the released version.
A beta release must make beta point to the beta version without changing stable tags.

Branch: Release Identity Conflict

Q9

Prerequisites:

Question: What must happen when an existing Git tag points to another commit?

Accepted answer:

Stop with an error.
Never move or delete a conflicting release tag automatically.

Branch: Remote Cache Writers

Q10

Prerequisites:

Question: Who may write reusable CI remote-cache entries?

Accepted answer:

Only trusted protected-branch and release jobs may write reusable remote-cache entries.
Pull-request jobs may consume trusted entries but must not publish shared entries.

Branch: Test Classification Granularity

Q12

Prerequisites:

Question: At what granularity are tests classified as cacheable or uncached?

Accepted answer:

Classify ordinary CLI tests by file.
Move an unsafe ordinary test into an uncached test file when a file mixes cache policies.
Give registered update cases explicit cache-policy metadata so cacheable and uncached cases can run in separate tasks.
Do not use test-title filters as the durable classification contract.

Branch: Generated Build Identity

Q13

Prerequisites:

Question: Is the generated baseline identity a build input, a build output, or both?

Accepted answer:

Treat src/data/bundled-baseline-identity.generated.ts as a build output only.
Derive it from declared bundled-baseline inputs and restore it on a cache hit.
Exclude its previous generated contents from the build input hash.

Branch: Remote Cache Identity

Q14

Prerequisites:

Question: Which platform and toolchain values belong in the remote-cache identity?

Accepted answer:

Include operating system, architecture, exact Bun and Node versions, relevant environment values, source and fixture inputs, required root inputs, and the lockfile.

Branch: Remote Cache Integrity

Q15

Prerequisites:

Question: Must shared remote-cache entries use artifact signatures?

Accepted answer:

Yes.
CI must verify a shared cache artifact before it can supply a build or test result.

Branch: Release Routing

Q11

Prerequisites:

Question: Where must the npm version probe route new releases and existing-version retries?

Accepted answer:

The uncached release dispatcher must check whether the package version exists before Turbo verification.
An existing version follows the current retry path without deterministic verification.
A new version runs the cached verification graph and then checks npm again immediately before publication.

Branch: Delivery Scope

Q16

Prerequisites:

Question: Is external release-state reconciliation part of this caching delivery?

Accepted answer:

No. Park external release-state reconciliation as separate work.
Preserve the current external release behavior in this delivery.
Keep Q4, Q8, and Q9 as accepted requirements for the parked branch.

Branch: Development and PR Cache Reuse

Q17

Prerequisites:

Question: How may local development and pull-request runs reuse cache entries without supplying artifacts to protected release jobs?

Accepted answer:

This supersedes Q10 for the development-cache namespace only; Q10 continues to govern the protected namespace.
A passing local development task may write a signed development-cache entry.
Same-repository pull-request CI may read and write the same development-cache namespace.
Protected and release jobs use a separate trusted namespace and never consume development-cache entries.
Fork pull requests receive no cache credentials.
A platform or environment mismatch produces a cache miss under Q14.

Branch: Timing and Network Tests

Q18

Prerequisites:

Question: Are timing-sensitive or network-using tests cacheable?

Accepted answer:

Yes, when their declared cache identity matches.
Prefer Effect TestClock for Effect-managed sleeps, schedules, retries, and timeouts.
Prefer test-owned loopback servers and deterministic synchronization for network-like behavior.
Effect TestClock does not control Date.now(), operating-system process timeouts, or time inside a child process.

Branch: Cached Release Artifact

Q19

Prerequisites:

Question: May release publication consume a restored build artifact from trusted remote cache?

Accepted answer:

Yes.
The entry must have a valid signature, come from the trusted namespace, match the complete build hash, restore every declared output, and leave the worktree clean.

Branch: Cache Acceptance Proof

Q20

Prerequisites:

Question: What cache behavior proof is required before delivery is accepted?

Accepted answer:

Force build, typecheck, and test tasks to execute successfully.
Prove first-run misses and identical second-run hits.
Prove deleted declared outputs are restored on a hit.
Prove each declared input and runtime-identity change causes a miss.
Prove cached and fresh build artifacts are byte-identical.
Prove every test is assigned exactly once and uncached exceptions always execute.
Prove fresh and cached build paths leave the worktree clean.

Branch: Real OS Timing

Q21

Prerequisites:

Question: May a real operating-system timing assertion be cached before it has a controllable boundary?

Accepted answer:

No.
Keep the current real child-process timing assertion uncached until it uses a controllable boundary.
Effect TestClock remains the preferred boundary for Effect-managed time, but it does not control child-process wall time.

Branch: PR Cache Provenance

Q22

Prerequisites:

Question: May a developer-originated cached pass satisfy a required pull-request check?

Accepted answer:

Yes.
Authenticated developer machines and same-repository pull-request CI share a signed development-cache namespace.
A signature proves development-cache authority, not execution by a clean CI runner; this trust tradeoff is accepted for required pull-request checks.
Protected main and release jobs use a separate signed namespace and never consume development-cache artifacts.
A new protected-branch source hash must execute before it can become trusted release evidence.

Shared-Understanding Confirmation

Confirmed by the user on 2026-08-06.
The active design frontier is empty.
External release-state reconciliation remains parked as separate work.

Turborepo Release Caching Grill Log

On this page