path: root/ORAL_B_V2.md

# Oral-B-v2: role-vectorized temporal-difference outcome surprise

This is a new, independently frozen branch. It does not edit, reopen, or
reinterpret the failed `oral_b_td_confirmation_v1` record in
`results/bci_td_confirmation_gate.json`, and it cannot satisfy the old
oral-A unlock. Its purpose is to answer the strongest reviewer objection to
that branch: the old residual was almost a rank-one role vector multiplied by
instantaneous performance velocity, while a 99.5% evaluation ceiling and the
absence of an explicit reward/timeout phase made balanced outcome decoding
ill-conditioned and structurally disconnected from the implemented
mechanism.

No oral-B-v2 task endpoint was inspected before this protocol, both runners,
both analyzers, all thresholds, and all seeds were committed. Endpoint-free
mechanics live in `experiments/bci_v2_smoke.py`.

## Mechanism and claim boundary

For somatic state `h_t`, a local scalar critic predicts

```text
V_t = v^T [1, h_t].
```

The environment supplies a dense within-trial performance change and a
terminal rewarded/timeout event,

```text
rho_t = 0.25 (|e_(t-1)| - |e_t|) + 1{rewarded terminal},
delta_t = rho_t + gamma (1-terminal_t) V_(t+1) - V_t.
```

Sparse antithetic cursor probes estimate each cell's signed causal role
`m_i = dz/dh_i` without reading the synthetic role map. The instructional
apical term is `m_i delta_t`. It is mixed with ordinary soma-predictable
traffic and only the innovation

```text
r_(i,t) = a_(i,t) - (P_i h_(i,t) + b_i)
```

enters the actor update. A local eligibility trace supplies temporal credit:

```text
E_(ij,t) = 0.8 E_(ij,t-1)
           + (1 - h_(i,t)^2) x_(j,t),
Delta W_ij = eta r_(i,t) E_(ij,t).
```

The critic, actor, role estimator, and neutral predictor all use explicit
manual local updates under `torch.no_grad()`. There is no task-loss query,
autograd, reverse-mode graph, feedback weight transport, or BP comparison in
this branch. `kappa=0`, so v2 tests innovation-guided plasticity and
outcome-surprise coding, not online apical control.

The terminal signal is not presented as mysterious evidence: an outcome
bonus directly enters the TD target. The nontrivial tests are that it survives
mixing with ordinary dendritic traffic only after residualization, is
cell-vectorized with the learned causal roles, is modulated by learned
expectedness, drives learning through a local eligibility rule, and replicates
under untouched task-cluster uncertainty. Acute lesions isolate the outcome
and expectedness contributions on identical trained states and trajectories.

## R0 endpoint-free mechanics gate

R0 touches no task endpoint. It passes only if all deterministic checks in
`experiments/bci_v2_smoke.py` pass:

- the simultaneous antithetic role estimate and its local update each have
  cosine above 0.99 with an analytic role used only for diagnosis;
- the neutral predictor identifies soma-predictable traffic to numerical
  tolerance;
- TD(0), critic, eligibility-trace, and forward updates equal their explicit
  local formulas;
- the continuing state's stored value is recomputed after an online critic
  update rather than left stale;
- a controlled terminal transition gives positive rewarded surprise and
  negative timeout surprise, with exact critic and outcome lesions;
- every episode produces exactly one terminal record under a truncated
  horizon, and paired replay is exact; and
- the frozen grouped terminal metrics are finite and preserve pairing.

Passing R0 changes no score and only permits R1.

## Frozen task, costs, conditions, and assays

All runs use 40 cells (`5 P+`, `5 P-`, `30 P0`), 16 context components, 28
maximum steps per episode, 64 episodes per day, 14 days, target `0.8`,
inertia `0.65`, process noise `0.12`, context AR coefficient `0.8`, neutral
predictor rate `0.2`, role rate `0.03`, perturbation scale `0.03`, one role
probe every four temporal steps, eligibility decay `0.8`, velocity reward
scale `0.25`, terminal reward `1`, and `kappa=0`.

Every condition first receives 100 instruction-off batches of 64 neutral
states. Every condition consumes the same two scalar cursor observations per
role-probe example; fixed-role and oracle conditions ignore the resulting
target. The oracle reads the analytic role only as a labelled ceiling and is
ineligible for selection. Predictor maximum error must be at most `1e-5`.

Six paired training conditions share context, process noise, perturbations,
and evaluation trajectories:

1. intact learned-role actor--critic innovation;
2. fixed random role vector;
3. forward-plasticity lesion;
4. critic training lesion;
5. terminal-outcome training lesion; and
6. exact-role diagnostic oracle.

Ordinary task performance is evaluated on 256 full-horizon episodes. The
biological signature assay is separate and uses the fixed horizon ladder
`{4, 8, 12, 16, 20, 24, 28}`, with 128 independent episodes at every horizon.
All horizons are pooled; no horizon is selected, reweighted, removed, or
tuned. This deliberately produces rewarded and censored timeout trials
without weakening the trained task or choosing a difficulty after viewing
outcomes. On exactly the same trained intact model and trajectories, the
assay replays intact, acute-critic-lesion, and
acute-terminal-outcome-lesion readouts with all learning disabled.

