Incremental scheduling and determinism - Contracts and edge cases

Platform spec article

Incremental scheduling and determinism - Contracts and edge cases

Back to Incremental scheduling and determinism ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (3)

1. 0001-feature-hub-authority Feature hub authority Accepted

   This feature hub owns normative MUST/SHOULD contract text for Incremental scheduling and determinism.

   Context

   Sibling articles under this feature previously restated requirements in inconsistent forms.

   Decision

   This feature hub owns normative MUST/SHOULD contract text. Sibling articles must not redefine hub requirements and should link here for authority.

   Consequences

   Contract changes start on the hub or in linked ADRs, then propagate to articles and implementation anchors.

   Verification anchors

   • site/website/src/content/docs/platform-spec/compiler/compiler-mods/incremental-scheduling-determinism/index.mdx
   • article bundle under the same feature directory.

   Open full ADR page

2. 0002-spec-over-implementation-notes Specification over implementation notes Accepted

   Platform-spec text supersedes informal crate comments for Incremental scheduling and determinism.

   Context

   Implementation crates accumulated informal notes that diverged from published contracts.

   Decision

   Normative platform-spec prose and ADRs under this feature supersede informal comments in implementation crates until explicitly migrated into spec text.

   Consequences

   Engineers file spec/ADR updates when behavior changes; crate comments are non-authoritative for conformance arguments.

   Verification anchors

   • compiler/crates/beskid_analysis/src/analysis/rules/staged/
   • compiler/crates/beskid_lsp/

   Open full ADR page

3. 0003-mod-invalidation-deterministic-replay Deterministic mod invalidation and replay Accepted

   Incremental mod runs produced unstable ordering.

   Context

   Incremental mod runs produced unstable ordering.

   Decision

   Invalidation keys and dirty sets for mod pipelines must replay deterministically for identical inputs (Collector scope + syntax snapshot hashes).

   Consequences

   LSP rescan triggers share the same keys as batch compile.

   Verification anchors

   • compiler/crates/beskid_lsp/
   • compiler/crates/beskid_analysis/src/analysis/rules/staged/.

   Open full ADR page

Articles

• Incremental scheduling and determinism - Contracts and edge cases Cache boundaries, invalidation keys, and replay guarantees for mod outputs and Mod SDK reads. article Standard Reviewed Thu Apr 30
• Incremental scheduling and determinism - Design model Cache boundaries, invalidation keys, and replay guarantees for mod outputs and Mod SDK reads. article Standard Reviewed Fri May 01
• Incremental scheduling and determinism - Examples Cache boundaries, invalidation keys, and replay guarantees for mod outputs and Mod SDK reads. article Standard Reviewed Thu Apr 30
• Incremental scheduling and determinism - FAQ and troubleshooting Cache boundaries, invalidation keys, and replay guarantees for mod outputs and Mod SDK reads. article Standard Reviewed Thu Apr 30
• Incremental scheduling and determinism - Flow and algorithm Cache boundaries, invalidation keys, and replay guarantees for mod outputs and Mod SDK reads. article Standard Reviewed Thu Apr 30
• Incremental scheduling and determinism - Verification and traceability Cache boundaries, invalidation keys, and replay guarantees for mod outputs and Mod SDK reads. article Standard Reviewed Thu Apr 30

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) · 3 H2 heading(s)

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

Related spec docs

• Feature
  Incremental scheduling and determinism

  Parent feature hub

This article states contracts and edge cases for Incremental scheduling and determinism.

Hard requirements

• Deterministic ordering — discovery and execution order must be reproducible from equal inputs (path-normalized roots, sorted files, stable tie-breaks).
• Bounded work — host enforces step limits, allocation caps, and recursion depth across nested meta calls.
• Versioned facades — Beskid.Compiler surface is tied to compiler language version tokens exposed on the compilation instance.

Edge cases

• Partial programs — facades must tolerate incomplete syntax where the language permits; diagnostics are preferred over host panics.
• Conflicting edits — multiple meta contributors touching the same declaration identity produce a deterministic merge failure surfaced as structured diagnostics.