<!-- informative -->

# Code Organization Report

Review of `src/orchestrator/` covering module organization, KISS and DRY
violations, and dead code. No code was changed; findings only. Line numbers
refer to the tree at the time of review.

Scope: ~17k LOC across 30 modules. Two files dominate: `experiment.py` (3299
lines) and `controller.py` (2972 lines) — 37% of the codebase. Then
`conformance.py` (1551), `reducer.py` (1157), and `sandbox.py` (970).

## Summary

1. **Split `experiment.py`** (hidden oracle, trial driver, target fixture, and
   hashing utils into their own modules); **extract 4–5 satellite modules from
   `controller.py`** (errors, read model, approvals, run limits) but keep the
   admission state machine whole.
2. **Biggest single refactor**: `reducer.reduce` → dispatch table.
3. **Highest-risk DRY**: executor base class (token/cache/cancel/lock + shared
   response envelope) and a single amount-validator — 3–6 copies of
   safety-relevant behaviour exist today.
4. **Mechanical cleanup**: ~20 dead symbols, 7 unused imports, 5 unused locals,
   3 dead parameters, 1 missing `Tuple` import.
5. **Correctness smells** found along the way (worth tickets even without
   refactoring): fail-open `passed` default in `_normalise_inline_checks`,
   `_model_review` ignoring its `limits` arg in favour of a mutable module
   global, divergent rounding between live and recovery settlement, drifting
   acceptance idempotency keys, and `restore_credentials` never being called by
   recovery.

## Should `experiment.py` and `controller.py` be divided?

### `experiment.py` — yes, split it

It mixes at least seven unrelated concerns:

| Concern | Lines | Suggested home |
|---|---|---|
| Hash/freeze/canonical-JSON utils | 3206–3255 | `hashing.py` (tests already import these as API) |
| Git/worktree/env plumbing (`_git`, `_materialise`, `IntegrationTree`) | 1224–1259, 3258–3299 | `git_ops.py` |
| Fixed-target fixture (toy parser project as string literals) | 321–542 | `experiment_target.py` |
| Hidden oracle suite (drivers, collector, grading) | 545–851 | `hidden_oracle.py` — a complete R08 sandbox-isolation subsystem |
| Manifest + arms + limits + model profile | 98–314, 858–1139 | `experiment_spec.py` |
| Trial machinery (drive, batch, repair, metrics) | 1401–2574 | `trial_driver.py` + `trial_metrics.py` |
| Experiment phases (calibration, pilots, comparison) | 1266–3182 | `experiment_phases.py` |

Keep `experiment.py` as a re-export façade so `tests/*` and
`scripts/smoke_run.py` imports do not break. The strongest cuts are the hidden
oracle, the trial driver, the target fixture, and the hashing utils.

`select_ready_action` and `plan_decomposition` (1147–1216) are control-plane
policy, not experiment logic; they belong near `decomposition.py`/`policy.py`.

### `controller.py` — partial split only

The core is one coherent admission-thread state machine and should stay
together (splitting it would force a shared mutable context or thread 4–6
dependencies through every signature — a net loss). But ~600–700 lines are
ride-along concerns worth extracting:

| Extract | Lines | Why |
|---|---|---|
| Exception hierarchy → `errors.py` | 51–98 | Zero controller coupling; used by 12+ files |
| Read model (8 `get_*` methods) → `read_model.py` | 2830–2908 | Pure queries over `EventStore` |
| Approval lifecycle → `approvals.py` | 1900–2136 | Own event family, own timers |
| Run-limit enforcement → `run_limits.py` | 157–310 + 935–975 | Self-contained R03 policy engine |
| Module helpers | 2911–2972 | Fold into `secrets.py` / `acceptance_checks.py` / a shared module |

The residual `Controller` (~2200 lines) is long but topically unified and
defensible.

### Other size offenders

- **`reducer.reduce()`** is a ~780-line function with 25 `if et == "..."`
  branches (`reducer.py:380–1157`). Convert to a `{event_type: handler}`
  dispatch table. Biggest readability win in the repo.
- **`conformance.py`** conflates corpus recording, crash simulation,
  fingerprinting, coverage instrumentation, a suite runner, and oracle
  calibration. Split into `conformance_corpus` / `conformance_fingerprint` /
  `conformance_coverage`.
- **`decisions.py`** is ~85% frozen prose data (`DEFERRED_DECISIONS`, 210
  lines). Externalize as YAML/JSON like `docs/tables/*.yaml`.

## KISS violations

### Long multi-concern functions

- `controller.admit_observation_and_result` (`controller.py:1231–1488`, 258
  lines) — validation, redaction, cost reconciliation, result/artefact
  admission, model outputs. At least 4 extractable phases.
