Compiler Query Engine And Incremental Compilation

The compiler query engine is the source-owned dependency and reuse boundary for

incremental compilation. It records stable query keys, deterministic providers,

persisted output schemas, red/green dependency status, cache miss reasons, and

incremental rebuild scenarios.

Run the bounded gate with:

make compiler-query-engine-check
make incremental-compiler-check

incremental-compiler-check depends on compiler-query-engine-check, so the

existing incremental compiler gate now validates query-engine evidence before

checking compile-time budgets. These gates do not run self-host, release,

deployment, emulator, remote publication, or broad benchmark jobs.

Evidence Files

• compiler-query/query-kinds.tsv: stable query key prefixes for source files,

tokens, parsed forms, module signatures, imports, type/effect results, HIR,

MIR, native IR, object output, diagnostics, and documentation extraction.

• compiler-query/provider-registry.tsv: deterministic provider registry and

the explicit always-evaluate filesystem boundary for source files.

• compiler-query/output-schemas.tsv: versioned persisted output schemas.
• compiler-query/diagnostics.tsv: stable diagnostics for query failures.
• compiler-query/incremental-scenarios.tsv: no-change, leaf edit, import

edit, signature change, package change, and diagnostic-only rebuild behavior.

• release/compiler-query-graph-report.tsv: bounded query graph inspection

report with red/green dependency status.

• release/compiler-query-cache-miss-report.tsv: cache miss report explaining

why each recomputed query was red.

• compiler-query/verification-cases.tsv: valid and invalid fixtures used by

the gate.

Query Keys

Query keys are content and configuration keys, not file modification time keys.

Every key has a stable q: prefix and every output has a query-output-v1

schema. The core query kinds are:

• source-file;
• token-stream;
• parsed-forms;
• module-signature;
• imports;
• type-effect-result;
• hir;
• mir;
• native-ir;
• object-output;
• diagnostics;
• documentation-extraction.

The source-file query is always evaluated because it is the filesystem input

boundary. Dependent queries can stay green when the content fingerprint remains

unchanged.

Red/Green Reuse

A green query may only depend on green queries. A red query must have a cache

miss row explaining the invalidation reason. No-change rebuilds reuse parser,

checker, HIR, MIR, native IR, object, diagnostics, and documentation work.

Single-leaf edits recompute the edited leaf chain while reusing green work for

unaffected dependencies.

Provider Purity

Providers must be deterministic and side-effect-free. The only default

side-effect boundary is the source-file provider, which is explicitly marked

always-evaluate and restricted to source reads. A provider that is

nondeterministic and not always-evaluate is rejected.

Diagnostics

The gate rejects query evidence with stable diagnostics:

ZERO_QUERY_STALE_INPUT
ZERO_QUERY_SCHEMA_VERSION
ZERO_QUERY_NONDETERMINISTIC_PROVIDER
ZERO_QUERY_DEPENDENCY_CYCLE
ZERO_QUERY_INVALID_CACHE_ROOT
ZERO_QUERY_UNEXPLAINED_MISS

These diagnostics are public because cache behavior must be explainable. A

developer should be able to inspect the graph report and cache miss report and

understand why a query was reused or recomputed.

Cache Root Policy

Compiler query cache evidence must stay under:

build/compiler-query/cache/v1/

This keeps query cache artifacts separate from release artifacts, package

registry state, and runtime output.