How does an in-process incremental compiler (like TypeScript's --incremental mode or a language server's recompilation) differ from build-system-level task caching, and where can each one still get correctness wrong?

## Two mechanisms that both go by 'incremental' There are two distinct mechanisms that both go by 'incremental' and are easy to conflate: whole-task caching at the build-system level, and fine-grained incremental compilation inside a single compiler process. They solve overlapping problems with very different mechanisms, and understanding both is necessary to reason about where a monorepo's rebuild speed is actually coming from. ## Task-level caching treats a task as a black box Task-level caching, as implemented by tools like `Bazel`, `Nx`, and `Turborepo`, treats each task (compiling a package, running a test file) as an opaque black box. It computes a content-addressed key from that task's declared inputs and either reuses a previously stored complete output or re-executes the entire task from a cold start. Nothing about the internals of the compiler matters to this layer — from its point of view, a compiler compiling forty files is indistinguishable from it compiling four hundred; it either replays the whole cached result or invokes the whole tool again. This granularity is coarse but simple and easy to reason about, because the correctness argument reduces to 'is the declared input set for this whole task exhaustive.' ## In-process incremental compilation works at a finer grain In-process incremental compilation works at a much finer grain, inside a single long-running compiler invocation. TypeScript's `incremental` flag (backed by a build-info file that persists a snapshot of the program's dependency graph and per-file semantic diagnostics) and its watch mode are the canonical example: rather than re-parsing and re-type-checking every file in a project on every keystroke-driven save, the compiler keeps (or reloads) a model of which files depend on which declarations, and when a file changes, it recomputes only that file and whatever the dependency graph says is transitively affected — not the whole project. A long-running watch process or a language-server process (the same engine that powers live editor type errors) amortizes this further by never fully restarting; it just applies incremental updates to its in-memory program model on every edit. The payoff is dramatic for the local edit-save loop: a full clean compile of a large TypeScript project might take 30+ seconds, but an incremental recompile of one changed file inside a warm watch process can be near-instant, because parsing, binding, and re-type-checking are the expensive steps and this mechanism skips them for everything the dependency model says is unaffected. ## Where the fine-grained mechanism gets correctness wrong The trade-off is that this speed comes from trusting an internal model of 'what depends on what' that's baked into the compiler's own logic, rather than from an external, structurally enforced input declaration like sandboxing provides for task-level caching. That internal model can be wrong in edge cases that are genuinely hard to track precisely: - **structural typing** — a type used only because its shape matches, with no explicit import; - **ambient/global type declarations**; - **decorators or metaprogramming** that alter behavior in ways the dependency tracker doesn't model; - **bugs in the incremental compiler itself**. When the model misses a real dependency, the result is the same class of failure as an under-specified cache key at the task level: a stale, subtly wrong recompilation that reports success but doesn't reflect a change that should have propagated. This is why 'delete the build-info cache and do a clean rebuild, and the bug goes away' is such a common and recognizable debugging step for TypeScript developers — it's a symptom of exactly this class of incremental-compiler staleness, not usually a bug in the developer's own code. ## Inner loop versus outer loop Because of this correctness gap, the two mechanisms are typically used in different places for different reasons. | Mechanism | Which loop it serves | |---|---| | Incremental, stateful compilation | optimized for the tight local inner loop — a developer saving a file every few seconds and wanting fast feedback, where an occasional false-negative (a missed error) is an acceptable, quickly-self-corrected cost against the alternative of a slow feedback loop killing productivity | | Whole-task content-addressed caching | optimized for the outer loop — CI, and cross-machine reuse — where correctness matters far more than saving the last few hundred milliseconds | For that outer loop, a full, from-scratch invocation of the compiler is preferred specifically because it doesn't carry forward any stateful in-process model that could be wrong; CI pipelines routinely disable or ignore incremental-mode state precisely to avoid inheriting a potentially-stale build-info file from a previous, unrelated commit. ## How the two layers compose A concrete pattern seen across many monorepo toolchains: `Nx` and `Turborepo` provide task-level caching for the whole build/typecheck command, while the underlying tool invoked by that command (`tsc`, `webpack` in dev mode, `jest` in watch mode) may itself use its own internal incremental mechanism during local development. These two layers compose — task caching decides whether to invoke the tool at all, and if it does invoke it, the tool's own incremental engine decides how much internal work it can skip — but they're solving the problem at different scopes with different correctness guarantees, and conflating them (assuming task-cache-level hermeticity extends to trusting the compiler's internal incremental state across machines) is a common source of 'why is CI's result different from my local build' confusion.