Expand example and parity coverage

Author: code5717

AGENT.md

@@ -17,12 +17,15 @@ Compatibility pointer for tools that look for a singular `AGENT.md`.
 
 - Run the compiler: `uv run a7 <args>` (or `uv run python main.py <args>`).
   The Python package lives at `a7/`; the entrypoint is `a7.cli:main`.
-- Full release gate: `./run_all_tests.sh`
+- Full release gate: `./run_all_tests.sh` (covers example E2E for **both**
+  Zig and C backends and the 24-case backend parity sweep).
 - Debug artifacts:
   `uv run python scripts/build_examples.py --profile debug --backend both --clean`
 - Release artifacts:
   `uv run python scripts/build_examples.py --profile release --backend both --clean`
-- Backend parity: `uv run python scripts/verify_backend_parity.py`
+- Backend parity (24 cases — generic constraints, generic structs/functions,
+  explicit enum discriminants, stdlib math, operator edge cases):
+  `uv run python scripts/verify_backend_parity.py`
 - Package build: `uv build`
 - Wheel install smoke test (clean venv):
   `uv run python scripts/verify_wheel_install.py` (CI/release uses
@@ -48,6 +51,13 @@ Compatibility pointer for tools that look for a singular `AGENT.md`.
 - Keep `site/public/llms.txt`, `site/public/llms-full.txt`, and
   `site/public/docs/` aligned when site navigation, release commands, CLI
   behavior, or public docs structure changes.
+- Docs must distinguish currently supported features from parsed-only or
+  reserved syntax — notably variadics, intrinsics other than `@type_set`,
+  and multiple-declaration/destructuring binding syntax. Do not present
+  parsed-only forms as working.
+- Package-registry publishing (a7 package index, registry client, lockfile
+  resolution) is **out of scope**; reject related additions to code, docs,
+  TODO, or MISSING.
 
 See `AGENTS.md` for the full workflow, post-change checklist, and security
 caveats.

CHANGELOG.md

@@ -8,6 +8,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Changed
+- `examples/014_generics.a7` now runs real generic functions and generic struct
+  instances in both backends; backend parity coverage now also includes type-set
+  generic constraints, explicit enum discriminants, stdlib math mappings, and
+  edge operator assignments/comparisons.
+- README, SPEC, site, and public Markdown docs now distinguish current features
+  from parsed-only or reserved syntax such as variadics, non-`@type_set`
+  intrinsics, and multiple declaration/destructuring syntax.
 - Generic struct literals now retain concrete instance types during semantic
   analysis, Zig emits generic struct instances with explicit type arguments,
   and the C backend monomorphizes used generic struct instances before codegen.

CLAUDE.md

@@ -22,6 +22,9 @@ from a fresh checkout.
   `uv run python scripts/build_examples.py --profile debug --backend both --clean`
 - Release artifact verification:
   `uv run python scripts/build_examples.py --profile release --backend both --clean`
+- Backend parity (24 cases — generic constraints, generic structs/functions,
+  explicit enum discriminants, stdlib math, operator edge cases):
+  `uv run python scripts/verify_backend_parity.py`
 - Full local release gate: `./run_all_tests.sh`
 - Package build: `uv build`
 - Wheel install smoke test (clean venv):
@@ -32,10 +35,14 @@ from a fresh checkout.
   then check `/a7-py/llms.txt`, `/a7-py/llms-full.txt`, and
   `/a7-py/docs/index.md`.
 
+Examples are verified end-to-end against **both** the Zig and C backends —
+the Zig and C example E2E scripts must both pass for any change to
+`examples/`, codegen, or runtime behavior.
+
 `run_all_tests.sh` is the single source of truth for the full gate (pytest,
-parser/semantic/codegen tests, example e2e for Zig and C, backend parity,
-debug + release artifacts, error-stage matrix, docs style, secrets check).
-Run it before reporting a non-trivial task as done.
+parser/semantic/codegen tests, example E2E for Zig and C, 24-case backend
+parity, debug + release artifacts, error-stage matrix, docs style, secrets
+check). Run it before reporting a non-trivial task as done.
 
 The public docs site also ships Markdown entry points for agent tooling under
 `site/public/llms.txt`, `site/public/llms-full.txt`, and `site/public/docs/`.
@@ -65,6 +72,28 @@ navigation when docs structure changes.
 - This rule applies to A7 source only. Compiler internals already use
   iterative AST traversals; keep them that way.
 