Each record reports maximum and actually active state transitions, neutral
examples, role-probe examples, two scalar cursor observations per probe,
terminal observations, evaluation cost, wall time, peak RSS, task-loss
queries, and reverse-mode calls. Early termination is counted rather than
silently charged as a full active trajectory.

## R1 frozen development selection

R1 uses fresh development task seeds `20--22` and model seed `0`. It evaluates
the complete Cartesian grid

```text
forward eta in {0.03, 0.1}
gamma       in {0.8, 0.95}
critic eta  in {0.01, 0.03}
```

for exactly 24 records. Full performance seeds are `400000 + task_seed`.
Horizon-ladder seed for index `k` is `410000 + 1000 task_seed + k`.
Confirmation task seeds `30--35` and model seeds `0--4` remain untouched.

A candidate is eligible only if every one of its three task seeds passes every
check:

- intact final success at least 70% and early-to-late gain at least 10 points;
- final success at least 20 points above fixed role and no more than 10 points
  below the exact-role oracle;
- the plasticity lesion retains at most half the intact learning gain and the
  learned-role cosine is at least 0.80;
- pooled challenge success fraction lies in `[0.15, 0.85]`;
- terminal residual outcome balanced accuracy is at least 65%, role-aligned
  rewarded-minus-timeout separation at least `0.03`, and acute outcome lesion
  reduces that separation by at least `0.01`;
- mean learned-critic expectedness contribution is at least `0.005` and its
  paired contribution correlates at least `0.95` with the stored value
  prediction;
- nonterminal mean absolute residual--soma correlation is at most `0.10`, and
  raw-minus-residual correlation gap is at least `0.20`;
- preceding surrounding population predicts the sign of a causal cell's
  residual with mean balanced accuracy at least 52%, and decoder distance has
  residual correlation at least `0.02`; and
- P+/P- performance-change sign inversion is at least `0.01`, with at least
  `0.05` absolute CV-correlation advantage for performance velocity over
  instantaneous error magnitude.

Among eligible candidates, selection maximizes worst-task final success, then
worst-task terminal outcome accuracy, then prefers smaller forward rate,
smaller critic rate, and smaller gamma. If no candidate is eligible, v2
closes. R1 never changes the score. The executable screen and deterministic
analyzer are `experiments/bci_v2_development_screen.sh` and
`experiments/analyze_bci_v2_development.py`.

## R2 frozen untouched confirmation

Only a complete eligible R1 gate permits R2. R2 runs the selected candidate
without further selection over task seeds `30--35` and model seeds `0--4`,
exactly 30 paired records. Full performance seeds are
`500000 + task_seed`; ladder seed for index `k` is
`510000 + 1000 task_seed + k`. The task seed is the independent unit: each
metric is first averaged over the five model seeds, then summarized over six
task clusters with a one-sided 95% Student-t bound with five degrees of
freedom.

Learning and plasticity pass only if:

- mean intact final success is at least 70%, every task mean and the lower
  bound are at least 60%;
- mean learning gain is at least 10 points and its lower bound at least 5;
- mean fixed-role gap is at least 20 points and its lower bound at least 10;
- mean oracle deficit is at most 10 points and its upper bound at most 20;
- the lower bound of `0.5 intact_gain - plasticity_lesion_gain` is
  nonnegative; and
- mean role cosine is at least 0.80 and every record is at least 0.70.

Innovation and network prediction pass only if:

- mean residual--soma correlation is at most `0.10` with upper bound `0.12`,
  and mean raw-minus-residual gap is at least `0.20` with lower bound `0.15`;
- surrounding-event accuracy averages at least 52% with lower bound 50%, and
  decoder-distance correlation averages at least `0.05` with nonnegative
  lower bound;
- sign inversion is positive in at least 25/30 records and in every
  task-cluster mean; and
- velocity advantage averages at least `0.05` with nonnegative lower bound.

Terminal outcome surprise passes only if:

- every record's pooled challenge success fraction lies in `[0.10, 0.90]`;
- terminal residual outcome accuracy averages at least 65% with lower bound
  60%;
- role-aligned outcome separation averages at least `0.03` with lower bound
  `0.01`;
- acute outcome lesion reduces separation by at least `0.01` on average with
  nonnegative lower bound;
- critic expectedness contribution averages at least `0.005` with
  nonnegative lower bound; and
- every paired critic contribution/value-prediction correlation is at least
  `0.95`.

The runner and immutable complete-grid analyzer are
`experiments/bci_v2_confirmation.py` and
`experiments/analyze_bci_v2_confirmation.py`. All records bind the protocol,
model, metrics, both analyzers, both runners, D4 gate, preserved failed old R2
gate, and (for confirmation) R1 gate by SHA-256, require a clean tracked
worktree, reject missing or extra records, and refuse overwrite.

A complete R2 pass raises the repository's formal milestone score from 7 to 8
and establishes role-vectorized TD outcome surprise plus innovation-guided
plasticity on this BCI paradigm. It does not establish online apical control,
does not erase the old R2 failure, and does not open the old oral-A panel. It
only permits a separately frozen oral-A-v2 protocol. Any failed R2 is retained
and leaves the formal score at 7.