1# DECISIONS.md — design decisions (dated)23| id | date | decision | rationale |4|---|---|---|---|5| D1 | 2026-10-29 | Repository lives at `Recherche-UQO/ia/prisme-slm` (new `ia/` category of the UQO series); Python 3.12 venv via `uv`, PyTorch 2.15 (CPU/MPS), fp32 training. | Series convention; bf16 autocast gave no speed-up on MPS (15.3k vs 15.0k tok/s on M3 Ultra). |6| D2 | 2026-10-29 | A dedicated `bank_norm` RMSNorm precedes the bank/z projections. | The pre-final-norm residual stream has growing norm; projecting it raw would couple editor dynamics to residual scale. Costs d parameters. |7| D3 | 2026-10-29 | Workspace/controller parameter counts are NOT forced to the brief's figures. | The brief's figures are reproduced exactly by a closed form (`4dw+Mw+17w²+6wf_w+15.5w+4`); the implemented design needs 7 fewer w×w projections per config (bank is read directly; readout uses raw slot values; controller shares one state MLP across the 24 actions so that scoring costs O(A·w²) not O(A·w·f_w)). Reconciliation reported in `results/tables/param_counts.json`. |8| D4 | 2026-10-29 | STOP is absorbing in forced-action training too. | Needed for incremental/full-prefix equivalence (test revealed the mismatch). |9| D5 | 2026-10-29 | Cost proxy c(a) in the controller's Q is the analytic ops ratio of the action (not a learned ĉ); the ĉ head is kept as a diagnostic regressor. | Per-action cost is deterministic given k(a) and T; learning it adds noise without information. |10| D6 | 2026-10-29 | Synthetic splits are deduplicated by exact text across splits (train written first); eval items colliding with train are dropped and counted. | Low-depth cells have few distinct items; 995 train dups, 256 dev_iid dups removed. |11| D7 | 2026-10-29 | Phase 4 uses a character-level tokenizer and a 2.1M-parameter backbone trained from scratch on the synthetic train split. | Self-contained learnability test independent of the web corpus/tokenizer. |12| D8 | 2026-10-29 | 103M pilot backbone: 196.6M tokens (12k steps × 32 × 512) of FineWeb-Edu, one seed; parameter-matched plain decoder baseline (ffn 2144, 102.16M) trained with the identical recipe on a second node. | ~3.7 h per run at 14.8k tok/s on an M3 Ultra; seeds are varied at the editor/controller stage where the pilot's decisive comparison lives. |13| D9 | 2026-10-29 | `readout_scale`: Δ = readout_scale · U(r(S_f) − r(S0)), with readout_scale a fixed constant set once at bootstrap to the measured rms of the backbone residual stream (5.6 for the tiny backbone). | Scale mismatch blocked the U = 0 bootstrap (see FAILURES). The final RMSNorm makes logits invariant to the joint scale of h and Δ, so this is a reparametrisation of U's learning rate; identity properties are unchanged (tests pass). |14| D10 | 2026-10-30 | Controller features: the normalised backbone residual ĥ_t (d-dim) and the backbone's own predictive entropy at budget 0 are added to z_t; their cost (2dw per token, one head evaluation per token) is charged in `prisme/flops.py`. | With z-only features the controller's sign accuracy on calibration labels was at chance (49 %); the variance decomposition showed 86–89 % of gain variance is between states, and oracle gains concentrate on high-loss states, which the entropy exposes. With ĥ + entropy sign accuracy rose to 60 %. |15| D11 | 2026-10-30 | Counterfactual labels for the controller are collected on a dedicated `ctrl_train` stream (seed 4, same cells as train) that the editor never trained on; calibration stays on `calib` (seed 3). Existing splits are byte-identical. | Labels collected on the editor's own training items were unrepresentative (train: pairs > singles, calib: the reverse); the controller selected on calibration (−1.1 % loss) was worse than the backbone on dev-iid (+1.6 %). |16| D12 | 2026-10-30 | Additional controller variant with within-state ranking losses (pairwise logistic loss on the 4 logged candidates weighted by the gain difference; listwise soft cross-entropy over the 24 exhaustive-audit gains, temperature 0.02), on top of the pre-registered Huber/BCE/NLL losses. | Motivated by the diagnosis that the controller finds high-opportunity states but ranks actions within a state at chance; a new, separately labelled experiment, not a change to the pre-registered one. |17| D13 | 2026-10-30 | The 103M pilot backbone budget is 98.3M tokens (6,000 steps × 32 × 512), not the 196.6M announced in D8. | The step count had been raised to 12,000 locally but the earlier rsync exclusion bug (FAILURES) left the 6,000-step config on M3U96a; the run completed at 6,000 steps (val ppl 48.2, 2.3 h, peak 28 GB). The parameter-matched plain decoder, launched later with the 12,000-step config, is killed at step ~6,500 and relaunched with the identical 6,000-step recipe so that the comparison stays matched. |18| D14 | 2026-10-30 | 103M adapter learning rate lowered to 3e-4 for the sparse editor (the global-recurrence adapter, run at 1e-3, did not collapse). | Harmless-collapse failure at 1e-3 (FAILURES); the two adapters therefore differ in learning rate at 103M, which is disclosed with the result. |19