design: define deterministic parallel compilation boundary

[vycdev2]

Summary

Define the first deterministic parallel-compilation and namespace-scheduling boundary after the initial incremental query database is selected, without making worker timing observable or weakening Jett’s declaration and diagnostic ordering.

Source documentation

• docs/progress.md, Phase L: Incremental Compilation marks parallel compilation as not started.
• docs/architecture.md, Incremental Compilation Strategy describes future demand-driven queries, diagnostics, cycles, cancellation, and arena ownership.
• docs/architecture.md, Phase L calls for parallel compilation of independent namespaces.
• Issue design: define initial Salsa query and invalidation boundary #147 and PR docs: define incremental query boundary #149 select the initial query/invalidation boundary and explicitly defer parallel query execution and namespace scheduling.

Current state

The compiler has no parallel compilation scheduler or Salsa database. Driver entry points run parsing, stdlib discovery, resolution, type checking, and verification sequentially. Project discovery assigns FileId values while iterating lexically sorted paths and mutates a single SymbolInterner; diagnostics are accumulated in phase order. The only compiler threads provide larger stacks for runtime or verification execution rather than scheduling compilation work.

The current architecture does not yet say which work units may execute concurrently, how namespace and top-to-bottom dependencies constrain them, which interners and query-owned values may be shared, or how diagnostics, cancellation, stale LSP revisions, and task failures remain deterministic across worker counts.

Scope

This issue selects and documents one bounded parallel-compilation contract. It includes:

• the first parallelizable unit, such as independent namespace queries or file parsing, and the dependency graph that decides independence;
• the phases and declarations that must remain ordered, including strict top-to-bottom visibility, mutual:, merged stdlib fragments, and namespace/export dependencies;
• ownership and thread-safety boundaries for query snapshots, ASTs, diagnostics, file/declaration identities, symbol/type interners, and body-local data;
• deterministic merge and publication rules for results and diagnostics independent of worker timing and worker count;
• cycle, task failure, cancellation, stale LSP revision, and CLI behavior, including preventing partial results from being published or cached;
• bounded worker/resource policy and whether CLI, LSP, and test execution use different defaults;
• a focused implementation sequence plus repeatability, cancellation, and race-oriented verification.

Explicitly excludes implementing the deferred CST, HIR/MIR/native lowering, distributed builds, persistent/content-addressed caching, broad performance tuning, and Jett source-level run task semantics.

Acceptance criteria

• The first parallelizable work unit and its dependency graph are selected.
• Required sequential boundaries and safe concurrency boundaries preserve declaration order, mutual:, namespaces, exports, and stdlib fragment semantics.
• Ownership, Send/Sync, interner, identity, query snapshot, and diagnostics-aggregation rules are explicit.
• Identical inputs produce identical observable results and diagnostic ordering across worker counts and repeated runs.
• Cycles, task failures, cancellation, and stale LSP revisions have deterministic outcomes and cannot publish partial results.
• Worker/resource limits and CLI, LSP, and test defaults are defined.
• A bounded implementation and test sequence covers independent work, dependency ordering, deterministic diagnostics, repeated runs, cancellation, and stale-result suppression.
• Content-addressed caching and future frontend/backend phases remain separate follow-up work.
• docs/design.md, docs/architecture.md, and docs/progress.md remain aligned with the selected policy.

Dependencies / open questions

The design should build on #147 / PR #149’s selected query ownership, FileKey identity, immutable query results, diagnostics ordering, and revision model. Issues #20 and #22 are future HIR/MIR consumers but need not block this design decision. The separate Phase L content-addressed caching row should remain out of scope.

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.