- `controller.dispatch_attempt` (`controller.py:977–1229`, 253 lines) — happy
  path plus a 6-branch `except` ladder of emit-then-settle-then-raise.
- `experiment.run_trial` (`experiment.py:1884–2069`) and
  `_TrialRecorder.finish` (`1665–1850`) — ~186 lines each.
- `experiment._execute_leaf_batch` (`2345–2440`) — three nested recovery
  strategies in one body.
- `model_adapter.ModelAdapter._dispatch` (`model_adapter.py:516–632`) — and
  `required_max_charge` re-validates the request a second time (`506` vs
  `529`).
- `sandbox.SandboxRunner.run` (`sandbox.py:591–799`) — teardown/fail-closed
  block written twice (`770–783` vs `784–794`); `timed_out = False` assigned
  twice (`678`, `692`).
- `controller.propose_decomposition` (`646–802`) — five sequential phases in
  one body.

### Convoluted / clever-but-opaque

- `experiment.calibrate_oracle` (`1305–1343`) — five-way `if/elif` on `case_id`
  strings where the `else` silently means "infrastructure case"; should be a
  table next to `_CALIBRATION_CASES`.
- Side effect hidden in a payload expression: `controller.py:2130–2131` —
  `"evidence_ids": list(...) or [self._admit_inline_evidence(...)]`.
- Code-as-string generators: `experiment._collector_script` (`639–690`) and
  `_write_script` (`2708–2715`) — unlintable, untypecheckable generated Python.
- Import-time `assert` at `experiment.py:697` — vanishes under `python -O`.
- `experiment.run_measured_comparison` (`3015–3035`) — nested ternaries inside
  `dataclasses.replace` inside a comprehension.
- `conformance.py:1288` — `old_root = state.nodes[state.root_node_id] if False
  else None`.
- `_normalise_inline_checks` (`controller.py:2938`) — `check.get("passed",
  True)`: a check without `passed` **defaults to passing** in an acceptance
  path. Fail-open.
- `_emit`'s `policy_version: int = 1` sentinel (`controller.py:424–425`) makes
  an explicit `1` indistinguishable from "use run's version"; `None` would be
  honest.

### Unnecessary abstraction

- `attempt_id_placeholder` (`controller.py:2965`) — `return
  attempt.attempt_id`.
- `_scheduling_order` (`controller.py:2969–2972`) — one-line wrapper with a
  deferred import; no import cycle exists.
- `ArmDefinition` (`experiment.py:123–139`) — 4 of 5 fields never read; only
  `concurrent_workers` matters.
- `PILOT_ORDER = ARM_ORDER` (`experiment.py:120`) — pure alias.
- `glossary.py:38–150` — 24 copy-pasted one-line `@lru_cache` accessors; one
  `catalogue(heading)` would do.
- `model_provider.py` — 100% speculative groundwork;
  `ModelRoutingNotSupported` is never raised.

## DRY violations

### Cross-module (highest impact)

1. **Numeric validation ("reject bool/non-numeric/non-finite/negative")
   implemented 6×**: `model.require_amount:27`, `reducer._payload_amount:91`,
   `model_adapter._finite_cost:69`, `executor_protocol._require_finite:118`,
   `spend._require_amount:83`, `schemas._positive_number:103`. Plus
   `controller._commitment_amount:2946` =
   `reducer._commitment_amount:109` forked verbatim (different exception,
   untyped).
2. **Executor dispatch scaffolding copy-pasted 3×** — `issue_token` / response
   cache / cancel / `_dispatch_lock` in `executor.py:53–91`,
   `model_adapter.py:471–527`, `command_executor.py:84–129`. `ScriptedExecutor`
   drifted (no lock). Response envelope built by hand in
   `model_adapter.py:590–630` and `command_executor.py:219–244` with no shared
   `build_response`. Safety-relevant: crash-recovery claims depend on identical
   cache behaviour.
3. **Ledger semantics duplicated** — `model.Ledger` (`model.py:212–448`) vs
   `spend.ExperimentSpendLedger` (`spend.py:92–238`); `TOLERANCE = 1e-9`
   defined 3× (`model.py:24`, `spend.py:26`,
   `model_adapter.COST_TOLERANCE:50`).
4. **`TOOLCHAIN_PATHS` 13-entry tuple defined 4×**: `experiment.py:3189`,
   `conformance.py:60`, `tests/test_milestone3_sandbox.py:34`,
   `tests/test_milestone3_acceptance.py:32`. `GIT_ENVIRONMENT` defined 3×.
5. **Budget-id fallback `contract.get("budget_id") or f"{node_id}-budget"` in
   4 places**: `reducer.py:142`, `reducer.py:433`, `decomposition.py:204`,
   `retry_policy.py:62`.
