Stage ordering and lowering - Verification and traceability

Platform spec article

Stage ordering and lowering - Verification and traceability

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

ADRs (3)

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

   This feature hub owns normative MUST/SHOULD contract text for Stage ordering and lowering.

   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/build-pipeline/stage-ordering/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 Stage ordering and lowering.

   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/

   Open full ADR page

3. 0003-canonical-phase-dag Canonical parse-to-lowering phase DAG Accepted

   Pipeline ordering was fragmented across crates before `beskid_pipeline` phase ids.

   Context

   Reference compiler must emit stable beskid_pipeline phase events from parse through lower.ready without reordering semantic gates relative to mod boundaries.

   Decision

   Phase literals are defined in compiler/crates/beskid_pipeline/src/phases.rs and asserted by conformance tests; CLI/LSP observers rely on the same ids.

   Consequences

   Reordering phases requires an ADR and registry updates.

   Verification anchors

   • compiler/crates/beskid_pipeline/
   • compiler/crates/beskid_analysis/src/services.rs.

   Open full ADR page

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
• 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
  Test harnesses and fixtures

  Conformance evidence

Implementation anchors:

• compiler/crates/beskid_analysis/src/projects/assembly/
• compiler/crates/beskid_analysis/src/services/front_end.rs
• compiler/crates/beskid_codegen/src/services.rs
• compiler/crates/beskid_analysis/src/services.rs
• compiler/crates/beskid_cli/src/commands/build.rs
• compiler/crates/beskid_engine/src/services.rs
• compiler/crates/beskid_tests/src/projects/assembly.rs

Traceability should include tests that assert semantic failures stop before backend stages.

Mod phase ordering tests

When the mod host ships, add integration tests under compiler/crates/beskid_tests/ that:

1. Install a test PipelineObserver collecting PhaseStart / PhaseEnd ids.
2. Assert the substring parse → mod.load → mod.collect → mod.generate → semantic → mod.analyze → lower.ready → lower appears in order for a workspace fixture with a transitive Mod dependency (see Project manifest contract / verification for manifest fixture layout).

Any change to FULL_BUILD_PHASE_ORDER or mod insertion rules must update these expectations in the same commit.