0%

s03 — Architecture Design + Design-Validation Gate

Goal

The locked, falsifiable design documents for every backend subsystem — BIR, function-granular compilation, ArchConfig/MIR, regalloc, object/link, caches, deterministic parallelism, bounded optimizing tiers — plus a prototype-strategy design-validation gate that must PASS before any implementation section starts.

Implementation Sketch

Design docs in content/, decision records for every contested choice; inputs are the s01/s02 dossiers, backend-boundary, and repr-opt#13 (boundary surfaces verified live before the gate):

  • Shared-input design: ori_codegen::CodegenInput { ExecutableProgram, TargetSpec, CompiledLayoutPlan } is the complete codegen input. BIR may reference stable layout/ABI IDs from that plan; it cannot compute field offsets, enum encodings, FunctionAbi, RC headers, or runtime declaration attributes itself. The design includes backend-private Module ownership and typed finalize() to a relocatable native object or complete WASM module, with no native-specific artifact branch in oric.
  • Enum design follows plans/enum-layout-ssot: BIR names semantic variant/field IDs plus a CompiledEnumLayout ID; the backend adapter resolves the shared per-target decision and never ports LLVM TagAccess classification logic.
  • BIR design: SoA storage (parallel tags/data arrays + u32 extra pool, per-function instance), block parameters (matching ArcFunction — compiler_repo/compiler/ori_arc/src/ir/mod.rs:387), value model, type references as Idx into the existing Pool, fact side-tables (index-aligned maps; SLOTS reserved now: effects, return-provenance, reuse-events, uniqueness — populated at s18), span provenance through lowering, and verifier invariants (use-before-def, block connectivity, and exact preservation of each post-AIMS logical event’s stable identity, multiplicity, order, transfer edge, and cleanup obligation). Translation binds every event to an action selected by the matching CompiledLayoutPlan; it never reclassifies the event. A target may spell, fuse, or omit physical counter actions only when its compiled-plan satisfaction proof validates the result. AIMS invariant 5 therefore forbids a second ownership-policy analysis; it does not require every backend to reproduce a verbatim RC-op multiset.
  • Compilation-unit and invalidation design: one stable CodegenUnit per function over immutable session tables plus worker-local scratch. Freeze FunctionCodegenKey inputs: realized-function semantic hash; target triple/features; only the referenced CompiledLayoutPlan/ABI entries; typed-fact and runtime-ABI schema versions; tier/pass-pipeline config; and exact callee/body dependencies for cross-function transforms. A body-only callee change cannot invalidate callers unless a transform actually consumed that callee body/fact; an ABI/layout/fact change invalidates the declared dependency closure. Native codegen contains no module-wide mutable pass state.
  • ArchConfig + MIR design: per-arch config (register lists, masks, lower fns), MIR-per-arch shape (SoA again), the wasm virtual-register arch (OnWasmStack flag model), encoder interfaces.
  • Regalloc design: schedule pass contract, liveness, greedy linear scan over u64 masks, spill heuristic, block-param handling (no phi insertion), symbolic checker contract (input: pre/post-alloc MIR; verdict: per-edge value-location consistency).
  • Object/link/cache design: every function finalizes to a target-specific CompiledFunctionFragment containing code/body bytes, constants, relocations, symbols, and unwind/debug contributions. A content-addressed cache stores fragments independently. Stable-ID-ordered finalization, never worker completion order, merges fragments into an object-crate artifact or complete WASM module and drives the system linker (reuse LinkerFlavor plus RuntimeConfig::detect()). The design records finalization/link cost separately and specifies the escalation point to stable object partitions or the s22 in-memory shape if relinking prevents the end-to-end gate.
  • Tier and budget design: fast tier = BIR -> MIR -> emit with zero mid-end; optimizing tier = bounded mid-end over BIR then the same function pipeline. Freeze an OptimizationBudget contract with deterministic, input-size-derived rewrite/visit fuel and IR-node/growth limits per pass and per function. No wall-clock cutoff, unbounded saturation, or convergence-only loop is admissible. Exhaustion returns the last verifier-clean BIR and structured telemetry. Cross-function transforms read immutable summaries/bodies and add exact key dependencies. Record the dev-mode shape decision (quick-AOT vs in-memory) for s22.
  • Parallelism design: jobs=1 and jobs=N schedule independent cache misses; shared inputs are immutable, scratch is worker-local, diagnostics are stably sorted, and final artifacts are byte-identical across worker count and cache-hit order. The design names every serial phase and proves there is no backend-global lock.
  • Design-validation gate: falsifiable criteria — (1) BIR can represent every ArcInstr/terminator incl. unwind edges without loss (paper-walk all 21+8 variants); (2) fact side-table slots cover every s18 surface field; (3) LLVM and ori_backend consume the identical shared compiled layout/ABI fixtures with no circular dependency or fallback classifier; (4) direct compiled WASM fits the ArchConfig frame and complete-module path on paper without VM/evaluator participation; (5) two unrelated functions can compile concurrently from immutable inputs and merge byte-identically to jobs=1; (6) one body-only edit invalidates exactly one fragment when no declared cross-function transform consumed it; (7) every proposed optimizing pass has deterministic fuel/growth accounting and a safe exhaustion result; (8) /tpr-review of the design docs returns clean or all findings cured. Gate FAIL routes back into design, never forward.

Constraints

  • Design docs are plan content, not compiler source; no compiler edits in this section.
  • Every design claim grounded to dossier or verified boundary facts; UNVERIFIED flags resolved before the gate.

Work Items

  • Shared-input, private-module, per-function CodegenUnit/FunctionCodegenKey, typed artifact-finalization, and BIR design doc (ori_codegen::CodegenInput over ExecutableProgram + TargetSpec + CompiledLayoutPlan, storage, exact dependency invalidation, block params, fact-slot reservation, verifier invariants, logical-event coverage, compiled-plan satisfaction, and layout-preservation rules) + decision records.
  • ArchConfig + per-arch MIR + encoder-interface design doc covering all 5 targets incl. the wasm virtual-register model.
  • Regalloc + schedule-pass + symbolic-checker design doc.
  • Function-fragment cache + deterministic object-emission/link strategy doc (fragment schema, cache/version keys, stable merge, relocation set per ISA, wasm module writer, linker driving, runtime discovery reuse, measured escalation point).
  • Tier/parallelism/budget design doc (fast/optimizing boundaries, deterministic optimizer fuel and growth limits, immutable shared state, worker-local scratch, stable diagnostics/finalization, dev-mode shape decision for s22).
  • Design-validation gate executed: all falsifiable criteria evaluated with artifacts, /tpr-review on the design set clean; PASS recorded before s04 starts.