Add backend parity verifier

Author: code5717

.github/workflows/ci.yml

@@ -57,6 +57,9 @@ jobs:
       - name: Verify examples through C
         run: uv run python scripts/verify_examples_e2e_c.py
 
+      - name: Verify backend parity
+        run: uv run python scripts/verify_backend_parity.py
+
       - name: Build debug artifacts
         run: uv run python scripts/build_examples.py --profile debug --backend both --clean
 

CHANGELOG.md

@@ -27,6 +27,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   returns, linked-list traversal, iterative binary-tree traversal, and string
   utilities; tightened example catalog copy where language support is still
   status-only.
+- Added a selected Zig/C backend parity verifier that compiles, builds, runs,
+  and compares non-example smoke programs across both native backends.
 
 ## [0.3.0] - 2026-05-07
 
@@ -48,7 +50,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Expanded `scripts/verify_error_stages.py` and `test/test_error_stage_matrix.py` so deferred semantic errors are checked across all semantic-capable modes and human/JSON output.
 
 - **Labeled Loops** (both backends)
-  - `outer: while`, `outer: for`, `outer: for-in` with `break outer` / `continue outer`.
+  - `@outer while`, `@outer for`, `@outer for-in` with `break outer` / `continue outer`.
+  - The old `outer: for` spelling is rejected so `name:` remains reserved for typed bindings, fields, and case-like syntax.
   - Zig backend emits native labeled loops; C backend lowers to goto-based control flow.
 
 - **Slice Expressions in C Backend**
@@ -357,7 +360,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - Inline type sets: `fn($T: @type_set(i32, i64), x: T) T`
     - AST stores constraint on GENERIC_PARAM nodes
   - **Labeled Loops**: Implemented for all loop forms (while, for, for-in, indexed for-in)
-    - Syntax: `outer: for i := 0; i < 10; i += 1 { break outer }`
+    - Syntax: `@outer for i := 0; i < 10; i += 1 { break outer }`
     - Zig backend emits native labeled loops (`label: while ...`, `break :label`)
     - C backend lowers to goto-based control flow with unique labels
   - **Builtin Intrinsics**: All `@function` intrinsics now parse correctly

MISSING_FEATURES.md

@@ -8,7 +8,7 @@
 
 ## Recently Completed (Language Core)
 
-1. **Labeled loops** — `outer: while`, `outer: for`, `outer: for-in` with `break outer` / `continue outer` in both Zig and C backends.
+1. **Labeled loops** — `@outer while`, `@outer for`, `@outer for-in` with `break outer` / `continue outer` in both Zig and C backends.
 2. **Slice expressions in C backend** — `arr[1..4]` on arrays and slices, including indexing and `for-in` over slices.
 3. **Type checker: slice and index validation** — `visit_slice_expr` returns `SliceType`; `visit_index_expr` rejects non-integer indices.
 4. `match` expressions are type-checked and participate in expression typing.
@@ -27,7 +27,7 @@
 13. Constant folding covers arithmetic, boolean logic, literal comparisons, and integer bitwise expressions.
 14. Installed CLI entrypoint (`a7`) is wired through `pyproject.toml`.
 15. Debug/release example artifact verification is available through `scripts/build_examples.py`.
-16. `run_all_tests.sh` includes C backend verification, both example E2E verifiers, debug/release artifact builds, the error-stage matrix, docs style checks, and full pytest.
+16. `run_all_tests.sh` includes C backend verification, both example E2E verifiers, selected Zig/C parity smoke checks, debug/release artifact builds, the error-stage matrix, docs style checks, and full pytest.
 17. Local file-based imports now fail closed during semantic analysis instead of swallowing module loading failures.
 18. Zig unsupported expression fallbacks now fail as compiler-side codegen errors instead of generated `@compileError` expressions.
 19. `fall` now fails closed with a semantic error instead of being ignored or reaching backend output.

README.md

@@ -74,6 +74,7 @@ PYTHONPATH=. uv run pytest test/test_tokenizer.py  # Specific test file
 PYTHONPATH=. uv run pytest -k "generic" -v         # Targeted tests
 uv run python scripts/verify_examples_e2e.py       # Compile/build/run + output checks for all examples
 uv run python scripts/verify_examples_e2e_c.py     # Same flow via C backend + zig cc