6. **`sha256:` + `hashlib.sha256` digest helpers 5+ times**
   (`executor_protocol.content_hash:57`, `sandbox._sha256:291`,
   `worktree.py:87/101/432`, `model_adapter.py:360/366`,
   `conformance.py:124`) — and `experiment._accept:2489` hand-rolls a sixth
   instead of using its own `_content_hash`.
7. **Two graph-cycle detectors**: `decomposition._ensure_acyclic:240` vs
   `reducer._dependency_would_cycle:344`. **Two path-pattern engines**:
   `executor_protocol:286–347` vs `decomposition:264–300`.
8. **`limits.yaml` re-read uncached in 3 modules** (`decomposition.py:40`,
   `retry_policy.py:33`, `experiment.py:186`) despite `tables.load` caching.
   `schemas.RUN_LIMIT_KEYS:137` is a third hand-synced limits list.
9. **Catalogue drift risk**: `policy.CONFLICT_RESOLUTION_REGISTRY` keys never
   checked for coverage of `glossary.conflict_types()`;
   `events._attempt_cause_values:100` hard-codes `("INITIAL","RETRY")` against
   the "never redefines a value" convention; `oracle.py:22–44` re-declares
   glossary-owned grade values.

### Inside `controller.py`

10. `BUDGET_EXHAUSTION_RECORDED` emit+raise block ×7 (`212`, `228`, `253`,
    `879`, `892`, `900`, `1177`).
11. Validation→acceptance event triple ×4 with **drifting idempotency keys**
    (`1725–1770` uses `accept-{node}-{cycle}`; `2194–2219`, `2247–2271`,
    `2105–2135` omit the cycle suffix). Related:
    `resume_deferred_acceptance` computes the cycle twice around an emission
    (`2109` vs `2115`) so STARTED and PASSED embed different cycles.
12. Terminal-attempt tuple
    `("RESULT_PRODUCED","FAILED","TIMED_OUT","CANCELLED")` hard-coded ×4
    (`498`, `1386`, `2549`, `2795`) while `tables.attempt_table().is_terminal`
    exists and is used elsewhere.
13. `run_model_review:1874–1877` body == `execute_attempt:2529–2532` body
    character-for-character.
14. Settle/reclaim logic 3× with **divergent rounding order**:
    `round(max(0.0, …), 9)` at `1362` vs `max(0.0, round(…, 9))` at `2738`.
15. `f"{attempt_id}-result"` result-id convention string-literalled in ≥4
    files (`controller.py:373/1383`, `experiment.py:2473`,
    `conformance.py:178`, tests).

### Inside `experiment.py`

16. Grade+infra-rerun pipeline duplicated: `_calibrate_case:1359–1369` ≈
    `_grade_trial:2563–2573`.
17. Repair-policy logic triplicated: `_drive_repair_terminal:2221`,
    `_advance_repair:2244`, inline in `_accept:2493`.
18. `ExecutorFailed` handling copy-pasted 3× (`2287`, `2308`, `2359`),
    including the literal `"sha256:executor-failed"`.
19. `_process_ready_node`/`_process_children`'s `arm` param only feeds
    `direct=(arm == ARM_DIRECT)`, which is **always `False`** (`_run_arm`
    returns early for DIRECT at `2087–2089`) — 6 call sites threading a dead
    parameter.

## Dead code

### Unused functions (repo-wide zero callers, verified by grep)

| Symbol | Location |
|---|---|
| `attempt_id_placeholder` | `controller.py:2965` |
| `settle_attempt_conservatively` | `controller.py:1880` |
| `supersede_node` | `controller.py:2419` (tests bypass it via `controller._emit`) |
| `restore_credentials` | `controller.py:314` — **or a recovery hole**; docs mandate it, `experiment.recover` never calls it |
| `decomposition._child_ids` | `decomposition.py:46` |
| `decomposition._mandatory_criteria` | `decomposition.py:50` |
| `executor_protocol.REQUEST_SCHEMA_VERSION` | `executor_protocol.py:30` |
| `executor_protocol.STATUS_TO_ATTEMPT_RESULT` | `executor_protocol.py:41` (mapping re-hard-coded at `:350`) |
| `executor_protocol.content_hash` | `executor_protocol.py:57` |
| `model_provider.ModelRoutingNotSupported` | `model_provider.py:29` (never raised) |
| `CommandExecutorConfiguration.owned_scope_exclude` / `.environment_version` | `command_executor.py:56/46` (never read) |
| `sandbox.SandboxObservation.violated` | `sandbox.py:227` |
| `sandbox._sha256` / `sandbox._libc` | `sandbox.py:291/295` |
| `worktree.TreeManifest.paths` | `worktree.py:97` |
| `paths.EVENT_CATALOGUE_PATH` | `paths.py:12` |
| `oracle.GRADE_NOT_EXECUTED` | `oracle.py:27` (value produced by no path) |
| `events.EventSpec.current_schema_version` | `events.py:86` |
| `oracle.OracleManifest.criteria_for` | `oracle.py:84` (weak) |
| `tables.Transition.guard` | `tables.py:52` (stored, never read) |

