nocter-compiler-computation#

Responsibility#

Own the compiler-domain query entry shared by ephemeral command compilation and persistent workspace analysis.

Contract#

The crate accepts atomic source revisions and returns a token bound to the computation owner, the exact source-overlay generation, and its source-identity domain. That token is required both to lend the computed syntax provider and to construct package source maps before analyzing a discovered unit. The crate derives and publishes semantic inputs from that exact unit, then demands the sole complete-or-incomplete semantic branch. It then seals that reusable branch with the exact current discovery unit outside the query cache. The publication types, semantic query entries, and sealing constructor are private to this crate, so callers cannot assemble mismatched module, body, and scope authority. It owns the computation database, retention policy, and query instrumentation but does not select packages, discover modules, translate session outcomes, build targets, or interpret editor requests.

Internal Responsibilities#

• content-addressed parse, declaration-surface, and module-surface queries
• stable block-and-initializer body-input collection from declaration surfaces
• atomic semantic-scope publication
• private declaration, preparation, body, materialization, relation, finalization, and unit query graph
• closed unit-analysis demand
• bounded retention of source revisions and dependency-closed inactive-entry collection
• execution and reuse statistics for equivalence tests

Invariants#

• Command and workspace callers differ only in owner lifetime, not query providers or stage order.
• The computed syntax provider accepts only a normalized source value matching the canonical path and bytes observed through its admitted overlay. Validation reuses the overlay's frozen first observation; the parse query key then owns the exact normalized text and never opens a path.
• Declaration-surface queries consume the same content-addressed parse product. Module-surface queries consume declaration surfaces rather than raw source identity, so body-only edits do not invalidate module contracts.
• A source token from another owner or an earlier overlay generation is rejected before any query is supplied or semantic input is published. Discovery additionally rejects a package graph built from an independently created overlay, even when its explicit overrides are byte-identical.
• Semantic input publication may advance the internal database without invalidating the current source token; source authority and internal query revisions are separate identities.
• One discovered unit supplies both semantic and exact-current fingerprints atomically.
• The current-source fingerprint includes complete process-local source identities in addition to paths and bytes. Metadata-only document generations retain those identities and may reuse source-backed semantics; every content transition changes them, so reverting text cannot revive an older source projection.
• Query reuse owns semantic equivalence only. The returned unit-analysis envelope always retains the current discovery unit, so editor document versions, open-document state, and other overlay metadata cannot be inherited from an equivalent earlier source revision.
• Semantic fingerprints may declare two source publications reusable; opaque overlay identity separately decides whether a token can authorize physical source access. Neither concept is reconstructed from the other.
• Callers cannot access the raw computation database or demand an intermediate semantic query.
• Authored rejection and compiler-domain integrity failure are separate outcomes. A rejected stage prevents its downstream query from being demanded; projection or checking failure retains its typed cause through session.
• Complete, incomplete-syntax, declaration, preparation, body, and finalization queries validate their own input capability. Correctness does not rely on an upstream caller remembering the scheduler order.
• A body query receives a sealed exact-body input that binds the demanded physical source identity and fingerprint to the declaration identity or lexical product that consumes it. The checking context cannot accept an unrelated source token as a procedural invalidation proof.
• Declaration-surface pruning and exact-body publication share the syntax crate's complete semantic body-root set. Adding a new semantic body form therefore cannot leave computation with an unpublished per-body input while direct checking still succeeds.
• The current checking context owns one immutable body-source catalog for its complete query graph. Per-body name and type queries select from that catalog, while final materialization shares the same catalog allocation; computation does not ask checking to rediscover body syntax per stage.
• Canonical body replay publishes one exact-current materialization. A relation-input projection narrows its fingerprint only by eliding scalar literal payloads; identifiers, operators, parsed body shape, interpolation expressions, and the complete declaration surface remain exact.
• Provenance, execution, and loan analysis depend on that narrow structural projection. Finalization depends independently on the exact-current materialization and joins reusable source-neutral relations with its current source projection. A literal edit can therefore reuse relation facts without reusing source positions, body text, or an earlier semantic authority.
• Structural equivalence is owned by the syntax surface and consumed by computation. Checking does not inspect source text to decide reuse, and LSP does not define an editor-only equivalence rule.
• Incomplete declaration recovery retains both the authoritative declaration rejection and any later preparation or body-check rejection reached while collecting editor evidence.
• The crate schedules checking through ReusableCheckingQuery, but does not construct its internal join. Checking itself owns the paired declaration recipe and materializes the exact-current bindings, spellings, and source projection behind one safe transition.
• Source admission fingerprints an overlay without duplicating its bytes into the query database. Old semantic inputs and query products cannot accumulate beyond the retained source-revision window.
• The crate owns no filesystem topology, package acquisition, session, target, native, or protocol policy.