+uv run python scripts/verify_backend_parity.py     # Selected Zig/C differential smoke checks
 uv run python scripts/verify_error_stages.py       # Error-stage audit across modes and formats
 uv run python scripts/build_examples.py --profile debug --backend both --clean
 uv run python scripts/build_examples.py --profile release --backend both --clean
@@ -162,6 +163,8 @@ Use fixed-width integers such as `i32`, `i64`, `u32`, or `u64` when the data its
 - Example end-to-end verification is available for both backends:
   - `uv run python scripts/verify_examples_e2e.py`
   - `uv run python scripts/verify_examples_e2e_c.py`
+- Selected Zig/C differential smoke checks are available through
+  `scripts/verify_backend_parity.py`.
 - Debug/release artifact verification is available through `scripts/build_examples.py`.
 - Tag releases publish package artifacts through PyPI Trusted Publishing once the PyPI project trusted publisher is configured.
 - Parser covers the implemented language surface, but spec/implementation gaps remain tracked in `MISSING_FEATURES.md`.

RELEASE.md

@@ -73,6 +73,7 @@ uvx pip-audit --strict
 - Zig and C backend tests
 - Zig example compile/build/run/output verification
 - C example compile/build/run/output verification
+- selected Zig/C backend parity verification beyond examples
 - debug artifact build verification for Zig and C
 - release artifact build verification for Zig and C
 - CLI error-stage matrix verification

RELEASE_READINESS_REVIEW.md

@@ -32,6 +32,7 @@ not factually provable from local tests alone.
 - `PYTHONPATH=. uv run pytest test/test_release_tooling.py -q`
 - `uv run python scripts/build_examples.py --profile debug --backend both --clean`
 - `uv run python scripts/build_examples.py --profile release --backend both --clean`
+- `uv run python scripts/verify_backend_parity.py`
 - `./run_all_tests.sh`
 - `uv build`
 - `uvx pip-audit --strict`
@@ -41,10 +42,11 @@ not factually provable from local tests alone.
 - `cd site && npm run build`
 - built wheel installed into a temporary virtualenv and invoked as `a7`
 - `git diff --check`
-- hosted CI run `25519819833` passed for commit `13bf369`:
+- hosted CI run `25520030936` passed for commit `452d176` before the backend
+  parity verifier was added:
   docs, pytest, dependency audits, error-stage verification, Zig and C example
   verification, debug artifacts, release artifacts, and package build
-- hosted Deploy Docs run `25519819834` passed for commit `13bf369`
+- hosted Deploy Docs run `25520030885` passed for commit `452d176`
 - manual release workflow dispatch passed on `master` after the PyPI publish
   dependency update; run `25517785179` uploaded
   `python-package-distributions` artifact `6864726540` and `release-bundles`
@@ -60,7 +62,8 @@ not factually provable from local tests alone.
 - `scripts/build_examples.py` builds and verifies debug/release artifacts for
   both backends.
 - `run_all_tests.sh` now covers C backend tests, C E2E, error-stage audit,
-  debug/release artifact builds, docs style, and full pytest.
+  selected Zig/C backend parity checks, debug/release artifact builds, docs
+  style, and full pytest.
 - GitHub CI now runs Python tests, backend verifiers, artifact builds, package
   build, dependency audits, secret scanning, docs style, docs lint, and docs
   build.
@@ -102,6 +105,8 @@ not factually provable from local tests alone.
 - Semantic validation now rejects direct and mutual recursion and avoids false
   recursion reports when a local function-pointer variable shadows a top-level
   function name.
+- Selected non-example programs now run through both Zig and C backends and
+  compare runtime output.
 
 ## Residual Risks
 
@@ -111,7 +116,8 @@ not factually provable from local tests alone.
 - Full ownership/lifetime safety is not implemented.
 - Built-in stdlib imports are virtual and still need unification with file-based
   module semantics.
-- Backend parity is verified for examples, not all possible source programs.
+- Backend parity is verified for examples and selected differential smoke
+  programs, not all possible source programs.
 - Tag-based PyPI publishing is wired, but `a7-py` is not yet a public PyPI
   project and still needs matching trusted-publisher configuration before the
   first real publish.

SECURITY.md

