docs: freeze bootstrap contract and lock ABI tests (#24)

Author: OmarAglan

CHANGELOG.md

@@ -14,6 +14,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
   - Added `docs/COMPONENT_OWNERSHIP.md`.
   - Defined canonical logical boundaries for `Frontend`, `Middle-End`, `Backend`, `Driver`, and `Support`.
   - Documented allowed dependency directions between those components.
+- **Bootstrap contract freeze summary (v0.5.1 sidecar)**:
+  - Added `docs/BOOTSTRAP_CONTRACT.md`.
+  - Published the frozen bootstrap-facing contract for the current language surface, stdlib signatures, ABI rules, and IR/verifier guarantees.
+  - Declared the currently unsupported bootstrap surface that remains intentionally frozen as unsupported.
 - **Component-owned public header surfaces**:
   - Added `src/frontend/lexer.h`, `src/frontend/ast.h`, `src/frontend/parser.h`, and `src/frontend/analysis.h` as the frontend-owned public declarations split out of the old shared surface.
   - Added `src/support/version.h`, `src/support/read_file.h`, `src/support/diagnostics.h`, `src/support/updater.h`, and `src/support/target_contract.h` for support-owned cross-cutting contracts.
@@ -29,6 +33,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
   - File I/O failures now include Arabic-first diagnostics with the underlying system error reason.
   - Fatal read-path diagnostics consistently terminate with `EXIT_FAILURE` via `stderr`.
 
+- **Bootstrap freeze documentation sync**:
+  - `docs/LANGUAGE.md`, `docs/INTERNALS.md`, and `docs/BAA_IR_SPECIFICATION.md` now point to `docs/BOOTSTRAP_CONTRACT.md` as the bootstrap-facing summary of the frozen contracts.
+  - `stdlib/baalib.baahd` now explicitly declares itself as the canonical stdlib signature surface for the freeze.
+- **Bootstrap regression locking**:
+  - Added focused integration coverage for Windows x64 call-register/shadow-space emission, SysV varargs `AL=0` emission, and verifier-safe CFG/phi compilation.
 - **QA orchestration**:
   - `scripts/qa_run.py` now runs the module-size guard before `full` and `stress` QA work, and stops early on hard-cap violations.
 - **CI gating**:

ROADMAP.md

@@ -1,7 +1,7 @@
 # Baa Roadmap (Updated)
 
 > Track the development progress of the Baa programming language.
-> **Current Status:** Phase 4.5 - Bootstrap Readiness (v0.5.x) ← IN PROGRESS
+> **Current Status:** Phase 4.5 - Bootstrap Readiness (v0.5.3) ← IN PROGRESS
 
 ---
 
@@ -1330,10 +1330,12 @@ Partial status update (2026-03-06):
 
 ### v0.5.1: Language + ABI Freeze 🔒
 
-- [ ] **Freeze grammar surface** — avoid syntax churn before bootstrap.
-- [ ] **Freeze stdlib signatures** — lock callable contracts used by compiler-in-Baa.
-- [ ] **Freeze target ABI contracts** — Windows x64 + SystemV AMD64 invariants.
-- [ ] **Freeze IR invariants** — verifier-enforced guarantees documented.
+- [x] **Freeze grammar surface** — avoid syntax churn before bootstrap.
+- [x] **Freeze stdlib signatures** — lock callable contracts used by compiler-in-Baa.
+- [x] **Freeze target ABI contracts** — Windows x64 + SystemV AMD64 invariants.
+- [x] **Freeze IR invariants** — verifier-enforced guarantees documented.
+
+✅ COMPLETED (2026-03-22)
 
 ### v0.5.2: Module & Multi-File Hardening 📦
 
@@ -1395,7 +1397,7 @@ Partial status update (2026-03-06):
 #### Phase 4.5 Required Artifacts
 
 - [x] `docs/COMPONENT_OWNERSHIP.md` — boundaries + owners + allowed dependencies.
-- [ ] `docs/BOOTSTRAP_CONTRACT.md` — frozen ABI/IR/language requirements for v0.9.
+- [x] `docs/BOOTSTRAP_CONTRACT.md` — frozen ABI/IR/language requirements for v0.9.
 - [ ] `docs/BAA0_SPEC.md` — bootstrap subset definition and exclusions.
 - [ ] `scripts/qa_bootstrap_gate.py` — one-command admission checks for Phase 5.
 - [ ] `tests/bootstrap/` — parity corpus dedicated to migration from C → Baa slices.

docs/BAA_IR_SPECIFICATION.md

@@ -4,6 +4,10 @@
 
 This document specifies the Intermediate Representation (IR) for the Baa compiler. The IR uses Arabic naming conventions throughout, creating a culturally authentic yet technically robust design.
 
+> **Bootstrap freeze note (v0.5.1):** The verifier-backed IR invariants in this document are part
+> of the frozen bootstrap contract. See [BOOTSTRAP_CONTRACT.md](BOOTSTRAP_CONTRACT.md) for the
+> bootstrap-facing summary.
+
 ---
 
 ## Table of Contents
@@ -145,6 +149,9 @@ The `فاي` instruction selects a value based on which predecessor block was ex
 - **IR well-formedness verifier (v0.3.2.6.5):** The compiler provides `--verify-ir` to validate general IR invariants (operand counts, type consistency, terminator rules, phi placement, and intra-module call signature checks).
 - **All verifiers (v0.3.2.9.1):** The compiler provides `--verify` to run `--verify-ir` + `--verify-ssa` together (requires `-O1`/`-O2`).
 
+These currently enforced verifier guarantees are the IR portion of the bootstrap freeze; this
+freeze does not promise additional IR features beyond the implemented verifier surface.
+
 ### 3.4 Memory Model
 
 Stack allocations create addressable memory:

docs/BOOTSTRAP_CONTRACT.md

@@ -0,0 +1,166 @@
+# Baa Bootstrap Contract
+
+> **Version:** v0.5.1 freeze contract (bootstrap-facing) | [Language Spec →](LANGUAGE.md)
+
+This document freezes the current Baa language, stdlib, ABI, and IR contracts that later
+bootstrap work must treat as stable inputs.
+
+It is intentionally conservative:
+
+- no new syntax is introduced here,
+- no ABI behavior is widened here,
+- no IR guarantees are promised beyond what the current compiler already implements and verifies.
+
+## Canonical Sources
+
+The freeze is defined by these sources of truth:
+
+- Language surface: `docs/LANGUAGE.md`
+- Standard library callable signatures: `stdlib/baalib.baahd`
+- IR semantics and verifier-backed invariants: `docs/BAA_IR_SPECIFICATION.md`
+- Target/ABI implementation contract: `src/backend/target.h` and `src/backend/target.c`
+
+If detailed docs drift from these surfaces, this document and the files above win for bootstrap
+planning.
+
+## Frozen Language Surface
+
+The following source-language surface is frozen for bootstrap readiness:
+
+- UTF-8 source files with `.baa` extension
+- `الرئيسية` as the only program entry-point name
+- current preprocessor directives:
+  - `#تضمين`
+  - `#تعريف`
+  - `#إذا_عرف`
+  - `#وإلا`
+  - `#نهاية`
+  - `#الغاء_تعريف`
+  - `#خطأ`
+- current core type spellings, including:
+  - signed/unsigned integer families
+  - `منطقي`
+  - `حرف`
+  - `نص`
+  - `عشري`
+  - `عشري٣٢` as a source-level alias that still lowers as `f64`
+  - `عدم`
+  - function-pointer syntax `دالة(...) -> ...`
+- current control-flow and declaration syntax
+- current function-pointer syntax and semantics
+- current variadic function syntax with `...`
+- current inline-assembly syntax through `مجمع`
+
+The only frozen entry-point signatures are:
+
+```baa
+صحيح الرئيسية()
+صحيح الرئيسية(صحيح عدد، نص[] معاملات)
+```
+
+Bootstrap work must not assume additional accepted entry-point shapes.
+
+## Frozen Standard Library Surface
+
+`stdlib/baalib.baahd` is the canonical stdlib signature surface for bootstrap work.
+
+The current frozen modules are:
+
+- string APIs
+- dynamic memory APIs
+- file I/O APIs
+- math APIs
+- system APIs
+- time APIs
+- error-handling APIs
+- variadic intrinsics
+
+Freeze rules:
+
+- exact callable signatures come from `stdlib/baalib.baahd`
+- ownership rules documented there are part of the contract
+- heap-returning APIs remain heap-returning APIs and must be freed by the caller as documented
+- no new stdlib signatures should be introduced under the bootstrap freeze without explicitly
+  revising this contract
+
+## Frozen Target / ABI Surface
+
+Only these targets are in scope for the freeze:
+
+- `x86_64-windows`
+- `x86_64-linux`
+
+Windows x64 ABI contract:
+
+- integer/pointer argument registers: `RCX`, `RDX`, `R8`, `R9`
+- return register: `RAX`
+- 32-byte shadow space at call boundaries
+- object format: COFF/PE
+- executable suffix default: `.exe`
+
+SystemV AMD64 ABI contract:
+
+- integer/pointer argument registers: `RDI`, `RSI`, `RDX`, `RCX`, `R8`, `R9`
+- return register: `RAX`
+- no shadow space
+- varargs path currently emits `AL=0` when no XMM arguments are used
+- object format: ELF
+- executable suffix default: empty
+
+Shared target limits:
+
+- x86-64 only
+- current data layout stays 64-bit and identical across the two supported x86-64 targets
+- cross-target assembly generation is supported; bootstrap work must not assume broader host/toolchain
+  guarantees than the current compiler documents
+
+## Frozen IR / Verifier Surface
+
+The bootstrap freeze relies on the current Baa IR contract, not a future generalized IR.
+
+Frozen guarantees:
+
+- SSA-form IR before Out-of-SSA
+- verifier-backed single-definition SSA discipline
+- verifier-backed dominance and phi incoming-edge checks
+- verifier-backed well-formedness for:
+  - operand counts
+  - type consistency
+  - terminator rules
+  - phi placement
+  - intra-module call signature checks
+- current x86-64 data-layout assumptions
+- current typed-memory model for `حجز` / `حمل` / `خزن`
+
+Non-guarantees:
+
+- no promise of new IR opcodes for bootstrap
+- no promise of new alias-analysis precision
+- no promise of non-x86-64 data layouts in this freeze
+
+## Frozen Unsupported Surface
+
+The following remain intentionally unsupported under the freeze and must stay unsupported unless a
+later milestone explicitly reopens them:
+
+- variadic function-pointer calls
+- advanced inline-assembly constraints and clobber lists beyond the currently documented subset
+- additional entry-point signatures beyond the two frozen forms
+- new bootstrap-relevant syntax churn in grammar/type spelling
+- new target families or ABI contracts beyond current Windows x64 and SystemV AMD64 support
+
+## Enforcement Expectations
+
+The freeze is locked by:
+
+- documentation synchronization against the canonical sources above
+- existing verifier paths: `--verify-ir`, `--verify-ssa`, and `--verify`
+- focused integration tests that lock:
+  - stdlib short include behavior
+  - entry-point argument lowering
+  - SysV register-argument behavior
+  - Windows shadow-space/register-call behavior
+  - verifier-safe CFG/phi compilation
+
+This document is the bootstrap-facing summary, but it does not replace the detailed language,
+stdlib, ABI, and IR references that define exact syntax and declarations.

docs/INTERNALS.md

@@ -13,6 +13,7 @@ This document details the internal architecture, data structures, and algorithms
 ## Table of Contents
 
 - [Pipeline Architecture](#1-pipeline-architecture)
+- [Bootstrap Contract](#11-bootstrap-contract-v051)
 - [Component Boundaries & Size Guard](#121-component-boundaries--size-guard-v050-sidecar)
 - [Lexical Analysis](#2-lexical-analysis)
 - [Syntactic Analysis](#3-syntactic-analysis)
@@ -80,6 +81,17 @@ flowchart LR
 
 > **Note (v0.3.2.4+):** The compiler uses the full IR-based backend pipeline end-to-end: AST → IR → Optimizer → ISel → RegAlloc → Emit → Assembly.
 
+## 1.1. Bootstrap Contract (v0.5.1)
+
+For bootstrap planning, the current language/stdlib/ABI/IR surface is frozen and summarized in
+[BOOTSTRAP_CONTRACT.md](BOOTSTRAP_CONTRACT.md).
+
+Practical rule:
+
+- bootstrap work consumes the frozen contracts as inputs,
+- later milestones may extend them only through explicit roadmap work,
+- ad-hoc syntax or ABI churn is out of scope under the freeze.
+
 ### 1.1.1. Component Map
 
 ```mermaid
@@ -2375,7 +2387,9 @@ The emitter translates Arabic function names to their C runtime equivalents:
 
 #### 6.21.8. ABI Compliance (Windows x64 + SystemV AMD64)
 
-This backend is being refactored to support multiple ABIs via `BaaTarget` (`src/target.h`).
+The current backend ABI contract is frozen for bootstrap via `BaaTarget`
+([`src/backend/target.h`](../src/backend/target.h)) and summarized in
+[BOOTSTRAP_CONTRACT.md](BOOTSTRAP_CONTRACT.md).
 
 - **Windows x64 ABI:** shadow space (32 bytes) around calls; first 4 args in RCX/RDX/R8/R9; return in RAX.
 - **SystemV AMD64 (Linux):** no shadow space; first 6 args in RDI/RSI/RDX/RCX/R8/R9; return in RAX; varargs require `AL=0` when no XMM args.

docs/LANGUAGE.md

@@ -4,6 +4,10 @@
 
 Baa (باء) is a compiled systems programming language using Arabic syntax. It compiles to native code via Assembly + host GCC/Clang on Windows and Linux.
 
+> **Bootstrap freeze note (v0.5.1):** The current language surface is frozen for bootstrap
+> readiness. See [BOOTSTRAP_CONTRACT.md](BOOTSTRAP_CONTRACT.md) for the canonical summary of the
+> frozen language, stdlib, ABI, and IR expectations.
+
 ---
 
 ## Table of Contents
@@ -719,6 +723,12 @@ Every program **must** have a main function:
 
 **Important:** The entry point **must** be named `الرئيسية` (ar-ra'īsīyah). It is exported as `main` in the generated assembly.
 
+**Bootstrap freeze rule (v0.5.1):** Only the two currently supported entry-point signatures are in
+scope for bootstrap:
+
+- `صحيح الرئيسية()`
+- `صحيح الرئيسية(صحيح عدد، نص[] معاملات)`
+
 **Command Line Arguments [Implemented v0.3.12.5]:**
 The main function can optionally accept arguments:
 
@@ -1290,6 +1300,10 @@ Baa includes a minimal standard library. To use it, you must include its header
 
 **Syntax:** `#تضمين "baalib.baahd"` (also supported: `#تضمين "stdlib/baalib.baahd"`)
 
+**Bootstrap freeze rule (v0.5.1):** The exact callable signature surface is defined by
+`stdlib/baalib.baahd`. This document describes that surface, but the header remains the canonical
+declaration source for bootstrap-facing stdlib contracts.
+
 ### 9.1. String Operations (`نص`)
 
 Strings in Baa are UTF-8 arrays of `حرف` terminated by a null character. The standard library provides C-like string manipulation functions.

stdlib/baalib.baahd

@@ -1,4 +1,5 @@
-// واجهات مكتبة باء القياسية (v0.4.0.0)
+// واجهات مكتبة باء القياسية
+// هذا الملف هو السطح المرجعي المجمّد لتواقيع stdlib ضمن عقد التمهيد v0.5.1.
 // ملاحظة الملكية:
 // - نسخ_نص ودمج_نص يعيدان نصاً مخصصاً على heap.
 // - يجب تحرير النتيجة لاحقاً عبر حرر_نص.

tests/integration/ir/ir_sysv_varargs_al_zero_asm_test.baa

@@ -0,0 +1,24 @@
+// RUN: compile-only
+// FLAGS: -S --target=x86_64-linux
+// EXPECT-ASM: xorl %eax, %eax
+
+#تضمين "stdlib/baalib.baahd"
+
+صحيح جمع_متغير(صحيح عدد, ...) {
+    قائمة_معاملات قائمة = عدم.
+    بدء_معاملات(قائمة، عدد).
+
+    صحيح مجموع = ٠.
+    لكل (صحيح ف = ٠؛ ف < عدد؛ ف++) {
+        مجموع = مجموع + معامل_تالي(قائمة، صحيح).
+    }
+
+    نهاية_معاملات(قائمة).
+    إرجع مجموع.
+}
+
+صحيح الرئيسية() {
+    صحيح أ = جمع_متغير(٢، ١، ٢).
+    صحيح ب = جمع_متغير(٢، ٣، ٤).
+    إرجع أ - ب.
+}

tests/integration/ir/ir_verify_phi_freeze_test.baa

@@ -0,0 +1,19 @@
+// RUN: compile-only
+
+صحيح دمج_شرطي(صحيح س) {
+    صحيح ن = س.
+
+    إذا (س > ١٠) {
+        ن = س + ١.
+    } وإلا {
+        ن = س - ١.
+    }
+
+    إرجع ن.
+}
+
+صحيح الرئيسية() {
+    صحيح أ = دمج_شرطي(١٢).
+    صحيح ب = دمج_شرطي(٣).
+    إرجع أ - ب.
+}

tests/integration/ir/ir_windows_call_abi_4args_asm_test.baa

@@ -0,0 +1,17 @@
+// RUN: compile-only
+// FLAGS: -S --target=x86_64-windows
+// EXPECT-ASM: subq $32, %rsp
+// EXPECT-ASM: movq $1, %rcx
+// EXPECT-ASM: movq $2, %rdx
+// EXPECT-ASM: movq $3, %r8
+// EXPECT-ASM: movq $4, %r9
+
+صحيح اجمع4(صحيح أ, صحيح ب, صحيح ج, صحيح د) {
+    إرجع أ + ب + ج + د.
+}
+
+صحيح الرئيسية() {
+    صحيح أ = اجمع4(1, 2, 3, 4).
+    صحيح ب = اجمع4(5, 6, 7, 8).
+    إرجع أ - ب.
+}