+## Docs Accuracy
+
+User-facing docs (`README.md`, `docs/SPEC.md`, `MISSING_FEATURES.md`,
+`site/public/llms*.txt`, `site/public/docs/`) must clearly distinguish
+**currently supported** features from syntax that is only **parsed or
+reserved** but not yet implemented. In particular, mark these as
+parsed-only/reserved rather than working features:
+
+- variadic parameters
+- intrinsics other than `@type_set`
+- multiple-declaration and destructuring binding syntax
+
+Adding examples, snippets, or claims that imply the parsed-only forms work
+end-to-end is treated the same as a doc/code drift bug.
+
+## Out of Scope
+
+- Package-registry publishing (a7 package index, registry client, lockfile
+  resolution, etc.) is **out of scope** for this repository. Do not add
+  features, examples, docs, or TODO/MISSING entries that assume a registry;
+  treat related requests as out-of-scope and flag them.
+
 ## Post-Change Checklist
 
 When language features, backends, or user-facing behavior change, update:

MISSING_FEATURES.md

@@ -55,6 +55,18 @@
 
 ## Remaining Language-First Gaps
 
+0. **Spec-only syntax and parsed-only features**
+   - Variadic parameters are parsed and partially type-checked, but runtime
+     iteration and backend ABI lowering are not implemented.
+   - Multiple return values / destructuring (`a, b, c := 1, 2, 3`) are planned
+     syntax, not current parser support.
+   - `@type_set(...)` is implemented for generic constraints. Other `@...`
+     intrinsic names such as `@size_of`, `@align_of`, `@type_id`,
+     `@type_name`, `@unreachable`, `@likely`, and `@unlikely` are reserved or
+     tokenized but not semantically resolved/lowered yet.
+   - Array/tensor programming syntax, performance annotations, and control-flow
+     narrowing remain tracked backlog items in `TODO.md`.
+
 1. **Advanced match diagnostics**
    - Exact duplicate bool, enum, and scalar literal case patterns are diagnosed.
    - Wildcard-first and fully covered bool/enum cases make later case patterns and else branches unreachable.

README.md

@@ -159,7 +159,7 @@ Use fixed-width integers such as `i32`, `i64`, `u32`, or `u64` when the data its
 
 ## What Works
 
-- **Types**: Primitives, arrays, slices, pointers, generics, raw and aliased function types, inline structs
+- **Types**: Primitives, arrays, slices, pointers, generics, raw and aliased function types, inline struct return values
 - **Declarations**: Functions, structs, enums, unions, variables, constants, type aliases
 - **Control Flow**: if/else, while, for loops, for-in, labeled loops with break/continue, match statements, defer
 - **Function Rules**: Direct and mutual recursion are semantic errors
@@ -206,7 +206,7 @@ Use fixed-width integers such as `i32`, `i64`, `u32`, or `u64` when the data its
 
 ```bash
 cd site
-npm install
+npm ci
 npm run dev
 ```
 

TODO.md

@@ -183,8 +183,8 @@ Features that are spec'd and partially implemented, or missing from one backend.
 
 ### Unimplemented Spec Features
 
-- [ ] Variadic functions (spec §6.5).
-  Notes: spec'd but not parsed or implemented.
+- [ ] Variadic functions (spec §6.6).
+  Notes: parsed and partially type-checked, but runtime iteration and backend ABI lowering are not implemented.
 
 - [ ] Multiple return values / destructuring (`a, b, c := 1, 2, 3`).
   Notes: spec'd in §4.1, not parsed.

docs/SPEC.md

@@ -416,9 +416,9 @@ buffer: [1024]u8
 age: i32 = 25    // Explicit type
 name := "John"   // Inferred as string
 
-// Multiple declarations
-a, b, c: i32 = 1, 2, 3
-x, y := 10, 20
+// Multiple declaration/destructuring syntax is planned, not current:
+// a, b, c: i32 = 1, 2, 3
+// x, y := 10, 20
 ```
 
 ### 4.2 Declaration Rules
@@ -814,8 +814,12 @@ v.normalize()         // Modifies v through pointer
 
 ### 6.6 Variadic Functions
 
+> **Implementation Status**: Variadic parameter syntax is parsed and partially
+> type-checked for declarations, but runtime iteration and ABI lowering are not
+> implemented. Do not treat variadic functions as runnable current syntax.
+
 ```a7
