# Backend Simplification Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Replace the hard-coded Python/Rust codegen backends with a small trait-based backend interface and a single default Numba backend, while keeping the CLI purely interpretive.

**Architecture:** Introduce a `Backend` trait in the `backend` module that emits kernels from `TypedDag`, implement a `NumbaBackend` that generates inline Numba-decorated Python kernels, remove the old `emit_python` / `emit_rust` functions and CLI `--codegen` option, and update tests and docs to point to the new abstractions.

**Tech Stack:** Rust 2024, existing Gonidium IR and optimisation pipeline, Python/Numba at the codegen boundary (as generated source only).

---

### Task 1: Introduce Backend trait and NumbaBackend type

**Files:**
- Modify: `src/backend/mod.rs`
- Create: `src/backend/numba.rs`

**Step 1: Define Backend trait in backend module**

- Add a `Backend` trait that takes `&TypedDag` and a `fn_name: &str` and returns an associated `Output` type.

**Step 2: Implement NumbaBackend struct and Backend impl**

- Create `NumbaBackend` as a zero-sized struct.
- Implement `Backend for NumbaBackend` with `type Output = String` and an `emit_kernel` method that will call internal helper functions to generate Numba-decorated Python source.

**Step 3: Re-export trait and default backend from lib.rs**

- Update `src/lib.rs` to re-export `Backend` and `NumbaBackend` alongside the existing interpreter exports.

### Task 2: Port Python codegen logic into Numba backend

**Files:**
- Modify: `src/backend/numba.rs`
- Delete: `src/backend/python_gen.rs`
- Delete: `src/backend/rust_gen.rs`

**Step 1: Copy traversal structure from python_gen into Numba backend**

- Implement the node traversal and code-emission logic inside `NumbaBackend::emit_kernel`, based on the existing `emit_python` implementation (discover used nodes, emit temporaries `t{idx}`, build return expression).

**Step 2: Add Numba-specific header and decorator**

- Emit `import numba` plus `import math` at the top of the generated source.
- Emit `@numba.njit` immediately before the `def fn_name(...):` line.

**Step 3: Fix small issues from review while porting**

- Replace the `unwrap_or("arg")` fallback for parameters with an explicit `expect` on the params vector.
- Replace the `unwrap_or(0)` call argument index with a strict `expect` that calls must have at least one argument.

**Step 4: Remove old Python/Rust backends**

- Delete `python_gen.rs` and `rust_gen.rs` and clean up any references in `backend::mod`, `lib.rs`, tests, and docs.

### Task 3: Simplify CLI to interpret-only

**Files:**
- Modify: `src/bin/gonidium.rs`

**Step 1: Remove codegen-related parser options**

- Remove the `codegen: Option<String>` field from `Run`.
- Remove the `--codegen` option from `run_parser` and associated help strings.

**Step 2: Remove codegen branch in run_command**

- Delete the `if let Some(kind) = codegen.as_deref()` branch that calls `emit_python` / `emit_rust`.
- Ensure `run_command` always follows the parse → lower → (optional optimise) → interpret path.

**Step 3: Adjust help and error messages**

- Update CLI help text to no longer mention codegen or Python/Rust backends.

### Task 4: Update tests to use Numba backend

**Files:**
- Modify: `tests/codegen_backends.rs`
- Modify: `tests/e2e_opt_codegen.rs`

**Step 1: Point tests at NumbaBackend instead of emit_python/emit_rust**

- Update imports to use `NumbaBackend` (and `Backend` if needed) from `gonidium`.
- Replace direct calls to `emit_python` / `emit_rust` with `NumbaBackend.emit_kernel(...)`.

**Step 2: Update assertions to reflect Numba output**

- Assert that the generated source contains `import numba`, `@numba.njit`, and a `def kernel(...):` signature.
- Keep and adapt the special float constant tests to check for `float('inf')`, `float('-inf')`, and `float('nan')` in the Numba backend output.

**Step 3: Run tests and ensure they pass**

- Run: `cargo test codegen_backends e2e_opt_codegen`
- Expected: All updated tests pass without compilation errors.

### Task 5: Update docs and config references

**Files:**
- Modify: `README.md`
- Modify: `docs/config.md`

**Step 1: Update pipeline description in README**

- Change the backend description from `emit_python` / `emit_rust` to a generic `Backend` trait plus the default `NumbaBackend`.

**Step 2: Update backend section in config docs**

- Replace references to `emit_python` / `emit_rust` with references to the new backend trait and the default Numba backend.

**Step 3: Run full test suite**

- Run: `cargo test`
- Expected: All tests pass, confirming that the refactor did not break existing behaviour.
