Add an execution platform for the Canonical conformance suite

.github/dependabot.yml

@@ -4,3 +4,7 @@ updates:
     directory: /
     schedule:
       interval: weekly
+  - package-ecosystem: cargo
+    directory: /
+    schedule:
+      interval: weekly

.github/workflows/ci.yml

@@ -16,6 +16,21 @@ jobs:
       - name: Check out repository
         uses: actions/checkout@v7
 
+      - name: Read supported specification revision
+        id: specification
+        shell: bash
+        run: |
+          grep -Eq '^[0-9a-f]{40}$' tests/specification-revision
+          revision=$(tr -d '\n' < tests/specification-revision)
+          printf 'revision=%s\n' "$revision" >> "$GITHUB_OUTPUT"
+
+      - name: Check out canonical specification
+        uses: actions/checkout@v7
+        with:
+          repository: stack-sh/specification
+          ref: ${{ steps.specification.outputs.revision }}
+          path: .stack-specification
+
       - name: Install latest stable Rust toolchain
         run: rustup toolchain install stable --profile minimal --component clippy,rustfmt,llvm-tools-preview
 
@@ -25,6 +40,11 @@ jobs:
       - name: Run tests
         run: cargo +stable test
 
+      - name: Run canonical conformance suite
+        env:
+          STACK_SPECIFICATION_DIR: .stack-specification
+        run: cargo +stable test --features conformance --test conformance
+
       - name: Run Clippy
         run: cargo +stable clippy --all-targets --all-features -- -D warnings
 

AGENTS.md

@@ -16,6 +16,7 @@ The canonical language contract is `stack-sh/specification`. Never introduce syn
 
 - Format: `cargo fmt --check`
 - Test: `cargo test`
+- Conformance: `STACK_SPECIFICATION_DIR=../specification cargo test --features conformance --test conformance`
 - Unit-test coverage: `cargo llvm-cov --lib --all-features --workspace --fail-under-lines 95 --fail-under-functions 95 --fail-under-regions 95`
 - Lint: `cargo clippy --all-targets --all-features -- -D warnings`
 - Documentation: `cargo doc --no-deps`

Cargo.toml

@@ -13,6 +13,17 @@ categories = ["parser-implementations"]
 [lib]
 path = "src/lib.rs"
 
+[features]
+conformance = []
+
+[[test]]
+name = "conformance"
+path = "tests/conformance.rs"
+required-features = ["conformance"]
+
+[dev-dependencies]
+serde_json = "1.0.151"
+
 [lints.clippy]
 expect_used = "deny"
 panic = "deny"

README.md