-// Variadic parameters must be last
+// Planned shape: variadic parameters must be last
 sum :: fn(values: ..i32) i32 {
     total := 0
     for val in values {
@@ -840,7 +844,7 @@ A7 uses a simple generic system where type parameters are compile-time constants
 - `$T` is used **inline** within type expressions to declare and reference generic types
 - The same `$T` syntax is used everywhere - no separate declaration vs reference syntax
 - Generic types are inferred from usage context at compile time
-- Constraints are a semantic analysis feature (future)
+- Constraints are a semantic analysis feature for declared generic functions
 
 **Generic Type Parameter Syntax Rules:**
 - Must start with `$` followed immediately by a letter (a-z, A-Z)
@@ -874,7 +878,7 @@ pair :: fn(first: $T, second: $U) {
     y := second
 }
 
-// Generic with array parameter
+// Planned broader composite propagation; not backend-complete yet.
 first :: fn(arr: []$T) $T {
     ret arr[0]
 }
@@ -1489,15 +1493,15 @@ Planned, not implemented as public stdlib modules yet:
 
 ### 10.4 Visibility Rules
 
-- `public` modifier only applies to **global/top-level declarations**:
+- `pub` modifier only applies to **global/top-level declarations**:
   - Global functions
   - Global variables and constants
   - Type declarations (struct, enum, union)
-- `public` items are exported from the file/module
-- Non-public items are file-private
+- `pub` items are exported from the file/module
+- Non-`pub` items are file-private
 - No protected/internal visibility
-- **Struct fields are always file-private** (cannot be marked `public`)
-- Function parameters and local variables cannot be marked `public`
+- **Struct fields are always file-private** (cannot be marked `pub`)
+- Function parameters and local variables cannot be marked `pub`
 
 ---
 
@@ -1510,7 +1514,12 @@ These functions are handled specially by the compiler and use the `@` prefix:
 ```a7
 // Type sets
 @type_set :: fn(types: ..type) TypeSet     // Create type set
+```
 
+The tokenizer/parser reserve additional intrinsic spellings, but they are not
+semantically resolved or backend-lowered yet:
+
+```a7
 // Memory intrinsics
 @size_of :: fn($T: type) usize             // Size in bytes
 @align_of :: fn($T: type) usize            // Alignment requirement

examples/011_memory.a7

@@ -10,6 +10,7 @@ main :: fn() {
         io.println("allocation failed")
         ret
     }
+    defer del value_ptr
 
     value_ptr.val = 42
     io.println("heap value = {}", value_ptr.val)

examples/014_generics.a7

@@ -1,13 +1,32 @@
-// Generics status note
-//
-// Parser and semantic tests cover generic functions, type parameters, and
-// constraints. The runnable example stays explicit because release artifacts
-// must pass both Zig and C backends, and C generic lowering is still tracked.
+// Generic functions and structs
 
 io :: import "std/io"
 
+identity($T) :: fn(value: $T) $T {
+    ret value
+}
+
+Box :: struct {
+    value: $T
+}
+
+Pair($A, $B) :: struct {
+    first: $A
+    second: $B
+}
+
 main :: fn() {
-    io.println("=== Generics Status ===")
-    io.println("Generic functions are validated in semantic tests.")
-    io.println("C backend generic lowering is tracked before runtime examples.")
+    io.println("=== Generics ===")
+
+    number := identity(7)
+    word := identity("ok")
+    boxed: Box(i32) = Box(i32){value: number}
+    nested: Box(Box(i32)) = Box(Box(i32)){value: Box(i32){value: 5}}
+    pair: Pair(i32, string) = Pair(i32, string){first: boxed.value, second: word}
+
+    io.println("identity number = {}", number)
+    io.println("identity string = {}", word)
+    io.println("boxed = {}", boxed.value)
+    io.println("nested boxed = {}", nested.value.value)
+    io.println("pair = {} {}", pair.first, pair.second)
 }

scripts/verify_backend_parity.py

@@ -327,6 +327,17 @@
 main :: fn() {
     io.println("generic = {} {}", identity(7), identity("ok"))
 }
+''',
+    "generic_constraint_calls": r'''
+io :: import "std/io"
+
+smaller($T: Numeric) :: fn(a: $T, b: $T) $T {
+    ret if a < b { a } else { b }
+}
+
+main :: fn() {
+    io.println("generic constraint = {} {}", smaller(7, 3), smaller(2.5, 4.5))
+}
 ''',
     "enum_match_expression": r'''
 io :: import "std/io"
@@ -350,6 +361,25 @@
     io.println("enum busy = {}", score(State.Busy))
     io.println("enum done = {}", score(State.Done))
 }
+''',
+    "enum_explicit_discriminants": r'''
+io :: import "std/io"
+
+Status :: enum {
+    Ok = 200
+    NotFound = 404
+    Error = 500
+}
+
+main :: fn() {
+    code: Status = Status.NotFound
+    label := match code {
+        case Status.Ok: "ok"
+        case Status.NotFound: "missing"
+        case Status.Error: "error"
+    }
+    io.println("enum explicit = {}", label)
+}
 ''',
     "heap_struct_roundtrip": r'''
 io :: import "std/io"
@@ -395,6 +425,29 @@
     }
     io.println("cube = {}", total)
 }
+''',
+    "operator_edge_surface": r'''
+io :: import "std/io"
+
+main :: fn() {
+    x := 12
+    x &= 10
+    x |= 1
+    x ^= 3
+    x <<= 2
+    x >>= 1
+    y := ~x
+    ok := (x != 0) and (x <= 20) and (x >= 1)
+    io.println("ops edge = {} {} {}", x, y, ok)
+}
+''',
+    "stdlib_math_runtime": r'''
+io :: import "std/io"
+math :: import "std/math"
+
+main :: fn() {
+    io.println("math = {} {} {} {}", math.floor(3.8), math.ceil(3.2), math.min(7.0, 3.0), math.max(7.0, 3.0))
+}
 ''',
 }