docs: consolidate three-part evidence story

1 files changed, 138 insertions, 0 deletions

diff --git a/THREE_PART_EVIDENCE.md b/THREE_PART_EVIDENCE.md
new file mode 100644
index 0000000..6673b0f
--- /dev/null
+++ b/THREE_PART_EVIDENCE.md
@@ -0,0 +1,138 @@
+# Three-part paper evidence
+
+## One-sentence claim
+
+Somato-dendritic innovation is a local correction for predictable teaching-
+channel error. It transfers across digital local learners, preserves coupled
+learning as the number of imperfect components grows, and can be implemented
+with local sampling and subtraction in a hardware-realistic CLLN.
+
+The method remains:
+
+```text
+r = a - P(z)
+Delta w = eta * r * eligibility
+```
+
+`P` is fitted from instruction-off local observations. It receives no task
+gradient, device constant, downstream weight, or BP signal.
+
+## Part 1: additive digital correction
+
+The first part asks whether the same operation can be attached to an existing
+learning rule without replacing that rule.
+
+| Digital learner | Task and repetitions | Clean | Raw imperfection | Static calibration | SDIL | Status |
+|:--|:--|--:|--:|--:|--:|:--|
+| Dual Propagation | CIFAR-10 miniCNN, 5 seeds | 82.86% | 9.40% | — | 82.92% | Passed frozen confirmation |
+| Equilibrium Propagation | FashionMNIST ConvHopfield, 5 seeds | 76.26% | 31.38% | 67.90% | 74.52% | SDIL beats raw in every seed; strict gate failed because one seed favors calibration |
+| Digital coupled learning | released ring tasks, size ladder pilot | reported by size | 37.5–62.5% error | 2.5–30.0% error | 0–7.5% error | Full confirmation running |
+| Overclamped coupled learning | released ring tasks, size ladder pilot | 0–2.5% error | 25–50% error | — | 0–2.5% error | Clean-only time constant selected before biased endpoints |
+
+Sources:
+
+- `results/contrastive_bias/c1_gate.json`
+- `results/ep_bias/c1_gate.json`
+- `results/coupled_ladder/p1_imperfection_pilot.json`
+- `results/coupled_ladder/p1_bias_baseline_pilot.json`
+- `results/coupled_ladder/p1_overclamp_selected_pilot.json`
+
+The Dual Propagation result establishes strong transfer. The EP result shows
+transfer with a visible remaining clean gap and seed variance. Coupled learning
+adds a system where the local variables map directly to circuit measurements.
+
+## Part 2: scaling digital coupled learning
+
+The periodic grid ladder uses side lengths `4, 8, 12, 16, 24, 32`, or 32 to
+2,048 learnable edges. Every method receives the same released task, tiled
+initial gate field, and component draw. Size-dependent update exposure is
+selected from ideal coupled learning only.
+
+Pilot final classification error:
+
+| Edges | Clean | Same-RMS noise | Raw | Static calibration | SDIL |
+|--:|--:|--:|--:|--:|--:|
+| 32 | 0.0% | 0.0% | 50.0% | 2.5% | 0.0% |
+| 128 | 0.0% | 0.0% | 62.5% | 2.5% | 0.0% |
+| 288 | 2.5% | 5.0% | 52.5% | 2.5% | 2.5% |
+| 512 | 2.5% | 10.0% | 47.5% | 5.0% | 2.5% |
+| 1,152 | 2.5% | 17.5% | 50.0% | 10.0% | 7.5% |
+| 2,048 | 2.5% | 22.5% | 37.5% | 30.0% | 2.5% |
+
+The raw learner has a large error floor at every size. Static calibration works
+on small grids and degrades on larger grids. Relative to static calibration,
+SDIL reduces the pilot excess-error growth slope by 88.1%; the paired
+task-bootstrap slope-difference interval is positive. At 2,048 edges, SDIL
+closes the full raw-to-clean final-error gap and reaches stable zero error on
+80% of task runs, versus 0% for raw and static calibration.
+
+The tuned overclamp pilot gives the same structural result. Clean overclamping
+ends at 0–2.5% error across the ladder. Imperfect overclamping ends at 25–50%,
+while overclamping plus SDIL ends at 0–2.5%. SDIL therefore combines with the
+strong-clamp correction.
+
+The publication figure and data are:
+
+- `results/figs/figure_clln_scaling_pilot.pdf`
+- `results/coupled_ladder/p1_scaling_analysis.json`
+- `results/coupled_ladder/p1_scaling_source.csv`
+
+The pilot has five task clusters and one component draw per task and size. The
+running confirmation contains all 40 released tasks, three new component draws,
+six sizes, and five core methods: 3,600 training trajectories. Its outputs are
+`results/coupled_ladder/p2_confirm_side{4,8,12,16,24,32}.json`.
+
+## Part 3: hardware-realistic simulation
+
+This part uses the nonlinear conductance law, periodic 4-by-4 topology,
+released Figure-5 tasks and initial gates, Appendix-C component imperfections,
+and explicit local voltage-square updates.
+
+Across 40 tasks and four component draws, or 160 trials per method:
+
+| Method | Mean classification error | Zero-error trials |
+|:--|--:|--:|
+| Clean CLLN | 0.00% | 100.00% |
+| Raw imperfect CLLN | 25.86% | 21.25% |
+| Static calibration | 3.75% | 84.38% |
+| Overclamping | 4.77% | 86.88% |
+| SDIL | 0.00% | 100.00% |
+| Overclamping + SDIL | 0.00% | 100.00% |
+
+The local CDS/autozero circuit model then adds sampling gain mismatch,
+pedestal mismatch, noise, and stale refresh. Ideal CDS and the combined mild
+refresh-every-four condition retain 0% error. The combined strong condition
+has 0.55% mean error and 96.88% zero-error trials. A 0.1 V/s pedestal mismatch
+has 0.63% error; a 0.25 V/s mismatch has 4.45% error and marks the simulated
+failure boundary.
+
+Sources:
+
+- `sdil/physical_grid.py`
+- `results/physical_bias/p5_full_grid_bias_crossover.json`
+- `results/physical_bias/p9_grid_correlated_autozero_key_results.json`
+- `results/physical_bias/p8_spice_autozero_primitive.json`
+
+The hardware claim is: the full update is simulated with published device
+equations and nonideal local sampling, and its primitive sample/subtract path
+has a SPICE check. A fabricated-chip demonstration remains future work.
+
+## Main figures
+
+1. Method and transfer across Dual Propagation, EP, standard CLLN, and
+   overclamped CLLN.
+2. Digital CLLN scaling: final error, stable success, and learning curves.
+3. Hardware-realistic CLLN: raw, calibration, overclamping, SDIL, and
+   nonideal-CDS robustness.
+4. Mechanism boundary: matched noise, state dependence, sampling mismatch,
+   and refresh interval.
+
+## Remaining gates
+
+1. Complete and audit the 3,600-trajectory digital ladder confirmation.
+2. Run the selected overclamp pair on the full task/device confirmation panel.
+3. Turn the local projection and scaling argument into a theorem whose plotted
+   quantity is excess task error or displaced fixed point, rather than an
+   unobserved residual alone.
+4. Rebuild the three main figures from confirmation data and audit every number
+   against its source JSON.