Codegen-Backend Trait and Dispatch

Goal

Fully flesh out the ori_codegen::CodegenBackend compile/finalize contract, make the CodegenBackendChoice dispatch backend-neutral at its own signature, and route every codegen-entry ori_llvm:: call site through it — collapsing the forked AOT/JIT emission projection and the codegen-entry #[cfg(feature = "llvm")] coupling down to one dispatch module.

Scope note on the #[cfg(feature = "llvm")] clause: 101 occurrences exist across oric/src; 86 sit outside this section’s in-scope six files, and the in-scope leader (11) is backend.rs, the dispatch module itself. This section collapses the codegen-entry subset only; the platform-toolchain occurrences stay out.

Context — verified terrain at head b1001be55

The terrain is a T, not a flat file list. The vertical is compile_common.rs -> backend.rs -> run_codegen_pipeline -> emit_realized_program. The crossbar is the AOT/JIT emission fork, which meets nowhere.

Dispatch surface (the central deliverable)

oric/src/commands/backend.rs (90 lines) is in this section’s touched set. It holds LlvmBackend:34, impl CodegenBackend for LlvmBackend:42, CodegenBackendChoice:76 (single variant Llvm), and CodegenBackendChoice::compile:83, declared -> Result<LlvmCodegenOutput<'ctx>, BackendError>. That concrete return type — not the trait’s method count — is what makes a second backend variant unrepresentable: the trait is already generic over an associated Artifact (ori_codegen/src/lib.rs:94), while the closed enum that dispatches it names one backend’s output type.

Contract crate

ori_codegen/src/lib.rs (98 lines, single file): BackendError:36, CodegenInput:62 (10 fields: pool, type_result, canon, source_path, module_name, symbol_prefix, target_triple, narrowing_policy, imported_type_metadata, imported_collection_surfaces), CodegenBackend:92. Its :9-21 doc-comment gates widening on types that do not yet exist.

Emission axis (the confirmed duplication)

Named-but-thin migration targets

No file in this section’s touched set exceeds the 500-line cap. The largest is pipeline.rs at 404.

Corrections to this section’s prior baseline

Out of scope (approved narrow-scope decision, unchanged)

