0%

Section 01: Evidence and Physical Layout Split

Context

The live compiler already has EnumLayoutInfo, compute_enum_layout_info, slot_padded_size, slot_count, ReprPlan::enum_layout_info, and a population pass. The old section’s additive API work has therefore landed, but its architecture is not the final cross-backend shape.

The current object embeds LLVM-oriented aggregate indices, native ABI size, and i64-slot packing in ReprPlan. It also uses one representative variant for payload offsets, reduces runtime ABI to a boolean, uses saturating conversions for layout arithmetic, and coexists with enum_repr_with_fallback. This section migrates that implementation in place. It must not create a second enum-layout computer beside the old one.

Required End State

EnumReprEvidence in ExecutableProgram
  semantic variants and stable field identities
  representation constraints and candidate proofs
  no selected physical layout

VmLayoutPlan::VmEnumLayout
  VM tag and payload storage
  verifier-visible access classes
  safe handle policy and canonical fallback

CompiledLayoutPlan::CompiledEnumLayout
  selected encoding for one TargetSpec
  checked size/alignment/tag width
  per-variant physical field locations
  typed runtime/FFI ABI classification
  shared by ori_llvm and ori_backend

LLVM GEP terminology, LLVM types, BIR/MIR nodes, VM opcodes, and mutable session state are forbidden from the shared evidence and compiled plan.

01.1 Boundary Types and Baseline Pins

  • Query the intelligence graph first, then census every live producer and consumer of EnumRepr, EnumTag, EnumLayoutInfo, enum_layout_info, enum_repr_with_fallback, slot_padded_size, slot_count, enum size/alignment, and runtime enum ABI. Verify every graph result in the dedicated compiler worktree and record stale graph edges as evidence, not truth.
  • Define EnumReprEvidence as a pure immutable record of semantic variant/field identity, explicit #repr and visibility constraints, tag cardinality, admissible niche/tagged-pointer candidates, proof provenance, and forced-canonical reasons. A candidate is not a selected target or VM encoding.
  • Replace is_runtime_abi: bool with a closed typed constraint such as EnumAbiConstraint::{Internal, Runtime(RuntimeAbiId), C(ReprCId)}. Define the exact owner of each runtime declaration and fail when a required contract is absent or incompatible with TargetSpec.
  • Define CompiledEnumLayout inside CompiledLayoutPlan with stable type and variant IDs, selected encoding, tag representation, checked size/alignment, payload storage, and a physical location for every semantic field of every variant. Use backend-neutral aggregate-element or byte-location vocabulary; an LLVM GEP index is adapter output, not plan data.
  • Define VmEnumLayout inside VmLayoutPlan with logical tag storage, register/heap payload schema, verified handle class, drop/trace schema, and explicit canonical fallback. A low-bit tagged handle is admitted only when verifier and heap-handle construction make forging or type confusion impossible.
  • Write TDD boundary matrices before migration: multi-variant heterogeneous payloads, equal-size variants with different field shapes, unit-only, single-variant, generic residue, recursive payloads, explicit repr/FFI, runtime ABI, niche candidate, tagged-pointer candidate, and unsupported-target fallback.
  • Pin crate dependency direction and public APIs: ori_target contains pure target identity; ori_repr may depend on it for compiled planning; ori_vm, ori_llvm, and ori_backend depend on the immutable plan; no reverse edge or backend callback is permitted.
  • Add compile-fail or visibility tests where practical so emitters cannot construct or mutate layout entries, and add negative validation tests for missing fields, duplicate stable IDs, impossible alignment, unsupported encoding, ABI mismatch, and unchecked offset overflow.

01.2 In-Place Migration and Closure

  • Split the current EnumLayoutInfo implementation in place. Move semantic candidates and constraints into EnumReprEvidence; move target physical fields into CompiledEnumLayout; do not leave a parallel EnumLayoutInfo computation after migration.
  • Build CompiledEnumLayout once from &ExecutableProgram, &EnumReprEvidence, and explicit &TargetSpec. Use checked arithmetic and typed errors throughout; saturating offsets, u32::MAX sentinels, guessed alignment, and host-target defaults are forbidden.
  • Build VmEnumLayout once during bytecode compilation from the same evidence plus explicit VM policy. Keep VM packing helpers in ori_vm; keep target byte-layout helpers in the compiled-layout kernel. A helper belongs in shared code only when both physical branches use identical units and semantics.
  • Replace representative-variant payload offsets with a total mapping keyed by stable (variant, semantic_field) identity. Validate that construction, projection, match, drop, derive, debug formatting, and ABI lowering resolve through that same map.
  • Remove ReprPlan::enum_repr_with_fallback and every on-demand enum canonicalization/layout path after producers are complete. ExecutableProgram::validate, VmLayoutPlan::validate, and CompiledLayoutPlan::validate must reject missing entries before execution or emission.
  • Preserve current LLVM output before enabling new encodings: snapshot structural LLVM IR and runtime ABI fixtures for representative enums, migrate the owner, then prove the post-migration LLVM path is behaviorally and structurally equivalent except for intentional stable naming.
  • Add deterministic equality, hashing, serialization/fingerprinting, and stable-order tests for evidence and both layout plans before bytecode cache, AOT cache, or JIT cache may use them as keys.
  • Update plans/repr-opt §13, plans/bytecode-vm, plans/backend-boundary, and plans/native-backend contracts in the same section close so no sibling plan still treats the landed native-shaped EnumLayoutInfo as the final SSOT.

01.3 Completion Checklist

  • EnumReprEvidence is complete, immutable, target-neutral, and free of selected physical layout.
  • CompiledEnumLayout is complete for every compiled enum and explicit TargetSpec, with per-variant field maps and typed ABI constraints.
  • VmEnumLayout is complete for every bytecode enum and verifier-safe under malformed bytecode and forged-handle attempts.
  • The existing EnumLayoutInfo physical fields no longer live in ReprPlan; any temporary adapter is deleted.
  • No enum representation or layout fallback survives closure; validation fails before eval, VM execution, LLVM emission, or ori_backend emission.
  • Target-specific packing and VM packing have one owner each; shared helpers have identical units and semantics for all consumers.
  • Baseline and negative matrices pass in debug and release, including non-host target layout fixtures.
  • Third-party review is clean and all validated findings are fixed in the plan or implementation.
  • Implementation-hygiene and documentation-sync gates are clean after the third-party review.

01.R Third Party Review Findings

  • The prior section assumed EnumLayoutInfo did not exist. Live source disproves that assumption; this rewrite makes migration of the landed partial implementation the section’s first responsibility.
  • The prior API made one maximum-payload variant stand in for all variants. The production layout requires stable per-variant field identity so codegen cannot interpret offsets under the wrong shape.
  • The prior plan placed physical layout and AIMS tag-field queries in the same object. The revised boundary forbids AIMS from consuming either compiled or VM layout.

Fresh intel note

The existing intel package predates the current compiler worktree. Use it only to seed queries; verify every symbol and edge against live source before execution.