Document cache behavior with --only

[solsson]

Sibling to #1, same level of surprise. The definition of "correctness" for build cache is unclear. Turbo has flexibility in config and CLI flags that's easy to use but hard to grasp the cache effects of.

[solsson]

Research by Opus 5:

PR #2 — Document cache behavior with --only

Recommendation: do not close — re-scope. Unlike #1, upstream has made no progress on this one, so there is no upstream feature that closes it. What upstream has shipped only supersedes the parts of this PR that overlap with #1.

Upstream status: unchanged

I diffed crates/turborepo-engine/src/builder.rs between our fork base (4b3e7cc96d, release 2.9.10) and v2.10.6. The --only edge-dropping logic is byte-for-byte identical:

if let Some(allowed_tasks) = &allowed_tasks
    && !allowed_tasks.contains(&from_task_id)
{
    return;      // topological (^) dependency edge, silently dropped
}

if let Some(allowed_tasks) = &allowed_tasks
    && !allowed_tasks.contains(&from_task_id)
{
    continue;    // direct task dependency edge, silently dropped
}

Both sites still drop the edge with no warning and no contribution to the cache key. Nothing in the v2.10.x deferred-hashing work touches this: jit and dependencyOutputs change when inputs are hashed, not which graph edges survive --only. A task whose ^bundle edge was dropped has no dependency to defer on in the first place, so the new modes cannot help.

Searching upstream commits between the fork base and v2.10.6 for --only-related changes turns up only unrelated matches (Cargo-only repos, errors-only, etc.). This remains entirely ours to carry.

What to strip from this PR

Of the 6 commits here, the ones that duplicate #1 are now obsolete and should come out:

• the dependsOn output/input overlap detection commit — superseded by upstream #13125 / #13129 (see the Include outputs from dependsOn tasks in same turbo run input hashes #1 comment)
• the "inputs hash issue" test case — upstream added its own regression coverage in run_caching.rs

That leaves the genuinely unaddressed material:

1. The #[should_panic] test asserting turbo bundle --only --filter=runtime should keep types#bundle in the graph. Worth keeping as executable documentation of the divergence.
2. The warning when --only drops dependency edges, suggesting which --filter flags to add.

A design note before we rebase

The #[should_panic] test frames edge-dropping as a bug to be fixed. I'd argue we should not try to fix it by preserving edges. Changing which nodes --only keeps in the graph is a semantic change to a documented flag, and it is the single most likely thing to conflict on every future rebase. Folding the dropped dependency's source hashes into the cache key (the approach in #3) gets us correctness without diverging on graph shape.

If we agree, this PR's test should be reworded from "this is broken" to "this documents that --only intentionally drops edges, which is why we compensate in the cache key" — and stay #[should_panic] as a tripwire that tells us if upstream ever changes its mind.

Suggested action

1. Rebase onto v2.10.6, dropping the two superseded commits.
2. Keep the warning and the tripwire test; reword the test's doc comment per above.
3. Fold this into Fewer false cache positives: hash --only inputs and dependsOn cache=false tasks #3 rather than shipping it separately — the warning and the hash compensation are the same feature, and reviewing them apart is what led to the overlap in the first place.
4. File an upstream issue. This is a real cache-correctness bug that produces silently stale artifacts, and upstream appears simply not to know about it. Their receptiveness to the Tasks should run dependsOn before hashing inputs vercel/turborepo#8051 work suggests it is worth reporting rather than carrying forever. A minimal repro from the #[should_panic] test would make the case well.