Add beta readiness hardening: multi-error CLI diagnostics, sanitizer and warning-clean CI, and beta/ABI/security docs.

Cod-e-Codes · Cod-e-Codes · commit 931507721df0 · 2026-06-25T18:00:33.000-04:00
Fix test_runner ion-build path resolution on Windows and fail harness PARTIAL mismatches instead of counting them as passes.
diff --git a/.cursor/skills/adding-ion-features/SKILL.md b/.cursor/skills/adding-ion-features/SKILL.md
@@ -70,9 +70,9 @@ Touch this for imports, multi-file mode, or qualified names - not only when edit
 
 ### Type checker (`src/tc/`)
 
-See `mod.rs`, `ownership.rs`, `builtins.rs`, `types.rs`. LSP uses `check_program_collecting` for multiple diagnostics; CLI uses `check_program` (first error only).
+See `mod.rs`, `ownership.rs`, `builtins.rs`, `types.rs`. LSP and CLI use `check_program_collecting` for multiple diagnostics via `tc::format_type_errors`.
 
-Critical checks to preserve. Patterns below match **CLI stderr** (`Type check error: UseAfterMove { ... }` via `{:?}`). The LSP formats the same errors differently (e.g. "Use after move: x") - see `ion-lsp-vscode` skill; do not use CLI grep patterns to validate LSP diagnostics.
+Critical checks to preserve. Patterns below match **CLI stderr** (e.g. `UseAfterMove` appears in `Type check failed with N error(s):` output). The LSP formats the same errors differently (e.g. "Use after move: x") - see `ion-lsp-vscode` skill; do not use CLI grep patterns to validate LSP diagnostics.
 
 | Check | CLI stderr pattern |
 |-------|----------------|
diff --git a/.cursor/skills/ion-integration-tests/SKILL.md b/.cursor/skills/ion-integration-tests/SKILL.md
@@ -54,6 +54,8 @@ Environment overrides:
 ```bash
 COMPILER=../target/debug/ion-compiler ION_BUILD=../target/debug/ion-build CC=clang ./test_runner.sh
 RUNTIME_OBJ=/tmp/ion_runtime.o ./test_runner.sh
+CFLAGS="-Wall -Wextra -Werror" RUNTIME_OBJ=.ion_test_runtime_werror.o ./test_runner.sh
+CFLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer" LDFLAGS="-fsanitize=address,undefined" ./test_runner.sh
 ```
 
 **Harness link step:** On startup, `test_runner.sh` precompiles `runtime/ion_runtime.c` once to `RUNTIME_OBJ` (default `.ion_test_runtime.o`) and links that object for each `run` test and `test_multifile`. This path uses `ion-compiler` and `gcc` directly, not `ion-build`. Example programs under `examples/` use `ion-build` per README.
