Incremental scheduling and determinism - Flow and algorithm

Platform spec article

Incremental scheduling and determinism - Flow and algorithm

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 documents flow and algorithms for Incremental scheduling and determinism.

Primary flow (incremental-specific)

1. Ingest signals — Collect file watcher events, manifest edits, lockfile changes, and explicit CLI/LSP invalidation hooks (invalidate_compilation_cache patterns in compiler/crates/beskid_lsp).
2. Classify scope — Determine whether each dirty signal is narrow (single compilation unit / isolating capture) or wide (workspace member or aggregating capture). Wide signals must bump syntax_generation_id for all units in the attach target.
3. Recompute keys — For each scheduled mod contract, rebuild capture_fingerprint, manifest_generation_id, and capability_set_id per design model. Drop any cache entry whose tuple diverges.
4. Schedule rounds — Enqueue mod contracts in deterministic discovery order (stable module walk, stable tie-break on equal keys). Respect maxGeneratorRounds from Project manifest contract.
5. Run host bridge — For each item, if cache hit for process-only work, reuse validated artifacts; otherwise run capture → process under capability policy.
6. Commit emit — Apply typed contributions atomically, bump syntax_generation_id, re-parse affected roots, and emit syntax.generation for telemetry.
7. Replay verification — On identical inputs and ids, hosts must reproduce the same ordered diagnostics and the same merge outcome (see contracts article for determinism tests).

Ordering constraints

• Incremental caches must not survive cross-compiler-version bumps without clearing: include compiler semver or commit identity in manifest_generation_id or a sibling host key.
• Soft invalidation (skip graph rebuild) is permitted only when design-model soft rules hold; otherwise fall back to full CompilationContext rebuild.
• Semantic queries declared against query_semantic_snapshot must declare minimum snapshot version; the host must defer with an explicit diagnostic when the staged pipeline has not reached that version yet.