@@ -34,11 +34,24 @@ Install [`cargo-llvm-cov`](https://github.com/taiki-e/cargo-llvm-cov) before run
 
 Package-level Clippy lints reject panic-producing `unwrap`, `expect`, `panic`, `unreachable`, `todo`, and `unimplemented` calls in library and test targets.
 
+## Conformance
+
+The language-independent schemas and fixtures live in [`stack-sh/specification`](https://github.com/stack-sh/specification). This repository records its tested specification commit in [`tests/specification-revision`](./tests/specification-revision).
+
+Run the canonical suite against a local specification checkout:
+
+```sh
+STACK_SPECIFICATION_DIR=../specification cargo test --features conformance --test conformance
+```
+
+JSON support is development-only and does not add a runtime dependency to the compiler library. CI checks out the recorded specification revision before running the suite.
+
 ## Architecture
 
 - [`docs/decisions/0001-build-a-portable-rust-compiler-core.md`](./docs/decisions/0001-build-a-portable-rust-compiler-core.md)
 - [`docs/decisions/0002-separate-syntax-ast-from-normalized-ir.md`](./docs/decisions/0002-separate-syntax-ast-from-normalized-ir.md)
 - [`docs/decisions/0003-use-a-handwritten-parser.md`](./docs/decisions/0003-use-a-handwritten-parser.md)
+- [`docs/decisions/0004-consume-a-pinned-conformance-suite.md`](./docs/decisions/0004-consume-a-pinned-conformance-suite.md)
 - [`docs/specs/compiler-frontend.md`](./docs/specs/compiler-frontend.md)
 
 ## License

docs/decisions/0004-consume-a-pinned-conformance-suite.md

@@ -0,0 +1,61 @@
+# ADR-0004: Consume a Pinned Canonical Conformance Suite
+
+## Status
+
+Accepted
+
+## Date
+
+2026-09-02
+
+## Context
+
+`stack-sh/specification` now owns portable normalized IR, diagnostic schemas, and implementation-independent conformance fixtures. The Rust compiler must prove that its native IR and diagnostics map to those contracts without copying canonical fixture data into this repository.
+
+Tracking the specification default branch implicitly would make compiler CI non-reproducible. A specification change could break an unchanged compiler commit, and passing CI would no longer identify the language revision actually supported. Vendoring fixtures would avoid network access but would create two sources of truth.
+
+The compiler core is intentionally dependency-free. JSON is needed only by the conformance adapter and must not become part of source parsing or runtime compilation.
+
+## Decision
+
+Record the exact supported specification commit in `tests/specification-revision`. Compiler CI checks out that immutable revision and passes its path explicitly to a feature-gated integration test through `STACK_SPECIFICATION_DIR`.
+
+The conformance test discovers canonical valid and invalid case directories. It maps native Rust IR and diagnostics to semantic JSON values and compares them with expected documents. Diagnostic comparison includes code, severity, and end-exclusive source range but excludes human-readable message, help, and related-information wording.
+
+`serde_json` is a development-only dependency. The library keeps no runtime dependencies and exposes no JSON-specific public API. The conformance test is gated by the `conformance` Cargo feature so a normal package checkout can run `cargo test` without fetching another repository.
+
+When the compiler adopts a newer language revision, the fixture runner must pass locally before `tests/specification-revision` changes. Once the specification publishes stable releases, a release commit may replace draft commit pins while retaining exact reproducibility.
+
+## Alternatives Considered
+
+### Copy fixtures into the compiler repository
+
+- Pros: Tests are self-contained and offline.
+- Cons: Expected data can drift from the canonical specification.
+- Rejected: Language fixtures must have one owner.
+
+### Track `stack-sh/specification` main automatically
+
+- Pros: Immediate detection of specification changes.
+- Cons: An unchanged compiler revision can begin failing without any local change.
+- Rejected: Compatibility claims must identify an exact tested revision.
+
+### Add serialization dependencies to the compiler library
+
+- Pros: Downstream tools could request JSON directly from the core crate.
+- Cons: Expands the public API and runtime dependency surface before WASM and package boundaries are designed.
+- Rejected: A test-only adapter proves the contract without committing to a runtime transport API.
+
+### Use a Git submodule
+
+- Pros: Git records an exact external revision.
+- Cons: Adds clone and contributor workflow complexity for a test suite that normal builds do not require.
+- Rejected: A revision file and explicit CI checkout provide the same reproducibility with less repository coupling.
+
+## Consequences
+
+- Compiler CI states exactly which public specification revision it supports.
+- Canonical fixtures remain owned by one repository.
+- Conformance runs require a specification checkout and explicit environment variable.
+- Updating specification support is a deliberate reviewed change.
+- The compiler lockfile includes development-only JSON dependencies, while the built library remains dependency-free.

docs/specs/compiler-frontend.md

@@ -35,6 +35,8 @@ src/validation/     Focused validation unit tests
 src/ir.rs           Renderer-independent normalized model
 src/lib.rs          Public parse and compile APIs
 tests/              Public API and conformance-oriented tests
+tests/specification-revision
+                    Exact canonical specification revision tested by CI
 docs/decisions/     Architectural decisions
 ```
 
@@ -71,7 +73,7 @@ match operator {
 
 - Unit tests cover lexer escapes, positions, parser productions, defaults, and each implemented diagnostic.
 - Integration tests exercise public `parse` and `compile` APIs.
-- Valid fixtures mirror the canonical specification examples.
+- Feature-gated integration tests execute the canonical conformance suite from the recorded specification revision.
 - Invalid cases assert stable diagnostic codes rather than entire prose messages.
 - Library unit-test line, function, and region coverage must each remain at or above 95 percent.
 - Every compiler change must pass formatting, tests, coverage, Clippy, and documentation builds.
@@ -102,7 +104,7 @@ match operator {
 
 ## Initial Success Criteria
 
-- All four canonical Stack examples parse and compile.
+- All valid cases in the pinned canonical conformance suite parse and compile.
 - Specification-defined defaults appear in normalized IR.
 - UTF-8, BOM, invalid string, syntax, name-resolution, semantic, layout-scope, and complexity diagnostics use their assigned codes.
 - Independent semantic errors are collected in one validation pass.
@@ -117,4 +119,4 @@ match operator {
 - Theme and icon resolution
 - Layout and renderer integration
 - Multi-error syntax recovery
-- Stable serialization schema and package versioning
+- Native Rust API stabilization and package versioning

tests/compiler.rs

@@ -1,50 +1,20 @@
 use stack_compiler::{compile, compile_bytes, diagnostic::Severity, ir};
 
-const VALID_EXAMPLES: &[(&str, &str)] = &[
-    ("minimal", include_str!("fixtures/valid/01-minimal.stack")),
-    (
-        "node semantics",
-        include_str!("fixtures/valid/02-node-semantics.stack"),
-    ),
-    (
-        "groups and layout",
-        include_str!("fixtures/valid/03-groups-and-layout.stack"),
-    ),
-    (
-        "commerce platform",
-        include_str!("fixtures/valid/04-commerce-platform.stack"),
-    ),
-];
-
-#[test]
-fn canonical_examples_compile_without_diagnostics() {
-    for (name, source) in VALID_EXAMPLES {
-        let output = compile(source);
-        assert!(
-            output.diagnostics.is_empty(),
-            "{name}: {:?}",
-            output.diagnostics
-        );
-        assert!(output.diagram.is_some(), "{name}");
-    }
-}
-
 #[test]
-fn canonical_commerce_example_has_expected_normalized_shape() {
-    let output = compile(VALID_EXAMPLES[3].1);
+fn public_api_applies_defaults_to_a_valid_document() {
+    let output = compile("stack 1.0 diagram \"API\" { node api \"API\" }");
     assert!(output.diagram.is_some(), "{:?}", output.diagnostics);
     let Some(diagram) = output.diagram else {
         return;
     };
 
     assert_eq!(diagram.theme_id, "default");
-    assert_eq!(diagram.nodes.len(), 13);
-    assert_eq!(diagram.groups.len(), 5);
-    assert_eq!(diagram.edges.len(), 12);
-    assert_eq!(
-        diagram.layout.as_ref().and_then(|layout| layout.direction),
-        Some(ir::Direction::Right),
-    );
+    assert_eq!(diagram.nodes.len(), 1);
+    let Some(node) = diagram.nodes.first() else {
+        return;
+    };
+    assert_eq!(node.kind, ir::NodeKind::Service);
+    assert!(diagram.edges.is_empty());
 }
 
 #[test]