### Unused imports and variables (confirmed by `ruff --select F401,F841`)

- Unused imports: `acceptance_checks.py:20` (`Dict`), `conformance.py:34`
  (`acceptance_checks`, `model_adapter`), `conformance.py:49` (`snapshot`),
  `observability.py:22` (`Dict`), `oracle.py:20` (`Any`), `policy.py:136`
  (`re`), `store.py:40` (`Path`).
- Unused locals: `conformance.py:320/669` (`root`), `conformance.py:1288`
  (`old_root`, from `... if False else None`), `controller.py:2365`
  (`replanned`), `controller.py:2420/2448` (`state`).
- Write-only: `controller.cancel_run`'s `cancelled` list (`2550–2553`),
  `IntegrationTree.integrated` (`experiment.py:1241/1258`),
  `conformance.CorpusRun.description`.

### Dead parameters

- `build_hidden_oracle(target)` — `target` never read
  (`experiment.py:782–803`).
- `_model_review(..., limits)` — `limits` never read; bills the global
  `MODEL_PROFILE` instead (`experiment.py:2443–2455`) — also a correctness bug
  if a caller passes a non-global profile.
- `conformance._completed_script(run_id)` / `_timeout_script(run_id)` —
  `run_id` unused (`conformance.py:120–137`).

### Unreachable / vacuous code

- `conformance.py:842–846` — `elif index == 3:` unreachable (`continue` at
  `:815`).
- `controller.py:1400–1404` — empty `elif ... : pass` branch.
- 4 of 5 `_pilot_invariants` checks (`experiment.py:2869–2881`) are vacuous —
  the compared fields are constants copied into every observation.

### Latent bug (dead binding)

- `controller.py` uses `Tuple[...]` at `200`, `1495`, `1506`, `1864` but never
  imports it (`from typing import …` at line 31 lacks `Tuple`). Only
  `from __future__ import annotations` prevents `NameError`;
  `typing.get_type_hints()` would fail.

## Correctness smells (follow-up tickets)

These surfaced during the review and are independent of any refactor:

1. **Fail-open check default** — `_normalise_inline_checks`
   (`controller.py:2938`) treats a check without `"passed"` as passed, in an
   acceptance path whose docstrings insist a model assertion cannot substitute
   for deterministic evidence.
2. **`_model_review` ignores its `limits` parameter** and bills the mutable
   module global `MODEL_PROFILE` (`experiment.py:2443–2455`, also metrics at
   `1846`); `scripts/smoke_run.py` rebinds that global at runtime.
3. **Divergent rounding** between the live settlement path
   (`round(max(0.0, …), 9)`, `controller.py:1362`) and the recovery path
   (`max(0.0, round(…, 9))`, `controller.py:2738`).
4. **Idempotency-key collisions** silently swallow distinct events: the
   budget-exhaustion key is always `budget-exhaustion-{node_id}` across 7 call
   sites, so a second distinct limit firing on the same node deduplicates;
   acceptance keys drift between paths (see DRY item 11).
5. **`restore_credentials` is never called by recovery** despite
   `docs/research/milestone8-handoff.md` mandating it — either dead code or a
   redaction-coverage hole on restart.
6. **`get_evidence_retrieval` only understands the legacy evidence shape**
   (`controller.py:2882` reads `checks`, but `authorise_acceptance` records
   `VALIDATION_PASSED` with `{"evidence_ids": [...]}`) — silent projection gap
   between the two acceptance paths.
7. **`_admit_inline_evidence` fixed `evidence_id`** (`controller.py:1650`)
   means a second inline admission for the same node silently deduplicates to
   the first evidence record.
8. **Global mutable injection points** (`MODEL_CLIENT_FACTORY`,
   `SECRETS_SOURCE`, `MODEL_PROFILE`, `experiment.py:235–259`) mutated by
   scripts and tests; `freeze_manifest`'s default argument captures the
   original profile at def time (`experiment.py:1071`).
9. **Cross-module access to controller private state** (`_dispatch_requests`,
   `_dispatch_responses`, `_emit`, `executor_environment`) from
   `experiment.py`, `conformance.py`, and many tests — formal accessors would
   protect the "immutable executor request" contract.
