<!-- informative -->

# Reviewer Brief: Phase 1 Refactor — Adversarial Review

## Mandate

Independently falsify the Phase 1 refactor before Axis 1 (self-host Phase 1)
builds on it. Phase 1 moved and restructured the harness's load-bearing
machinery with the promise of *zero behavior change*:

1. **1.1 file split** — the 3,331-line `experiment.py` became a 166-line façade
   over `experiment_target`, `hidden_oracle`, `experiment_spec`,
   `trial_driver`, `experiment_phases`, `hashing`, and `git_ops`.
2. **1.2 dispatch table** — the reducer's 770-line `if et == …` chain became 29
   `_on_*` handlers behind a module-level `_HANDLERS` table (65 event types).
3. **1.3 DRY unifications** — one numeric predicate
   (`numeric.amount_failure`, mapped per layer to seven exception types), one
   `TOLERANCE`, and one executor base (`DispatchBase`: single-use tokens,
   cancellation set, response cache, and the per-executor **single-flight
   lock**, which `ScriptedExecutor` gained).
4. **1.4 bindings** — `OracleManifest.target_binding` with mismatch-rejection
   in `run_trial`; the measured comparison captures its trial profile once
   after the freeze-binding check.

The conversion of 1.2 was done by script plus several manual repair passes
(leaked group-header fragments, a lost dataclass decorator, a dropped call
argument, quote-mangled docstrings — all found by the suite, all fixed), which
is precisely the shape of change that a green suite can bless while carrying a
drift. Assume the happy path is covered and attack the seams.

**Independence:** you must not be the author of the uncommitted Phase 1 change
set (the new `src/orchestrator/{numeric,git_ops}.py` and the restructured
`experiment*.py`, `trial_driver.py`, `hidden_oracle.py`, `reducer.py`,
`executor.py`, `command_executor.py`, `model_adapter.py`) nor of its new test
modules. Read the source and normative documents before the tests; treat the
new tests as claims to verify, not evidence.

## Target

- Repo: `/home/ruben/Projectos/meta-project/orchestrator`
- Revision reviewed: the **uncommitted working tree** (HEAD + the Phase 0
  defect closure + the step-2 hardening + the Phase 1 refactor — one stacked
  diff). Snapshot the tree you review (worktree or `git stash create`) and
  name it in the report. The diff also carries the already-reviewed Phase 0 /
  step-2 fixes (F1–F9 closed, verification addendum in
  `docs/research/axis2-robustness-review.md`) — out of scope except where the
  refactor touches them.
- Work on a frozen copy:
  `git worktree add --detach /tmp/kilo/phase1-review <your-snapshot>`
- Normative documents: `docs/control-plane.md` (node/attempt machines, crash
  recovery), `docs/budgets.md`, `docs/executors.md` (trust boundaries),
  `docs/experiment.md` (independent oracle), `docs/tables/*.yaml` (the frozen
  machines), `docs/research/report-recurring-failures.md` (classes A–I).
- Context: the Phase 1 plan in the working session; the Axis 2 report and its
  review for the already-verified baseline.
- Baseline: `.venv/bin/python -m pytest -q` (expect 701 passed);
  `scripts/check-static` gated rules clean; `scripts/check-docs` 183 links OK;
  the state fuzzer walks every catalogued event type. None of these is a
  verdict.
- No source edits, no third-party network, no real credentials, no paid calls.
  The local stub (`scripts/provider_stub.py`) is in-tree for client-level
  probes; probes under `/tmp/kilo/`.

## The guarantees under review

1. **Behavior preservation of the file split.** Every name reachable as
   `orchestrator.experiment.X` before the split is reachable after, with the
   same semantics — including the private names the regression suites pin
   (`_TrialRecorder`, `_HIDDEN_DRIVERS`, `_commands_for`, `_content_hash`, …),
   and including *attribute mutation* (`experiment.MODEL_PROFILE = …` had two
   live assignment sites in `scripts/smoke_run.py`, converted to
   `set_model_profile`; hunt for any remaining rebinding that the façade's
   delegation would silently drop).
2. **Dispatch-table completeness and equivalence.** Every event type in
   `events.EVENT_CATALOGUE` has exactly one `_HANDLERS` entry, and no handler
   without a catalogue entry (or an explicitly synthetic corpus record). The
   conversion preserved each branch's early returns, exception types, error
   message strings, derived-effect order, and the terminal fall-through.
