Skip to content
Beskid Platform specification

Beskid

Jump to a Beskid service

Beskid

Jump to a Beskid service

Incremental scheduling and determinism - Design model

Platform spec article

Incremental scheduling and determinism - Design model

Back to Incremental scheduling and determinism Open feature in platform map

Spec standingStandard

Owner
Piotr Mikstacki
Submitter
Piotr Mikstacki

This article documents the design model for Incremental scheduling and determinism.

Language alignment

Section titled “Language alignment”

Isolating capture yields narrow dirty sets; aggregating capture widens invalidation by language intent—encoded as explicit graph edges here.

Persistent entities

Section titled “Persistent entities”
  • Compilation instance — implicit handle to the compilation under construction (Compiler Mod SDK / Beskid.Compiler.Compilation).
  • Syntax snapshot — immutable tree with stable node identities suitable for incremental keys.
  • Capability tokens — host-granted permissions for I/O, diagnostics, and emit operations during mod execution.

Boundaries

Section titled “Boundaries”
  • Mod SDK facades never bypass the host bridge for effects.
  • Generation logic in the reference compiler remains Rust-internal; Beskid sees only the generated Beskid.Compiler.* projection.

Anchored code paths

Section titled “Anchored code paths”
  • compiler/crates/beskid_analysis/src/analysis/rules/staged/ — precedent for staged invalidation.
  • compiler/crates/beskid_lsp/ — incremental document models and rescan triggers.

Invalidation keys (normative)

Section titled “Invalidation keys (normative)”

Hosts must record, per mod contract schedule, at minimum:

  1. syntax_generation_id — Monotonic per compilation unit (or workspace slice) counter bumped whenever a new parse snapshot replaces the previous Program.
  2. capture_fingerprint — Hash of stable syntax node identities and predicate parameters bound during capture (isolating capture narrows this hash to declared roots; aggregating capture mixes in workspace-wide generation ids).
  3. manifest_generation_id — Hash of relevant Project.proj / Workspace.proj / lockfile bytes affecting mod package identity, capabilities, or dependencies.
  4. capability_set_id — Canonical encoding of granted capabilities for the active mod schedule.

Replay must reuse cached process outputs when and only when all four ids match prior committed work. Any mismatch must drop cached process/emit artifacts before running the next round.

Isolating vs aggregating (implementation mapping)

Section titled “Isolating vs aggregating (implementation mapping)”
  • Isolating — Dirty set includes only items whose capture fingerprints reference changed syntax ids or directly imported modules touched on disk.
  • Aggregating — Declarations in language-meta force inclusion of syntax_generation_id for every compilation unit in the attach target when any file in the member changes; hosts must record an explicit graph edge so tools can explain broad invalidation.

Atomicity

Section titled “Atomicity”

Within one syntax.generation commit boundary, emit applications and diagnostic emissions must commit atomically: downstream semantic stages must not observe partially applied generator edits (Typed emitter and transforms).