Salsa database owns incremental analysis memoization

Platform spec ADR

Salsa database owns incremental analysis memoization

Back to Stage ordering and lowering ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

Articles

• Stage ordering and lowering - Contracts and edge cases Required ordering guarantees and behavior under parse or semantic failures. article Standard
• Stage ordering and lowering - Design model Pipeline stage model and artifact boundaries for the reference compiler. article Standard
• Stage ordering and lowering - Examples Newcomer-oriented examples of pipeline execution order and failure points. article Standard
• Stage ordering and lowering - FAQ and troubleshooting Troubleshooting guide for stage ordering assumptions in build and run commands. article Standard
• Stage ordering and lowering - Flow and algorithm Ordered lowering algorithm used by build and run command paths. article Standard
• Unit artifact cache schema On-disk and in-process unit snapshot layout under obj/beskid/cache/salsa/units/. article Standard Reviewed Fri Jun 05
• Stage ordering and lowering - Verification and traceability Source and test anchors that verify lowering order and backend artifact handoff. article Standard

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 0 SpecSection(s) · 1 H2 heading(s)

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  Stage ordering and lowering

  Parent feature hub

• Feature
  LSP snapshot and refresh contract

  IDE invalidation consumer

Context

Within-run deduplication and ad-hoc JSON unit caches did not provide dependency-tracked invalidation. LSP and CLI paths recomputed assembly and typing independently; session caches could return stale assemblies after edits.

Decision

1. beskid_queries::BeskidDatabase is the single incremental host for analysis memoization (Salsa 0.26 inputs + tracked queries + on-disk persistence under {project}/obj/beskid/cache/salsa/).
2. CLI, LSP, and tests route prepare/assembly through beskid_queries entry points—CLI via process-scoped session in beskid_queries::session, LSP via workspace State.compilation_db, tests via local or session handles—no second analysis spine.
3. Unit materialization during program assembly uses Salsa-backed unit queries (parse_and_expand_unit_tracked, unit_hir_tracked, unit_imports); legacy obj/beskid/cache/units/ JSON records are retired in favor of obj/beskid/cache/salsa/units/{content_fp}/ (see unit artifact cache schema).
4. Pipeline observers emit salsa.query_hit, salsa.query_miss, salsa.revision_bump, salsa.artifact_disk_hit, and salsa.artifact_disk_miss counters for verification.

Consequences

• File text edits invalidate only affected units and dependents via import edges.
• LSP didChange sets file_text inputs; diagnostics and IDE snapshots share the same database.
• Mod-host invalidation keys (syntax_generation_id, manifest_generation_id, capability_set_id) map to Salsa inputs in beskid_queries::modhost.

Status

Accepted — implemented in compiler/crates/beskid_queries/ and compiler/crates/beskid_artifacts/. Legacy units/ JSON cache is retired; disk persistence uses content-addressed salsa/units/ snapshots.