3. **Replay equivalence.** `store.replay_fresh` re-derives identical state
   from the log for every admitted event — the dispatch order change must not
   alter any derived effect, any accounting transition, or any
   `late_event_retained` decision.
4. **The single-flight invariant holds for all three executors.**
   `DispatchBase` gives every executor the per-attempt token, cancellation
   set, response cache, and lock; a concurrent duplicate delivery of one
   `(attempt_id, token)` runs the underlying work exactly once — for the
   command executor, the model adapter, *and the scripted fixture that only
   now gained the lock*.
5. **The numeric predicate is a faithful unification.** Each migrated site
   refuses exactly what it refused before (booleans, non-numbers, NaN, ±inf,
   negatives where required), maps to the same exception type, and keeps the
   message contract (`schemas`' two bool predicates, `spend`'s formerly
   combined "finite and non-negative" message, the controller's declared-
   charge and commitment forks).
6. **The target binding is non-decorative (R12).**
   `OracleManifest.target_binding` is set by `build_hidden_oracle`, and
   `run_trial` refuses an unbound, hand-built, or foreign-target manifest
   *before* the spend reservation, the trial directory, or any sandbox work
   exists. The binding covers every `run_trial` call path (comparison, pilots,
   the smoke runner's probe and run modes, the stress sweep's children).
7. **Façade delegation is transparent.** The PEP 562 `__getattr__` on
   `experiment.py` serves the three mutable bindings with current values
   through reads, `from`-imports, `monkeypatch.setattr` (which shadows), and
   reload — and every other name resolves statically.
8. **The split did not move the guard rails.** The fixture-fidelity,
   open-defect, counterexample, and guard-mutation meta-tests still see what
   they scanned before; the interleave harness still pins the same
   controller/reducer windows; the static gates still scan the same files.

## In scope

- `src/orchestrator/experiment.py` (façade), `experiment_target.py`,
  `hidden_oracle.py`, `experiment_spec.py`, `trial_driver.py`,
  `experiment_phases.py`, `hashing.py`, `git_ops.py`.
- `src/orchestrator/reducer.py` (handlers + `_HANDLERS` + `reduce`).
- `src/orchestrator/executor.py` (`DispatchBase` + `ScriptedExecutor`),
  `command_executor.py`, `model_adapter.py` (the base wiring).
- `src/orchestrator/numeric.py` and the six migrated validator sites.
- `scripts/smoke_run.py` only at its two converted `set_model_profile` sites
  and the probe/run paths that call `run_trial`.
- The new pins: `test_verifier_mutations.py::test_oracle_manifest_binding_refuses_a_foreign_target`,
  the fidelity ratchet, and any test whose assertions changed in the diff.

## Out of scope

- The Phase 0 defect fixes and the step-2 hardening (already reviewed; their
  findings are closed). Incidental regressions are welcome, but the verdict is
  scoped to Phase 1.
- Axis 1 design, the performance plan, the doc reorganization (deliberately
  deferred by consensus until this review closes).
- Model capability and the free-tier provider's behaviour as such.

## Known residuals — acknowledge, do not re-report as novel

- The `MODEL_CLIENT_FACTORY`/`SECRETS_SOURCE` setters remain module-level
  injection points (13 test call sites); their per-run threading is Axis 1's
  run-spec work, deliberately deferred. The comparison's profile is
  manifest-derived per-run; the factory/secrets are process-wide by design
  until then.
- `git_ops._git` late-imports `ExperimentError` to break the re-export cycle —
  documented in the function.
- `numeric`'s `spend` mapping normalises the formerly combined
  "finite and non-negative" message into two messages; no test pinned it.
- The transcript durability and 429 billing residuals from the Axis 2 review
  (carried to Phase 3).

## Attacks to attempt (minimum)

- **Catalogue/table diff.** Script it: the set difference between
  `events.EVENT_CATALOGUE` keys and `_HANDLERS` keys must be empty in both
  directions. Then admit each catalogued event once against a minimal valid
  state and confirm the same transition/effect the pre-refactor reducer
  produced (compare against `git show HEAD:src/orchestrator/reducer.py`).
