protocol: freeze independent oral-B-v2 gates

1 files changed, 231 insertions, 0 deletions

diff --git a/ORAL_B_V2.md b/ORAL_B_V2.md
new file mode 100644
index 0000000..a585b58
--- /dev/null
+++ b/ORAL_B_V2.md
@@ -0,0 +1,231 @@
+# 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.