# I13 Compiler Canon — Known Good Status: **EXECUTABLE VERTICAL SLICE · TAGGED VALUE MODEL FROZEN · I13 FRAME LAW FROZEN · STEP POLICY RESOLVED · CONFORMANCE v0.1 · DIAGNOSTICS v0.1 · INTROSPECTION v0.1 · TRACE v0.1 · DEBUGGER v0.1 · BOOTSTRAP v0.1 FROZEN** This document freezes only compiler architecture and behavior proven by the compiler/conformance path. It does not add language features. ## Canonical authority chain ```text SPEC ↓ HIR ↓ IVM ``` The three authorities are: 1. **Language authority** — `spec/I13.md` 2. **Semantic authority** — I13 HIR 3. **Execution authority** — IVM-13 Backends may differ. Semantics may not. ## Compiler law ```text I13-COMPILER-001 SOURCE SYNTAX MAY DESUGAR. THE TWELVE MAY NOT DRIFT. IVM MAY LOWER. SEMANTICS MAY NOT DRIFT. BACKENDS MAY DIFFER. RESULTS MAY NOT. ``` ## Canonical pipeline ```text .i13 source ↓ source + spans ↓ lexer ↓ token stream ↓ parser ↓ AST ↓ HIR ↓ semantic checker ↓ IVM-13 ↓ single-pass validator / \ / \ VM Wasm \ / \ / = ``` ## I13 identity The concrete declaration keyword is `I`. The twelve semantic words remain: ```text Name Constant Attribute Assign Arg Return Expr If Compare Call FunctionDef BinOp ``` `Block` is a container, not a thirteenth semantic word. ## Representation law ```text AST = what the programmer physically wrote HIR = what I13 says that writing means IVM = executable I13 ``` The parser does not define language semantics. The Wasm backend does not define language semantics. ## One execution law Opcode stack/control effects have one definition. Validator, reference VM, and Wasm lowering consume the same IVM law rather than re-deriving it independently. The frozen IVM opcode surface remains exactly: ```text Const Ask Attr Ret Answer Drop Bin Cmp If Call Block Else End Func Halt ``` ## Reference-first law The reference VM prioritizes correctness and determinism over speed. For every semantic conformance program inside the canonical execution boundary: ```text VM(program) == WASM(program) ``` A disagreement is a compiler/backend defect until proven to arise from an explicitly non-semantic runtime policy. ## Wasm tagged-value law — FROZEN `I13-WASM-VALUE-001` ```text A VALUE SHALL RETAIN ITS KIND AND PAYLOAD THROUGH LOWERING. LOWERING MAY CHANGE REPRESENTATION. LOWERING MAY NOT ERASE VALUE IDENTITY. ``` The reference VM distinguishes: ```text Value::Number(f64) Value::Function(function_id) ``` Generated Wasm preserves that distinction as: ```text [ kind:i32 | payload:f64 ] NUMBER = [0 | numeric f64] FUNCTION = [1 | function/table id] ``` Stored bindings retain three independent facts: ```text [ kind | payload | bound ] ``` Tagged values are preserved through `Ask`, `Answer`, arguments, returns, local storage, and global storage. Operation boundaries enforce: ```text Bin / Cmp / If require NUMBER Call requires FUNCTION ``` `I13-WASM-TYPE-001` is closed and regression-locked. Original evidence remains in `docs/COMPILER-TORTURE-001.md`. ## Canonical frame law — FROZEN `I13-EXEC-LIMIT-001` ```text I13_FRAME_LIMIT = 4096 ``` This is part of I13, not host policy. The count includes the main/root frame. A `Call` is legal only when pushing the callee keeps active I13 frames at or below `4096`. The IVM layer owns `I13_FRAME_LIMIT`. The reference VM cannot raise its execution ceiling above it. Generated Wasm owns a private frame-depth counter, resets it to `1` at each `i13_run`, checks the canonical limit before every `call_indirect`, increments before a legal call, and decrements after a successful return. The former `I13-WASM-LIMIT-002` disagreement is closed: ```text count(4094) VM PASS == Wasm PASS count(4095) VM VETO == Wasm TRAP count(4096) VM VETO == Wasm TRAP ``` The frame law is hard-regression-gated in compiler/Wasm CI and in conformance v0.1. ## Deterministic step policy — FROZEN AS RUNTIME POLICY `I13-RUNTIME-POLICY-001` The reference VM keeps a deterministic IVM instruction meter: ```text 1 executed IVM instruction = 1 VM step ``` The reference VM default remains: ```text step_limit = 8,000,000 ``` This is a **reference-runtime safety fuse**, not an I13 language-validity rule. Measured evidence shows the meter is deterministic but execution-shape sensitive: ```text I OUT <- 1 + 2 → 4 steps, OUT=3 I a <- 1 I b <- 2 I OUT <- a + b → 8 steps, OUT=3 ``` Therefore: ```text DETERMINISTIC STEP METER KEEP 8M REFERENCE SAFETY FUSE KEEP 8M LANGUAGE LIMIT NO WASM 8M MATCH REQUIRED NO ``` The historical `I13-WASM-STEP-003` observation is reclassified as **policy divergence, not a semantic compiler defect**. Evidence and the locked decision live in `docs/COMPILER-STEP-HYPOTHESIS.md` and `docs/COMPILER-RUNTIME-POLICY.md`. A future I13 gas model would require its own separately versioned charge schedule before gas could participate in language conformance. ## Differential hardening — KNOWN GOOD THROUGH ATTACK 29 The measured passing surface includes: ```text 1-8 arithmetic/control/tagged-value regression 9 function used as If condition 10 rebound function name called 11 nested calls 12 global assignment before declaration 13 local assignment before declaration 14 function fallthrough 15 nested early return 16 arity-16 tagged ABI 17 recursion 512 18 recursion 1024 19 recursion 1536 20 recursion 2048 21 recursion 2560 22 recursion 3072 23 recursion 3584 24 recursion 4094 25 recursion 4095 · VM VETO = Wasm TRAP 26 recursion 4096 · VM VETO = Wasm TRAP 27 explode(16) · OUT=65536 28 explode(17) · OUT=131072 29 explode(18) · OUT=262144 ``` `explode(19)` remains useful as a runtime-policy probe but is no longer an open semantic parity defect. ## Conformance v0.1 — FROZEN `I13-CONFORMANCE-0.1` The formal conformance layer is separate from torture and policy characterization: ```text TORTURE discovers POLICY TEST characterizes CONFORMANCE locks known good ``` The manifest is `tests/conformance/manifest.json`. The runner is `scripts/compiler_conformance.js`. The CI gate is `.github/workflows/compiler-conformance.yml`. v0.1 locks these classes: ```text execute check + VM result + Wasm result + repeat determinism compile_error stable compiler diagnostic runtime_error VM diagnostic + Wasm trap resource_error canonical I13 resource-law parity ``` The first manifest covers arithmetic, nested calls, osmotic bind, recursion, `examples/core.i13`, arity diagnostics, unknown-function diagnostics, lexical rejection, division-by-zero runtime behavior, tagged Function-as-Number rejection, and the canonical 4096-frame ceiling. The 8M reference-VM safety fuse is explicitly excluded from semantic conformance. ## Diagnostics + source mapping v0.1 — FROZEN `I13-DIAGNOSTICS-0.1` Diagnostics are a compiler contract rather than incidental terminal text. `check`, `run`, and `build` share one renderer with stable E-code, compiler phase/category, file/line/column, source excerpt, and marked source span. Spans survive: ```text source → token → AST → HIR → IVM → validator/VM diagnostic ``` The full contract lives in `docs/COMPILER-DIAGNOSTICS.md` and is conformance-locked. ## Compiler introspection v0.1 — FROZEN `I13-INTROSPECTION-0.1` The CLI exposes deterministic read-only views: ```text i13 dump file.i13 --tokens i13 dump file.i13 --ast i13 dump file.i13 --hir i13 dump file.i13 --ivm ``` The authority law is: ```text INTROSPECTION MAY REVEAL AUTHORITY. INTROSPECTION MAY NOT DEFINE AUTHORITY. ``` Dump text is not accepted back into the compiler and cannot become a shadow source/IR format. The full contract lives in `docs/COMPILER-INTROSPECTION.md`. ## Execution tracing v0.1 — FROZEN `I13-TRACE-0.1` The CLI exposes: ```text i13 trace file.i13 ``` Tracing instruments the existing reference VM loop through a read-only observer. `vm::run` and `vm::run_observed` execute the same implementation; there is no trace interpreter. Every event observes the real pre-instruction state and includes: ```text step active frame depth main/function scope program counter opcode stack height canonical need/net stack effect source span operation-specific runtime detail ``` The frozen trace law is: ```text TRACE MAY OBSERVE EXECUTION. TRACE MAY NOT DEFINE EXECUTION. ``` Observed execution is regression-required to preserve the exact unobserved `VmResult`, and runtime failures preserve the exact diagnostic while the last emitted event identifies the real failing IVM instruction. CLI tracing streams events rather than collecting a full execution history in memory. v0.1 traces the canonical reference VM; it does not redefine Wasm parity or claim to expose host Wasm instructions. The full contract lives in `docs/COMPILER-TRACE.md`. ## Interactive debugger v0.1 — FROZEN `I13-DEBUGGER-0.1` The CLI exposes: ```text i13 debug file.i13 ``` Debugger control consumes the same pre-instruction observer point as tracing. `vm::run`, `vm::run_observed`, and `vm::run_debugged` enter one execution loop; there is no debugger interpreter. The debugger may pause and inspect immutable snapshots containing tagged globals, active I13 frames, current operand stack, current locals, PC/opcode and source span. It may resume execution or quit the debugger session. It cannot mutate values, frames, stacks, PCs or IVM instructions. The frozen debugger law is: ```text DEBUGGER MAY PAUSE EXECUTION. DEBUGGER MAY INSPECT EXECUTION. DEBUGGER MAY NOT MUTATE EXECUTION. ``` v0.1 provides `step`, `next`, `continue`, source-line breakpoints, breakpoint deletion/listing, `where`, binding lookup, stack inspection, frame inspection and clean debugger quit. Source-line breakpoint suppression is frame-aware: deeper calls do not clear the caller's suppression, so returning to another lowered instruction on the triggering source line does not spuriously re-fire the same breakpoint. The repaired debugger proof commit `ce3d605e4ef9e7398bc8e2de6bf492bd4c927f30` passed all compiler/debugger tests, compiler-owned Wasm parity, the canonical 4096-frame gate and conformance v0.1. The full contract lives in `docs/COMPILER-DEBUGGER.md`. ## I13 bootstrap self-use v0.1 — FROZEN `I13-BOOTSTRAP-0.1` Bootstrap v0.1 begins moving executable compiler/runtime support logic into I13 wherever the current language surface is sufficient. ```text I13-BOOTSTRAP-001 IF A COMPILER OR RUNTIME LAW CAN BE EXPRESSED IN THE CURRENT I13 LANGUAGE SURFACE, ITS EXECUTABLE REFERENCE PROBE SHOULD BE WRITTEN IN I13. HOST CODE MAY ORCHESTRATE. HOST CODE MAY VERIFY. HOST CODE MUST NOT PRETEND I13 HAS CAPABILITIES IT DOES NOT HAVE. ``` `examples/compiler_bootstrap.i13` is a real I13 program that mirrors and self-tests: ```text all 15 frozen opcode ids all 15 stack need/net effects variable Call(argc) effect 4096-frame Call admission Number / Function kind gates Bin / Compare / If / Call kind requirements Answer mode validity and scope class recursive whole-law checksum ``` The authoritative stack-effect implementation remains `src/compiler/ivm.rs`; bootstrap is an executable mirror/witness and does not become a fourth authority. First proof evidence: ```text VALID · IVM 15 ops · 16 region(s) · peak stack 4 RUN OK · 5946 step(s) · peak stack 4 · call depth 19 BUILD OK · 23186 byte(s) · 48 I13 global(s) WASM PARITY OK · 10 checked global(s) · repeat deterministic ``` Proof globals include: ```text BOOTSTRAP_OK = 1 LAW_CHECKSUM = 15638 FRAME_4095 = 1 FRAME_4096 = 0 CALL16_NEED = 17 CALL16_NET = -16 NUMBER_BIN_OK = 1 FUNCTION_BIN_VETO = 0 FUNCTION_CALL_OK = 1 NUMBER_CALL_VETO = 0 ``` The first dedicated `I13 compiler bootstrap` workflow passed the I13 check, reference VM execution, generated Wasm execution and deterministic repeat gate. This is deliberately called **self-use**, not self-hosting. I13 v0.1 still lacks strings/text values, general collections, structured records, file/source byte access, modules/imports and host I/O primitives required for an honest lexer/parser/compiler implementation in I13. The full contract and migration boundary live in `docs/COMPILER-BOOTSTRAP.md`. ## Compiler-owned Wasm law The production backend consumes **validated IVM**, not HIR and not AST. ```text validated IVM ↓ compiler/wasm.rs ↓ WebAssembly binary ``` The backend is dependency-free and emits the WebAssembly binary format directly. `i13_run` resets program globals and private execution-frame depth before execution so repeated calls represent fresh deterministic executions. IVM division-by-zero behavior is preserved with an explicit Wasm guard rather than accepting native `f64.div` infinity behavior. ## Closed inherited/compiler defects The accepted compiler path closes these defects: - `Arg` is a real HIR construct. - unsupported `Attribute` use fails explicitly before execution. - call arity fails during semantic checking. - reference-VM recursion uses explicit VM frames, not Rust recursion. - stack/control effects have one IVM authority. - source spans and stable diagnostics exist from the front end onward. - Wasm preserves Number versus Function identity. - VM and Wasm share the canonical I13 4096-frame ceiling. - reference step metering is explicitly separated from language semantics. - compiler layer dumps are observer-only and do not create a fourth authority. - runtime tracing observes the real VM loop rather than duplicating execution semantics. - interactive debugging pauses the same VM loop without exposing mutable execution state or a second interpreter. - compiler-law self-use now executes in I13 without mislabeling the compiler as self-hosted. ## Scope freeze during compiler construction E1, corpus expansion, UI stages, and new conceptual modules remain **referent-only** until the compiler usable-core work is deliberately released. They may be referenced for compatibility. They are not active construction targets. ## Whole-program acceptance — PASSED `examples/core.i13` passes: ```text i13 check examples/core.i13 i13 run examples/core.i13 i13 build examples/core.i13 -o core.wasm ``` The generated Wasm validates and instantiates in Node and matches the reference VM: ```text CORE_OK = 1 ROUTES = 56 ``` The compiler bootstrap also passes all three executable routes: ```text i13 check examples/compiler_bootstrap.i13 i13 run examples/compiler_bootstrap.i13 i13 build examples/compiler_bootstrap.i13 -o compiler-bootstrap.wasm ``` with `BOOTSTRAP_OK = 1` on the reference VM and generated Wasm. ## Current compiler status ```text SOURCE COMPLETE LEXER COMPLETE PARSER COMPLETE AST COMPLETE HIR COMPLETE SEMANTIC COMPLETE IVM COMPLETE VALIDATOR COMPLETE REFERENCE VM COMPLETE CLI CHECK COMPLETE CLI RUN COMPLETE CLI TRACE COMPLETE · I13-TRACE-0.1 CLI DEBUG COMPLETE · I13-DEBUGGER-0.1 CLI DUMP COMPLETE · TOKENS/AST/HIR/IVM CLI BUILD COMPLETE WASM CODEGEN COMPLETE · TAGGED VALUE MODEL FRAME LAW COMPLETE · I13_FRAME_LIMIT=4096 · VM=WASM STEP METER COMPLETE · deterministic 8M STEP FUSE LOCKED RUNTIME POLICY · non-semantic VM = WASM KNOWN-GOOD SEMANTIC SURFACE DIAGNOSTICS v0.1 FROZEN · SOURCE-MAPPED CONFORMANCE v0.1 FROZEN · CI-GATED INTROSPECTION v0.1 FROZEN · OBSERVER-ONLY TRACE v0.1 FROZEN · SINGLE-VM OBSERVER DEBUGGER v0.1 FROZEN · READ-ONLY CONTROL BOOTSTRAP v0.1 FROZEN · I13 SELF-USE · VM=WASM ``` This does **not** mean the language is feature-complete or self-hosting. It means the source-to-executable compiler path now has explicit semantic law, explicit runtime-policy boundaries, differential evidence, formal conformance, source-mapped diagnostics, static compiler introspection, execution-time introspection, interactive read-only debugging, and the first compiler-law workload written and executed in I13 itself while preserving one execution authority.