- **Conversion drift.** Diff each `_on_*` handler against its original chain
  block (HEAD's reducer, lines 387–1151): renamed locals, dropped statements,
  changed `raise` messages, swapped effect order, changed early-return
  conditions. The conversion was scripted and hand-repaired; assume
  transcription bugs and find them.
- **Replay equivalence.** For a corpus of runs (the conformance crash matrix,
  the fuzz walks, a real `run_trial` under the stub): `replay_fresh` state ==
  live state, field by field, including ledger entries, timers, freshness, and
  failure fingerprints.
- **Single-flight under real concurrency.** For each executor, drive two
  threads into `dispatch` with the same `(attempt_id, token)` and a slow
  delegate; assert one execution, one cache entry, identical responses. Then
  the token variants: duplicate `issue_token`, dispatch with an unissued
  token, dispatch after cancel, dispatch after token use.
- **Façade semantics.** `monkeypatch.setattr(experiment, "MODEL_PROFILE", x)`
  followed by a spec-module read; `from orchestrator.experiment import
  MODEL_PROFILE` before and after `set_model_profile`; `importlib.reload`;
  `dir()`/`hasattr` on the delegated names; pickling of anything holding a
  façade reference. Any stale-read shape is a P1 (the smoke runner's real-mode
  swap depends on it).
- **Binding bypass.** `run_trial` with an unbound manifest (empty
  `target_binding`), a foreign snapshot, and — the interesting one — a
  manifest whose binding matches but whose *suite hash* was computed from a
  different target (the label-echo variant the binding must close). Check all
  four call paths: `run_measured_comparison`, `run_pilots`,
  `calibrate_oracle`'s materialise-and-grade (does it need the binding? state
  so), and the smoke runner's probe.
- **Predicate drift.** For each migrated site, the input grid
  (True/False/0/-1/NaN/±inf/""/"5"/None/2**64/decimal-like) must produce the
  same refusal-vs-accept decision and exception type as HEAD's validator.
  `schemas`' two predicates must stay closed over the same domain.
- **Numeric edges at the new seams.** `numeric.amount`'s generic `ValueError`
  must never escape a layer unmapped (the reducer wraps it; check every other
  caller of `numeric.amount`/`amount_failure` wraps it in *its* contract
  exception).
- **Split-induced import drift.** `git_ops._git`'s function-level import; any
  other late imports introduced to break cycles; the façade's import block vs
  what the submodules actually use (an F401-stripped import that a lazy path
  still needs).
- **Meta-test blind spots.** The fidelity/defect/counterexample scans run over
  `tests/*.py` non-recursively — confirm the split did not move any fake,
  pin, or fixture into a subpackage (and that no new fake ships unregistered).

## Method

- Read the normative tables and the pre-refactor sources (`git show
  HEAD:…`) first; diff each moved symbol against its original.
- Drive the real entry points (`run_trial`, `run_measured_comparison`,
  `run_experiment`, `smoke_run.py --probe`) against
  `scripts/provider_stub.py`; prefer whole-trial reproducers for
  behavior-preservation claims and unit probes for conversion-drift claims.
- Use `EventStore.history`/`state` and `replay_fresh` as the source of truth,
  never the runner's stdout.
- For each attack: exact commands, the probe (not a source edit), observed vs
  expected, and which guarantee is violated. Prefer a failing reproducer.
- Do not weaken or edit tests; report a failing reproducer instead.

## Deliverable

1. **Verdict:** GO / NO-GO for relying on the Phase 1 refactor in Axis 1.
2. **Findings** with severity (P0/P1/P2), the guarantee violated, a minimal
   reproducer, observed vs expected, and the proposed permanent regression
   test.
3. **Claims verified:** each of the eight guarantees with the falsification
   attempt and outcome ("attacked, not falsified" is valid with the method
   stated).
4. **Conversion-drift census:** the per-handler diff status of the reducer
   conversion (identical / semantically identical with justification / drift).
5. **Residual unknowns:** what you could not test and why.

## Exit criteria

- Every guarantee is either falsified with a reproducer or explicitly
  "attacked, not falsified" with the method.
- The catalogue/table diff script exists and its result is stated.
- At least one concurrency probe per executor, and one replay-equivalence run
  over a multi-trial corpus.
- No source edits, no third-party network, no real credentials, no paid calls;
  host state left clean.
- Findings are reproducible from the report alone against the named snapshot.
- The review states what it did not cover.

## Reproduce everything

List every probe command, stub scenario, and worktree revision here so the
verdict can be re-run against a corrective revision.