The platform-toolchain subset — commands/build/*, commands/target*.rs, commands/demangle/*, llvm_dump/* (linking, mangling, target/sysroot resolution, executable packaging, process launch) — stays outside the backend trait. Reference-repo pain concentration corroborates this boundary: the highest-pain backend-abstraction issues in mature compilers (rust #107370, #109855, #113092, #113869) are all linker/SDK/LTO work-product concerns, none of which touch a trait seam.

Ownership and deferral boundary — what this section may author

Constrained symbols — do not reshape

prepare_analysis_products:154 and lower_arc_functions:257 outrank the emission functions on churn and betweenness and sit above this section’s boundary. Do not drag them in.

Emission-axis collapse — the section’s real deliverable

Source read of both sides in full at b1001be55 puts the shared skeleton at ~23 steps across the union: pool, repr_plan, ArcClassifier::new, TypeInfoStore::new_with_plan, TypeLayoutResolver::new, register_user_types, FunctionCompiler::new, bind_executable_program, declare_all, declare_mono_functions, declare_artifact_remainder, compile_impls_from_artifact, bind_executable_method_targets, bind_user_drop_targets, prepare_all_from_artifact, prepare_mono_from_artifact, prepare_artifact_remainder_from_artifact, compute_nounwind_set, emit_prepared_functions, apply_posthoc_nounwind, plus the error-count/description tail.

Detector-sizing rule: the parallel-drift sibling-divergence row for this pair scores jaccard 0.2727 with shared_count: 3, because emit_realized_program delegates the fan-out to emit_all_functions while the JIT side inlines it, so the callee-set comparison sees only the prologue. The detector understates this finding. Size the collapse from the source read, never from the row. The routing note’s “14 identical projection steps” figure is not derivable from any graph surface and is not used.

Parameterization surface — the genuine AOT/JIT deltas the shared projection must carry, not erase:

Sequencing: AOT-last. Shape the shared helper against the cold, isolated JIT side (compile_all_functions: hotspot 2.10, betweenness 0.0, span 124), then re-point the hot, high-betweenness AOT path (emit_realized_program: hotspot 95.66, betweenness 41.7).

Collapse completeness rule: covering only the 3-callee prologue leaves the LEAK:algorithmic-duplication open. Authoring a third emit_shared_program alongside the existing pair instead of parameterizing one is LEAK:reuse-bypass.

Collapse-target note: both halves already sit inside one graph community whose members are exactly the FunctionCompiler artifact-projection protocol they both drive. The shared helper’s module boundary exists; it does not need inventing.

Boundary disposition for ori_llvm:: importers

32 files under oric/src import ori_llvm:::

The undeclared 12: commands/run/mod.rs, db/mod.rs, debug_flags/{aims_ablation_phase5_core,aims_ablation_phase5_lineage,diagnostic_dumps}.rs, problem/codegen/{mod,tests}.rs, query/tests.rs, test/runner/{arc_lowering,llvm_backend}.rs, test/runner/llvm_backend/{compile,imports}.rs.

Each of the 12 gets an explicit disposition here — migrate through the dispatch, or a named exemption in the boundary set. s-522301d7 will assert that every ori_llvm:: import outside the designated dispatch module fires a violation; against today’s tree that is 26 files. Settling the exempt set here is what keeps that lint from landing red on work this section declared out of scope.

Hygiene constraints the design must satisfy

Evidence and verification contract

Coverage baseline (source-confirmed, independent of the stale test-topology facet): emit_realized_program, emit_all_functions, compile_all_functions, run_codegen_pipeline, realize_codegen_program, compile_module_with_tests, collect_annotated_sigs, declare_imported_functions, finalize_jit, and all four ori_codegen public items have zero direct and zero covering tests. The one exception is BackendError::from, reached only from the mirror-enum test file. oric/tests/backend_stub_conformance.rs:47-62 declares its own StubBackendChoice and never constructs the real CodegenBackendChoice (INVERTED-TDD:seam-injected-only-coverage + LAYER_GAP:production-entry-point).

Ordering is binding: the production-path pin lands before any migration. A migration that silently changed declaration order, the nounwind batch, main-wrapper emission, or export projection ships green against today’s suite.

Burden-sole caveat (.claude/rules/arc.md §STOP): this section changes emission orchestration, not ownership. Any RC delta observed is a regression signal, never an optimization lead, and any RC count quoted comes from the burden-sole stream (--emit-rc-remarks / rc-stats.sh --rc-remarks). A default-path RC count is false-green.

Negative pins (target/layout-mismatch, unsupported-artifact) are authored against the real enum. A negative pin written against a stub selector repeats the defect it exists to close.

Verification rule for graph claims: callers "run_codegen_pipeline" resolves 0 rows despite two confirmed call sites, history-coupling and CO_CHANGED_WITH return 0 rows for every emission-axis symbol, surprise-coupling returns 0 rows under a stale facet, and similar never bridges the AOT/JIT files. Blast radius for this section is source-derived only. Confirm every caller and coverage claim by source search before acting on it.

Prior-art decision rule

rustc_codegen_ssa is the right reference and is interrogated, not copied:

• Adopt the invariant: one whole-crate driver generic over the backend trait (rustc_codegen_ssa::base::codegen_crate, base.rs:681) delegating to the concrete backend (rustc_codegen_llvm::codegen_crate, lib.rs:353). rustc has one such driver; Ori has two. That asymmetry is this section’s axis.
• Adopt the DummyCodegenBackend shape (rustc_interface/src/util.rs:349) as the production-wired answer to the coverage gap: reachable from the real driver, not a test-local mirror.
• Reject ExtraBackendMethods’ width (traits/backend.rs:132 — allocator shims, module submission, CGU naming). CodegenBackend plus finalize + ArtifactRequest is two methods and one associated type; that is the end state. Importing rustc’s width is DESIGN:speculative-generality.
• Reject rustc’s partitioning / par_map / async module submission — no current requirement.
• Refute the direct transfer: rustc has no JIT path and never faced an AOT/JIT emission fork. It is prior art for the invariant, not for the fix. The collapse is a parameterized shared projection, Ori-shaped.

Trait-completeness bar (corroborated by rust #123119 and zig #15899): every declared trait method is genuinely implemented and reached by the real dispatch. The typeck-into-codegen back-edge zig #15899 describes is verified gone in Ori — register_resolved_collection_burdens now sits at oric/src/realization/program.rs:243, above the codegen boundary, with zero call sites in oric/src/commands/ or ori_llvm/.

Cross-plan contract

Read bytecode-vm#s-429b48fe and native-backend#s-3caa36e9 before freezing the compile/finalize signature — this section’s artifact type is their input.

Required reading before execution

1. plans/backend-boundary/content/shared-pre-codegen-orchestration--s-30e3c9a6.md in full — boundary, exclusions, cross-plan contract, do-not-unify carve-outs.
2. plans/backend-boundary/content/walking-skeleton--s-fdca8921.md, “Narrowed contract and deferral anchors” — the authority for narrowing the CodegenInput clause.
3. compiler_repo/compiler/oric/src/commands/backend.rs, all 90 lines.
4. compiler_repo/compiler/ori_codegen/src/lib.rs, all 98 lines.
5. pipeline.rs:298-404 and compile.rs:148-271 side by side, both in full.
6. compiler_repo/compiler/oric/tests/backend_stub_conformance.rs:47-62.

Spec references

.claude/rules/layer-coverage.md §1 (layer matrix) + §3.1 (mandatory L9 + L10 for compiler-scope sections); .claude/rules/finding-categories.md (LEAK:backend-ownership-calculus-fork, LEAK:algorithmic-duplication, LEAK:reuse-bypass, INVERTED-TDD:seam-injected-only-coverage, LAYER_GAP:production-entry-point, DESIGN:speculative-generality, GAP:conditional-fallthrough-not-exhaustive); .claude/rules/impl-hygiene.md WASTE-12 (500-line cap — no file in this touched set currently exceeds it); .claude/rules/arc.md §STOP (burden-sole RC measurement); .claude/rules/missions.md §ori_llvm (faithful emission; parallel emission paths fracture parity) and §Compiler (one validated executable artifact, consumed by every backend without re-derivation).

Work items

• Add oric/src/commands/backend.rs (the CodegenBackendChoice dispatch module — absent from this section’s declared file set even though it owns the section’s central deliverable) to this section’s touched files. Fix CodegenBackendChoice::compile (backend.rs:83-89, today -> Result<LlvmCodegenOutput<'ctx>, BackendError>) to return a backend-neutral EmittedArtifact via the trait’s generic Artifact associated type — this hardcoded concrete return type is the actual blocker on a second backend variant, not the trait’s method count. Flesh out CodegenInput’s fingerprint validation, backend-private Module ownership, typed ArtifactRequest, backend-neutral EmittedArtifact, and BackendError; declare a blocked-by dependency on plans/repr-opt section 13 for the TargetSpec/CompiledLayoutPlan fields instead of inventing them here — that section is not-started and owns those types exclusively, already named as their deferral target by s-fdca8921. Collapse the full emission axis (codegen_pipeline/pipeline.rs:298 emit_realized_program / pipeline.rs:347 emit_all_functions vs ori_llvm/src/evaluator/compile.rs:148 compile_all_functions, the confirmed ~23-step shared skeleton, not only the 3-callee prologue the parallel-drift detector surfaces) into one shared parameterized projection, sequenced AOT-last: shape the helper against the cold, isolated JIT side first, then re-point the hot, high-betweenness AOT path. Migrate finalize.rs, imported_mono.rs, pc2_hooks.rs, and compile_common.rs through CodegenBackendChoice with target/layout-mismatch and unsupported-artifact negative pins driven against the real enum (built on the production-path pin work item). Declare a disposition — migrate or explicit exemption — for the 12 currently-undeclared ori_llvm::-importing files (under commands/run/, db/, debug_flags/, problem/codegen/, query/tests.rs, test/runner/) before s-522301d7’s boundary-hygiene lint lands and flags them as unowned violations.
• Land a production-path pin BEFORE any migration: drive the real oric::commands::backend::CodegenBackendChoice end-to-end through ori build and ori test --backend=llvm, asserting the real emitted artifact. Every symbol on the emission axis (emit_realized_program, emit_all_functions, compile_all_functions) currently has zero direct and zero covering tests; the sole existing pin, oric/tests/backend_stub_conformance.rs:47-62, constructs a local StubBackendChoice enum documented verbatim as mirroring CodegenBackendChoice’s shape — it never constructs the real enum (TEST-14 / LAYER_GAP:production-entry-point). This item establishes real dispatch coverage first so the subsequent contract-fleshing, emission-axis collapse, and file migration cannot silently change declaration order, the nounwind batch, or export projection without a test noticing.

Intel dossier — pointer and tier disposition

Dossier: codegen-backend-trait-and-dispatch--s-90024726.intel.md (this section’s content/intel/ sidecar)

Read that dossier from line 1 through EOF before acting on this section. This block is a pointer and an audit record, never a substitute: not the BLUF, not a summary, not selected tiers.