@@ -27,8 +27,9 @@ uv run python scripts/check_no_secrets.py
 ```
 
 The full gate includes parser/tokenizer tests, semantic tests, Zig and C backend
-tests, example runtime verification, debug/release artifact builds, error-stage
-checks, docs style checks, and full pytest.
+tests, example runtime verification, selected Zig/C backend parity checks,
+debug/release artifact builds, error-stage checks, docs style checks, and full
+pytest.
 
 ## Known Security-Relevant Limitations
 

TODO.md

@@ -214,7 +214,7 @@ These are entire subsystems. Each needs a design decision before implementation
 
 - [x] Add parser coverage for labeled `continue`, nested labeled loops, and malformed labels.
   Files: `test/test_parser_combinatorial.py`, `test/test_parser_integration.py`
-  Notes: parser combinatorial tests now assert labeled `continue`, nested `for`/`while` labels, labeled `for-in` forms, and malformed non-loop labels.
+  Notes: parser combinatorial tests now assert `@label` loop prefixes, labeled `continue`, nested `for`/`while` labels, labeled `for-in` forms, and malformed or old `label:` labels.
 
 - [x] Add Zig regression coverage for labeled `for-in` and indexed `for-in`.
   Files: `test/test_codegen_zig.py`
@@ -245,7 +245,7 @@ These are entire subsystems. Each needs a design decision before implementation
 
 - [x] Add CI coverage for release-oriented gates.
   Files: `.github/workflows/ci.yml`, `.github/workflows/deploy-docs.yml`, `site/package-lock.json`
-  Notes: CI now installs Zig, runs pytest, dependency audits, error-stage checks, both backend E2E verifiers, debug/release artifact builds, package build, docs style, docs lint, and docs build. Pages deploy now uses `npm ci`.
+  Notes: CI now installs Zig, runs pytest, dependency audits, error-stage checks, both backend E2E verifiers, selected backend parity checks, debug/release artifact builds, package build, docs style, docs lint, and docs build. Pages deploy now uses `npm ci`.
 
 - [x] Add dependency-audit checks for release readiness.
   Files: `.github/workflows/ci.yml`, `RELEASE.md`, `SECURITY.md`

docs/SPEC.md

@@ -617,8 +617,8 @@ break
 // Continue to next iteration
 continue
 
-// Break/continue with label
-outer: for i := 0; i < 10; i += 1 {
+// Break/continue with loop label
+@outer for i := 0; i < 10; i += 1 {
     for j := 0; j < 10; j += 1 {
         if condition {
             break outer
@@ -627,6 +627,10 @@ outer: for i := 0; i < 10; i += 1 {
 }
 ```
 
+Loop labels use `@name` directly before a loop statement. The old
+`name: for ...` spelling is rejected because `name:` is reserved for typed
+bindings, fields, and case-like syntax.
+
 Semantic validation reports unreachable statements that appear later in the same block after `ret`, a valid `break` or `continue`, `fall`, or an `if`/`match` statement whose branches all terminate.
 
 ---
@@ -1905,8 +1909,8 @@ break
 // Continue to next iteration
 continue
 
-// Break/continue with label
-outer: for i := 0; i < 10; i += 1 {
+// Break/continue with loop label
+@outer for i := 0; i < 10; i += 1 {
     for j := 0; j < 10; j += 1 {
         if condition {
             break outer
@@ -1915,6 +1919,10 @@ outer: for i := 0; i < 10; i += 1 {
 }
 ```
 
+Loop labels use `@name` directly before a loop statement. The old
+`name: for ...` spelling is rejected because `name:` is reserved for typed
+bindings, fields, and case-like syntax.
+
 Semantic validation reports unreachable statements that appear later in the same block after `ret`, a valid `break` or `continue`, `fall`, or an `if`/`match` statement whose branches all terminate.
 
 ---
@@ -2801,12 +2809,16 @@ statement =
     | block_stmt
     | if_stmt
     | match_stmt
+    | loop_label loop_stmt
     | for_stmt
     | while_stmt
     | jump_stmt
     | defer_stmt
     | var_decl
 
+loop_label = "@" identifier
+loop_stmt = for_stmt | while_stmt
+
 jump_stmt = 
     | "ret" expr?
     | "break" identifier?

examples/036_control_flow_edges.a7

@@ -15,15 +15,15 @@ main :: fn() {
     io.println("slice total = {}", slice_total)
 
     break_total := 0
-    outer_break: for value in numbers {
+    @outer_break for value in numbers {
         if value == 7 {
             break outer_break
         }
         break_total += value
     }
 
     continue_total := 0
-    outer_continue: for value in numbers {
+    @outer_continue for value in numbers {
         if value == 7 {
             continue outer_continue
         }