@@ -132,7 +134,7 @@ The harness greps **compiler CLI stderr** for the pattern (not LSP diagnostic te
 
 ### `test_error` PARTIAL pass trap
 
-If compilation fails but the grep pattern does **not** match, the harness prints **PARTIAL** and still increments `pass_count`. A wrong pattern looks like a pass - always verify the pattern against actual CLI output and confirm the harness prints **PASS**, not PARTIAL.
+If compilation fails but the grep pattern does **not** match, the harness prints **PARTIAL** and increments `fail_count`. A wrong pattern is a harness failure - always verify the pattern against actual CLI output and confirm the harness prints **PASS**, not PARTIAL.
 
 ## Test file conventions
 
diff --git a/.cursor/skills/ion-lang/SKILL.md b/.cursor/skills/ion-lang/SKILL.md
@@ -18,9 +18,12 @@ Ion is a move-only, no-GC systems language transpiled to C. This skill orients y
 | Resource | Purpose |
 |----------|---------|
 | [ION_SPEC.md](../../../ION_SPEC.md) | Authoritative language semantics and grammar |
+| [docs/BETA.md](../../../docs/BETA.md) | Beta subset, compatibility policy, platform support |
+| [docs/ABI.md](../../../docs/ABI.md) | Runtime ABI notes for generated C and stdlib types |
 | [README.md](../../../README.md) | Build, run, project structure |
 | [CONTRIBUTING.md](../../../CONTRIBUTING.md) | Build, test, lint, and PR expectations |
 | [CHANGELOG.md](../../../CHANGELOG.md) | Release notes by month |
+| [SECURITY.md](../../../SECURITY.md) | Security reporting scope and policy |
 | [tests/README.md](../../../tests/README.md) | Integration test catalog |
 
 **Compiler pipeline** (see [references/compiler-pipeline.md](references/compiler-pipeline.md)):
diff --git a/.cursor/skills/ion-lang/references/compiler-pipeline.md b/.cursor/skills/ion-lang/references/compiler-pipeline.md
@@ -46,7 +46,7 @@
 - `Send` checking for channels and `spawn`
 - Module visibility (`pub`), generics, method resolution
 - Errors via `TypeCheckError` enum
-- CLI: `check_program` returns first error; LSP: `check_program_collecting` gathers multiple independent errors
+- CLI and LSP: `check_program_collecting` gathers multiple independent errors; CLI prints them via `tc::format_type_errors`
 
 ### 6. IR (`src/ir/mod.rs`)
 
diff --git a/.cursor/skills/ion-lsp-vscode/SKILL.md b/.cursor/skills/ion-lsp-vscode/SKILL.md
@@ -77,7 +77,7 @@ Known limitations: built-in methods have signature hover but no go-to-definition
 
 ### CLI vs LSP error text
 
-The CLI prints `Type check error: UseAfterMove { ... }` (`{:?}` on `TypeCheckError`) and stops at the first error. The LSP uses `check_program_collecting` and may show several type-check diagnostics in one publish (e.g. one per function). LSP formats errors as human-readable strings (e.g. "Use after move: x"). Do not use CLI grep patterns from `ion-integration-tests` to validate LSP diagnostics.
+The CLI and `ion-build` print `Type check failed with N error(s):` followed by numbered lines from `tc::format_type_errors`. The LSP uses `check_program_collecting` and may show several type-check diagnostics in one publish (e.g. one per function). LSP formats errors as human-readable strings (e.g. "Use after move: x"). Do not use CLI grep patterns from `ion-integration-tests` to validate LSP diagnostics.
 
 ## Extension files
 
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -35,6 +35,48 @@ jobs:
           ION_BUILD: ${{ github.workspace }}/target/release/ion-build
         run: cd tests && bash test_runner.sh
 
+      - name: Generated C sanitizer smoke (Linux)
+        shell: bash
+        env:
+          COMPILER: ${{ github.workspace }}/target/release/ion-compiler
+          CC: gcc
+          CFLAGS: -fsanitize=address,undefined -fno-omit-frame-pointer
+          LDFLAGS: -fsanitize=address,undefined
+          ASAN_OPTIONS: detect_leaks=0
+          UBSAN_OPTIONS: halt_on_error=1
+        run: |
+          cd tests
+          "$CC" $CFLAGS -c ../runtime/ion_runtime.c -I. -I.. -I../runtime -o .ion_test_runtime_san.o
+          while IFS=' ' read -r test expected; do
+            "$COMPILER" "$test.ion" >/dev/null
+            "$CC" $CFLAGS "$test.c" .ion_test_runtime_san.o -I. -I.. -I../runtime -lpthread $LDFLAGS -o "$test"
+            set +e
+            "./$test" >/dev/null
+            status=$?
+            set -e
+            if [ "$status" -ne "$expected" ]; then
+              echo "$test: expected exit $expected, got $status"
+              exit 1
+            fi
+            rm -f "$test.c" "$test"
+          done <<'EOF'
+          test_basic 42
+          test_vec_push_pop 0
+          test_string_push_byte 79
+          test_spawn_channel 0
+          test_array_to_slice_coercion 10
+          EOF
+
+      - name: Generated C warning-clean smoke (Linux)
+        shell: bash
+        env:
+          COMPILER: ${{ github.workspace }}/target/release/ion-compiler
+          ION_BUILD: ${{ github.workspace }}/target/release/ion-build
+          CC: gcc
+          CFLAGS: -Wall -Wextra -Werror
+          RUNTIME_OBJ: .ion_test_runtime_werror.o
+        run: cd tests && bash test_runner.sh
+
   integration:
     permissions:
       contents: read
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 ## 2026-06
 
+- **Readiness hardening**: beta compatibility and runtime ABI documents, a lightweight security policy, CLI/`ion-build` multi-error type diagnostics, sanitizer and generated-C warning-clean CI smoke jobs, and `CFLAGS`/`LDFLAGS` support in the integration harness.
 - **Language**: `for` iteration, `match` guards, `else if`, `break`/`continue`, `loop {}`, `+=`, hex/bin literals, function types `fn(T) -> R`, tuple literals and destructuring. Capture-free fn literals (`fn(T) -> R` lowered to static C function pointers; `ClosureCapture` for outer bindings).
 - **Stdlib & runtime**: `fmt.ion`, `Result<T, E>`, `fs.read_to_string`, `String::push_byte`.
 - **Compiler**: scope-drop codegen, `pthread` spawn, slice bounds checks, array-to-slice coercion, struct/enum field drops, `String` equality, module function name mangling, lasting-borrow rules (ION_SPEC 5.3), field-path borrow exclusivity, move/copy tracking fixes, generic monomorphization, generated C file banner (repo-relative source labels via `portable_source_label`, GNU C note, merged stdlib note, multi-file provenance, comment-safe path escaping).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -20,7 +20,7 @@ cargo install --path . --bin ion-compiler --bin ion-build
 
 `ion-lsp` is built with the release command above; point the editor extension at `target/release/ion-lsp` (see README IDE Support).
 
-CI (`.github/workflows/ci.yml`) builds all three binaries on Linux; the Windows job builds `ion-compiler` and `ion-build` only. Build `ion-lsp` locally for IDE work.
+CI (`.github/workflows/ci.yml`) builds all three binaries on Linux, runs integration tests, ASan/UBSan smoke on generated C, and a `-Wall -Wextra -Werror` harness pass on Linux. The Windows job builds `ion-compiler` and `ion-build` only. Build `ion-lsp` locally for IDE work.
 
 ## Test
 
diff --git a/ION_SPEC.md b/ION_SPEC.md
@@ -1237,12 +1237,17 @@ The `ion-lsp` binary and VS Code/Cursor extension provide:
 
 Built-in methods (`Vec::push`, `String::len`, etc.) show signature hover but have no source location for go-to-definition.
 
-The CLI `ion-compiler` still reports the first type-check error only. The LSP uses `TypeChecker::check_program_collecting` to gather multiple diagnostics in one `publish_diagnostics` call. Import failures are reported per `import` statement via `Compiler::load_imports`.
+The CLI `ion-compiler`, `ion-build`, and the LSP use `TypeChecker::check_program_collecting` to gather multiple independent type diagnostics. Import failures are reported per `import` statement via `Compiler::load_imports`.
 
 Build with `cargo build --release --bin ion-lsp`. Rebuild after compiler or LSP changes; reload the editor window so `ion.lspPath` picks up the new binary. Set `ion.lspPath` in editor settings to the executable path.
 
 #### 10.3 Known limitations
 
+Beta compatibility and runtime ABI notes live in [docs/BETA.md](docs/BETA.md)
+and [docs/ABI.md](docs/ABI.md). Features listed below are either intentionally
+constrained in the beta subset or unstable until a later release documents a
+stronger contract.
+
 - No trait bounds on generics
 - String `for...in` iterates bytes (`u8`), not Unicode code points or graphemes
 - `if`/`else` merge: ownership after an `if` is merged from branches that can fall through to the following code. A move in a branch that always `return`s, `break`s, or `continue`s does not block use after the `if`. If two fall-through paths disagree (one moved, one valid), it is still an error.
diff --git a/README.md b/README.md
@@ -29,6 +29,8 @@ Known limitations: [ION_SPEC.md section 10.3](ION_SPEC.md#103-known-limitations)
 | Resource | Contents |
 |----------|----------|
 | [ION_SPEC.md](ION_SPEC.md) | Language semantics, grammar, stdlib contracts |
+| [docs/BETA.md](docs/BETA.md) | Beta subset, compatibility policy, and platform support |
+| [docs/ABI.md](docs/ABI.md) | Runtime ABI notes for generated C and stdlib types |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | Build, test, lint, and PR expectations |
 | [CHANGELOG.md](CHANGELOG.md) | Release notes by month |
 | [tests/README.md](tests/README.md) | Integration test catalog |
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,38 @@
+# Security policy
+
+Ion is pre-1.0. Please treat the compiler, generated C, and runtime as suitable
+for experimentation and early adopters, not for security-critical deployments.
+
+## Supported versions
+
+Only the current `main` branch and the latest tagged `0.x` release, once tags
+exist, receive security attention.
+
+## Reporting a vulnerability
+
+Open a private security advisory if the hosting platform supports it. Otherwise,
+contact the project maintainer privately before publishing details.
+
+Useful reports include:
+
+- the Ion source that triggers the issue;
+- generated C, if relevant;
+- compiler version or commit SHA;
+- platform, C compiler, and sanitizer output;
+- whether the issue is in safe Ion, `unsafe` Ion, FFI, generated C, or runtime C.
+
+## Scope
+
+In scope:
+
+- memory unsafety or data races reachable from safe Ion;
+- compiler crashes on valid or hostile input;
+- generated C that invokes undefined behavior for safe Ion programs;
+- runtime ownership, drop, channel, or spawn bugs.
+
+Out of scope:
+
+- undefined behavior caused by user code inside `unsafe`;
+- vulnerabilities in external C libraries called through FFI;
+- denial-of-service from intentionally enormous source files unless it exposes a
+  distinct compiler bug.
diff --git a/docs/ABI.md b/docs/ABI.md
@@ -0,0 +1,86 @@
+# Ion runtime ABI notes
+
+This document describes the runtime data shapes that Ion-generated C and the
+standard library agree on. It is intentionally a beta-facing contract, not a
+promise that every internal helper symbol is stable before 1.0.
+
+## General rules
+
+- Generated C is the compiler/runtime ABI boundary.
+- Ion values are owned by exactly one binding unless borrowed through `&T` or
+  `&mut T`.
+- Owned values with runtime resources are dropped exactly once by generated
+  scope-exit code.
+- References are stack-only views and must not be stored in runtime containers
+  or sent across threads.
+
+## `String`
+
+`String` is an owned runtime allocation for byte strings. It carries the buffer
+pointer, length, and capacity needed by generated code and runtime helpers.
+String iteration in the beta subset is byte iteration (`u8`), not Unicode
+scalar-value or grapheme iteration.
+
+Stable beta expectations:
+
+- `String::new`, `String::from`, `String::len`, `String::push_str`, and
+  `String::push_byte` preserve ownership of the `String` receiver unless a
+  function explicitly consumes it.
+- Dropping a `String` releases its backing allocation once.
+- `String == String` and `String != String` compare byte contents.
+
+## `Vec<T>`
+
+`Vec<T>` is an owned dynamic array with pointer, length, and capacity. The C
+backend monomorphizes element-specific helpers where needed.
+
+Stable beta expectations:
+
+- `Vec::new`, `Vec::push`, `Vec::pop`, `Vec::get`, `Vec::set`, `Vec::len`, and
+  `Vec::capacity` remain available through the stdlib/builtin surface.
+- Dropping `Vec<T>` drops owned elements when `T` needs destruction.
+- Bounds-sensitive operations either return `Option<T>` where documented or
+  trigger the runtime panic path for checked indexing.
+
+## `Box<T>`
+
+`Box<T>` owns one heap-allocated `T`.
+
+Stable beta expectations:
+
+- `Box::new` allocates and owns a value.
+- `Box::unwrap` consumes the box and returns the owned payload.
+- Dropping a `Box<T>` drops the payload and releases the allocation once.
+
+## Arrays and slices
+
+Fixed arrays `[T; N]` are inline values. Slices `[]T` are fat views carrying a
+data pointer and length. Safe indexing emits runtime bounds checks; indexing
+inside `unsafe` blocks may omit those checks.
+
+## Enums and structs
+
+Struct layout is C-oriented and field-order preserving in generated C. Enum
+layout is compiler-generated and should be treated as stable only for C emitted
+by the same Ion compiler/runtime version unless a beta release explicitly
+documents a layout guarantee.
+
+## Channels and `spawn`
+
+Channels are typed ownership-transfer queues backed by the C runtime. Sending a
+value moves ownership into the channel; receiving moves ownership out. `spawn`
+creates an OS thread and transfers only structurally `Send` values into the
+thread context.
+
+Stable beta expectations:
+
+- References do not cross channel or thread boundaries.
+- Channel handles are runtime resources and are released by generated drops.
+- Runtime failures such as allocation or thread creation failures call the Ion
+  panic path.
+
+## Drops and panics
+
+Generated code is responsible for normal-scope destruction. Runtime panics abort
+the process; they are not currently exception-style unwinds. Code that relies on
+drop execution after a runtime panic is outside the beta contract.
diff --git a/docs/BETA.md b/docs/BETA.md
@@ -0,0 +1,62 @@
+# Ion beta readiness contract
+
+Ion is currently a `0.x` language and toolchain. This document defines what the
+project means by a future beta release: a narrow, documented compatibility
+surface rather than a promise that every experimental feature is complete.
+
+## Beta compatibility window
+
+For a beta tag, Ion should keep programs written against the stable beta subset
+compiling for the rest of the beta line unless a release note explicitly calls
+out a breaking change. Breaking changes require at least one of:
+
+- a new minor version while Ion remains `0.x`;
+- a migration note in `CHANGELOG.md`;
+- an unstable-feature escape hatch documented in this file or `ION_SPEC.md`.
+
+## Stable beta subset
+
+The stable beta subset is the part of Ion that examples, CI, and the standard
+library may rely on without an unstable marker:
+
+- ownership, moves, drops, no-escape `&T` / `&mut T`, and borrow conflicts;
+- functions, structs, enums, type aliases, modules, imports, and visibility;
+- primitive numeric and boolean types, arrays, slices, `String`, `Vec<T>`,
+  `Box<T>`, and `Result<T, E>`;
+- `if`, `while`, `for`, `loop`, `break`, `continue`, `match`, guards, and
+  `defer`;
+- FFI through `extern "C"` and `unsafe`;
+- channels and `spawn` with structural `Send`;
+- `ion-build` projects with `ion.toml` fields documented in `ION_SPEC.md`.
+
+## Unstable or constrained in beta
+
+The following features may change shape before 1.0:
+
+- tuples beyond flat two-field values;
+- capture-free function literals and function-pointer coercions;
+- generic ergonomics without trait bounds;
+- byte-oriented string iteration;
+- conservative move analysis in `while` and `for` loops;
+- generated C layout details not covered by `docs/ABI.md`.
+
+## Compatibility policy
+
+- The compiler, bundled standard library, runtime C ABI, and `ion-build`
+  manifest format are versioned together.
+- Public stdlib import paths such as `stdlib/io.ion`, `stdlib/fmt.ion`,
+  `stdlib/fs.ion`, and `stdlib/result.ion` should not be removed or renamed in a
+  patch release.
+- Additions are allowed in patch releases. Breaking language, stdlib, runtime,
+  or manifest changes require a minor version while Ion is `0.x`.
+- Unsupported behavior inside `unsafe` remains outside the compatibility
+  guarantee.
+
+## Platform support
+
+Beta support is limited to platforms exercised in CI:
+
+- Linux with GCC or Clang-compatible C tooling.
+- Windows with MinGW GCC through Git Bash.
+
+macOS and MSVC are best-effort until CI covers them.
diff --git a/src/build/driver.rs b/src/build/driver.rs
@@ -26,7 +26,7 @@ impl std::fmt::Display for BuildError {
         match self {
             BuildError::Manifest(err) => write!(f, "{err}"),
             BuildError::Compile(err) => write!(f, "{err}"),
-            BuildError::TypeCheck(msg) => write!(f, "Type check error: {msg}"),
+            BuildError::TypeCheck(msg) => write!(f, "{msg}"),
             BuildError::Io { path, message } => {
                 write!(f, "IO error ({}): {message}", path.display())
             }
@@ -86,9 +86,10 @@ fn type_check(
     let mut checker = tc::TypeChecker::new();
     checker.set_module_exports(compiler.get_module_exports().clone());
     let merged = compiler.merge_modules(ast, main_path);
-    checker
-        .check_program(&merged)
-        .map_err(|err| BuildError::TypeCheck(format!("{err:?}")))?;
+    let (_result, errors) = checker.check_program_collecting(&merged);
+    if !errors.is_empty() {
+        return Err(BuildError::TypeCheck(tc::format_type_errors(&errors)));
+    }
     Ok(())
 }
 
diff --git a/src/main.rs b/src/main.rs
@@ -84,8 +84,9 @@ fn main() {
 
     // Type check merged program (main + imported modules)
     let merged_program = compiler.merge_modules(&ast, input_path);
-    if let Err(err) = checker.check_program(&merged_program) {
-        eprintln!("{}", err);
+    let (_result, errors) = checker.check_program_collecting(&merged_program);
+    if !errors.is_empty() {
+        eprintln!("{}", tc::format_type_errors(&errors));
         process::exit(1);
     }
 
diff --git a/src/tc/mod.rs b/src/tc/mod.rs
@@ -196,6 +196,14 @@ impl std::fmt::Display for TypeCheckError {
     }
 }
 
+pub fn format_type_errors(errors: &[TypeCheckError]) -> String {
+    let mut message = format!("Type check failed with {} error(s):", errors.len());
+    for (idx, err) in errors.iter().enumerate() {
+        message.push_str(&format!("\n  {}. {}", idx + 1, err));
+    }
+    message
+}
+
 #[derive(Debug, Clone)]
 pub struct TypeCheckResult {
     pub lsp_info: LspInfo,
diff --git a/tests/README.md b/tests/README.md
diff --git a/tests/test_runner.sh b/tests/test_runner.sh
