experiments: preregister Harnett signature gates

2 files changed, 178 insertions, 0 deletions

diff --git a/ORAL_B.md b/ORAL_B.md
new file mode 100644
index 0000000..1f18de3
--- /dev/null
+++ b/ORAL_B.md
@@ -0,0 +1,172 @@
+# Oral-bar B: preregistered Harnett-signature programme
+
+This programme is grounded in Francioni et al., *Vectorized instructive
+signals in cortical dendrites* (Nature, 2026),
+<https://www.nature.com/articles/s41586-026-10190-7>. It does not treat
+"apical activity carries error" as sufficient novelty. The target is the
+paper's specific somato-dendritic innovation signatures and its explicitly
+unresolved distinction between an online control signal and a plasticity-only
+teaching signal.
+
+No oral-B result may be generated before this protocol is committed. Native
+accept-bar baselines may continue in parallel, but the oral-B confirmation may
+not be inspected until C4 is closed.
+
+## What the biological experiment establishes
+
+The paper motivates four experimental conditions for a vectorized dendritic
+teaching signal:
+
+1. dendritic activity contains information absent from parent-soma magnitude;
+2. a population of SD residuals contains reward and trial-outcome information;
+3. residual sign depends on the causal role of each neuron (opposite for P+
+   and P- cells) and follows error change rather than error magnitude alone;
+4. suppressing apical computation abolishes the vectorized signal and impairs
+   learning.
+
+The paper also reports that surrounding-network activity predicts whether a
+coincident event is dendritically amplified or attenuated, and that residual
+sign relates to subsequent activity changes. It explicitly leaves open whether
+the residual first controls neural state online, directly gates plasticity, or
+does both. That phase ambiguity is the model's central prospective prediction.
+
+## Continuous synthetic BCI
+
+The task is deliberately closer to the experiment than shuffled image
+minibatches. An episode contains 28 temporally contiguous steps. Five P+ and
+five P- units control a scalar cursor through
+
+`z(t) = mean(h_P+(t)) - mean(h_P-(t))`.
+
+The target is fixed within an episode, and reward is delivered when the cursor
+crosses the target. Thirty P0 units provide task-correlated surrounding-network
+activity but have zero direct cursor coefficient. Somatic dynamics have inertia,
+an autoregressive context input, and independent process noise. Task seed and
+model seed are separate.
+
+For every cell, raw apical activity is
+
+`a_i(t) = d_i h_i(t) + A_i c(t)`,
+
+where the first term is ordinary soma-predictable traffic and `A_i c(t)` is a
+locally calibrated causal instruction. A per-cell affine neutral-period model
+predicts normal soma-dendrite coupling and defines
+
+`r_i(t) = a_i(t) - P_i h_i(t)`.
+
+`A` is trained only from antithetic forward causal perturbations of neural
+state; forward plasticity uses local eligibility times `r`. No gradient,
+transpose weight, or reverse graph is available to learning. Exact derivatives
+may be used only in post-hoc diagnostics.
+
+The current image-runner option `feedback=error_deriv` is ineligible: it
+subtracts errors from unrelated shuffled minibatches and therefore has no
+temporal interpretation. The BCI runner must compute velocity features only
+within one contiguous episode and reset them at episode boundaries.
+
+## Frozen development screen
+
+Development uses environment seeds 0, 1, and 2 and model seed 0 only. No
+confirmation environment seed may be evaluated during selection. The fixed
+task has 40 neurons, 16 context variables, 14 training days, 64 episodes per
+day, 28 steps per episode, and a separate 256-episode final evaluation with
+plasticity disabled.
+
+Four mechanistic variants are crossed:
+
+- scalar error, plasticity only;
+- scalar error, online control plus plasticity;
+- error plus within-episode error velocity, plasticity only;
+- error plus within-episode error velocity, online control plus plasticity.
+
+For control variants, `kappa` is selected from `{0.1, 0.3}`. Forward learning
+rate is selected from `{0.01, 0.03}`. All variants use one simultaneous
+antithetic perturbation every four steps, predictor neutral updates every step,
+and the same trajectories/noise under paired seeds. A candidate is eligible
+only when all three development environments satisfy all of:
+
+- at least a 10-point early-to-late success-rate gain;
+- final success at least 20 points above the fixed-random-vectorizer control;
+- finite state, loss, weights, predictor, and vectorizer values;
+- absolute residual-parent-soma correlation no larger than 0.10;
+- positive P+/P- error-change sign-inversion index;
+- a both-phase apical lesion removes at least half of the intact learning gain.
+
+Among eligible candidates, select the largest worst-environment final success
+rate. Break a within-one-point tie by larger worst-environment sign-inversion
+index, then smaller `kappa`, then smaller learning rate. If none is eligible,
+oral B stops as failed; thresholds or seeds are not changed.
+
+## Frozen confirmation
+
+The selected configuration is frozen and crossed over environment seeds
+10--15 and model seeds 0--4. All metrics are computed by predetermined code;
+no run or seed may be removed. A result file must record the source revision,
+dirty state, task/model seed, full dynamics, phase masks, scalar reward
+observations, forward-equivalent work, and peak memory.
+
+### B1. Innovation identification and network predictability
+
+- Mean absolute per-cell `corr(r_i, h_i)` is at most 0.10.
+- Raw apical activity has at least 0.20 greater mean absolute soma correlation
+  than the innovation.
+- A cross-validated linear decoder using the preceding surrounding-network
+  state predicts amplified versus attenuated events at at least 55% accuracy.
+- Decoder hyperplane distance correlates positively with residual magnitude;
+  the mean cell-level correlation is at least 0.10.
+
+### B2. Reward, outcome, and causal-role vectorization
+
+- A cross-validated linear decoder of the residual population predicts final
+  episode success at at least 57%, and exceeds the matched soma-population
+  decoder by at least 3 points.
+- The causal-role sign-inversion index is positive in at least 25/30 paired
+  runs. Define
+
+  `I = 0.5 * [(r_P+ - r_P-)_(error decreases)
+              - (r_P+ - r_P-)_(error increases)]`.
+
+- Role-aligned innovation `s_i r_i` is more strongly associated with signed
+  error change than with unsigned instantaneous error by at least 0.05 in
+  absolute cross-validated correlation.
+- Mean early-training residual per neuron predicts its late-minus-early mean
+  somatic activity with correlation at least 0.30.
+
+### B3. Phase-specific causal lesion
+
+Four paired conditions reuse identical environment trajectories:
+
+1. intact online control and plasticity;
+2. online-control lesion only (residual excluded from state dynamics but still
+   available to local plasticity);
+3. plasticity lesion only (residual controls state but is excluded from weight
+   updates);
+4. both phases lesioned.
+
+A sham lesion consumes the same random numbers and arithmetic calls but
+multiplies no signal by zero.
+
+- Plasticity-only lesion reduces early-to-late learning gain by at least 50%
+  relative to intact.
+- After intact training, online-only lesion with weights frozen acutely reduces
+  final success by at least 5 points.
+- Both-phase lesion is no better than either single lesion on its corresponding
+  endpoint.
+- Sham lesion changes success by no more than 1 point.
+
+This factorial result is stronger than simply reproducing the paper's
+throughout-task NDNF manipulation: it predicts that suppressing dendritic
+innovation during learning and suppressing it after learning have dissociable
+effects. Failure of the acute online-lesion criterion supports a
+plasticity-only interpretation and falsifies SDIL's desired-velocity claim,
+even if the learning lesion remains positive.
+
+## Reporting boundary
+
+Passing B1 alone establishes faithful innovation statistics, not teaching.
+Passing B1+B2 without B3 establishes correlational biological signatures, not
+causal mechanism. "Oral bar B" requires all three confirmation gates and must
+include the failed structural variants and phase lesions. A match to empirical
+decoder percentages is not claimed as quantitative neuroscience; the claim is
+that one local learning-and-control mechanism jointly produces the qualitative
+signatures and a new phase-specific prediction.
diff --git a/ROADMAP.md b/ROADMAP.md
index 88b5e19..871f946 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -14,6 +14,12 @@ than triggering selective seed removal or post-hoc protocol changes.
    developed early so long jobs can use otherwise idle, explicitly authorized GPUs without
    delaying stages 1–2.
 
+The preregistered oral-B task, structural screen, confirmation seeds, signature thresholds, and
+phase-specific lesion are specified in `ORAL_B.md`. They were frozen while C4 author baselines
+were still running and before any continuous-BCI result was generated. Oral-B confirmation remains
+sequenced after C4; implementation and CPU-only mechanics may be prepared while the accept jobs
+occupy both authorized GPUs.
+
 ## Frozen accept claims and gates
 
 ### C1. Innovation is necessary under naturally mixed apical traffic