Specification Change Log

Use this file to note intentional documentation changes that affect the language/design direction.

Entry template

• Date:
• Scope (files/sections):
• Reason for change:
• Decision impact:
• Follow-up actions:

Entries

• Date: 2026-09-05

• Scope (files/sections): docs/10-spec/12-phase-1/27-storylm0-trained-fixture.md, docs/30-decisions/56-storylm0-trained-fixture.md, retarget of Section 23 / 24 / 26 trained-fixture opens

• Reason for change: Specify the trained 32-token fixture as Section 24 SGD persisted to storylm0-checkpoint-v1, before adding the host check. No new operator. Patterned v0 stays.

• Decision impact: A Python driver can load taught weights and lock a 36-id greedy cycle (once upon a time the end × 6).

• Follow-up actions: scripts/export_trained_checkpoint.py, scripts/validate_trained_rollout.py, committed NPZ.

• Date: 2026-08-24

• Scope (files/sections): docs/10-spec/12-phase-1/26-storylm0-mean-nll.md, docs/30-decisions/55-storylm0-mean-nll.md, retarget of Section 15 / 24 / 25 mean-NLL opens

• Reason for change: Specify mean NLL as keepdims reduce_sum times host 1/(B·T) before adding the examples. No new operator. No reduce_mean VJP.

• Decision impact: One .kina program can return a [1, 1] mean loss and mean-scaled SGD. Sections 24 / 25 stay sum-NLL.

• Follow-up actions: ad_reduce_sum.kina, storylm0_mean_nll_step.kina, host .so numeric check.

• Date: 2026-08-24

• Scope (files/sections): docs/10-spec/12-phase-1/25-storylm0-decoder-adamw.md, docs/30-decisions/54-storylm0-decoder-adamw.md, retarget of Section 16 / 24 decoder-AdamW opens

• Reason for change: Specify decoder-wide AdamW as Section 15 reverseMode plus one Section 16 copy per trainable weight, before adding the example. No new operator. Host t and β**t.

• Decision impact: A Python driver can drop corpus sum-NLL below 0.5 with AdamW and lock the same greedy cycle as Section 24.

• Follow-up actions: storylm0_adamw_step.kina, host .so numeric check.

• Date: 2026-08-24

• Scope (files/sections): docs/10-spec/12-phase-1/24-storylm0-host-train.md, docs/30-decisions/53-storylm0-host-train.md, retarget of Section 23 open issue 4

• Reason for change: Specify a host train loop as 40 epochs of Section 15 SGD over a three-window toy corpus plus Section 23 greedy, before adding the numeric check. No new operator. No mean NLL.

• Decision impact: A Python driver can drop corpus sum-NLL below 0.5 and lock greedy once upon a time the end once upon a time the end. Patterned 32-token fixture stays.

• Follow-up actions: scripts/validate_train.py, host .so numeric check.

• Date: 2026-08-24

• Scope (files/sections): docs/10-spec/12-phase-1/23-storylm0-rollout.md, docs/30-decisions/52-storylm0-rollout.md, retarget of Section 18 / 20 / 21 / 22 32-token and sampled-rollout opens

• Reason for change: Specify the companion 32-token checkpoint test as a host loop around a static T=36 forward plus argmax / Gumbel-max and a versioned NPZ fixture, before adding the example. No new operator. No in-place write.

• Decision impact: A Python driver can load the fixture, greedy-roll 32 tokens twice, sample 32 tokens twice, and check the causal non-leak. Weights stay the patterned recipe.

• Follow-up actions: storylm0_rollout.kina, host .so numeric check.

• Date: 2026-08-24

• Scope (files/sections): docs/10-spec/14-phase-3/07-storylm0-proj-shards.md, docs/30-decisions/51-storylm0-proj-shards.md, retarget of Section 6 open issue 2

• Reason for change: Specify 2-way column-parallel Wq/Wk/Wv as slice of projection columns plus per-head rank-4 attention plus concat, before adding the example. No new operator. No @mesh.

• Decision impact: A Python driver can match first-head Q, per-head context, and logits to the unsharded forward. Mesh types stay unimplemented.

• Follow-up actions: storylm0_tp_proj.kina, host .so numeric check.

• Date: 2026-08-24

• Scope (files/sections): docs/10-spec/14-phase-3/06-storylm0-head-parallel.md, docs/30-decisions/50-storylm0-head-parallel.md, retarget of Section 5 open issue 3

• Reason for change: Specify 2-way head-parallel attention as slice of Q/Kᵀ/V plus per-head rank-4 attention plus concat, before adding the example. No new operator. No @mesh.

• Decision impact: A Python driver can match per-head context and logits to the unsharded forward. Mesh types stay unimplemented.

• Follow-up actions: storylm0_tp_heads.kina, host .so numeric check.

• Date: 2026-08-24

• Scope (files/sections): docs/10-spec/14-phase-3/05-storylm0-workload.md, docs/30-decisions/49-storylm0-sharding-workload.md, retarget of Phase 3 §1 / §2

• Reason for change: Lock StoryLM-0 as the first Phase 3 sharding workload (2-way column-parallel lm_head) before adding the example. No new operator. No @mesh syntax.

• Decision impact: A Python driver can match vocab-parallel logits to the unsharded forward. Mesh types stay unimplemented.

• Follow-up actions: storylm0_tp_vocab.kina, host .so numeric check.

• Date: 2026-08-23

• Scope (files/sections): docs/10-spec/12-phase-1/22-tmax-scratch.md, docs/30-decisions/48-storylm0-tmax-scratch.md, retarget of Section 19 / 20 / 21 T_max open issues

• Reason for change: Specify T_max scratch as pad-with-zeros + slice-prefix before adding the example. No new operator. No in-place write.

• Decision impact: A Python driver can keep a fixed-shape […, T_max] cache next to the live prefix. In-place write stays out of scope.

• Follow-up actions: storylm0_tmax.kina, host .so numeric check.

• Date: 2026-08-23

• Scope (files/sections): docs/10-spec/12-phase-1/21-prefill-handoff.md, docs/30-decisions/47-storylm0-prefill-handoff.md, retarget of Section 19 / 20 prefill open issues

• Reason for change: Specify prefill → decode handoff as the existing forward graph returning Kᵀ/V, plus Phase 0 slice on last logits, before adding the example. No new operator.

• Decision impact: A Python driver can prefill T=3 and decode one token from that cache. T_max scratch stays out of scope.

• Follow-up actions: storylm0_prefill.kina, host .so numeric check.

• Date: 2026-08-23

• Scope (files/sections): docs/10-spec/12-phase-1/20-host-generation-loop.md, docs/30-decisions/46-storylm0-host-generation-loop.md, retarget of Section 19 open issue 1

• Reason for change: Specify the host generation loop as static-S decode plus Section 17 argmax before adding the example. No new operator. while carries stay fixed-shape.

• Decision impact: A Python driver can greedy-roll four tokens from one seed. Prefill handoff and T_max stay out of scope.

• Follow-up actions: storylm0_generate.kina, host .so numeric check.

• Date: 2026-08-23

• Scope (files/sections): docs/10-spec/12-phase-1/19-kv-cache.md, docs/30-decisions/45-storylm0-kv-cache.md, retarget of Section 18 open issue 2

• Reason for change: Specify one-step KV-cache append as existing concat plus rank-4 attention before adding the example. No new operator. while carries stay fixed-shape.

• Decision impact: One .kina program can append S=1 onto a static past cache and attend. Multi-step generation stays a host loop.

• Follow-up actions: storylm0_kv_step.kina, host .so numeric check.

• Date: 2026-08-23

• Scope (files/sections): docs/10-spec/12-phase-1/18-seeded-sampling.md, docs/30-decisions/44-storylm0-seeded-sampling.md, retarget of Section 17 open issue 1

• Reason for change: Specify seeded categorical sampling as existing arithmetic (host Uniform, Gumbel-max, Section 17 argmax) before adding the example. No new operator. Seed stays on the host.

• Decision impact: One .kina program can draw class ids from softmax(logits / T) given host noise. Top-k / top-p and KV-cache stay out of scope.

• Follow-up actions: storylm0_sample.kina, host .so numeric check.

• Date: 2026-08-23

• Scope (files/sections): docs/10-spec/12-phase-1/17-argmax.md, docs/30-decisions/43-storylm0-argmax.md, retarget of Section 16 open issue 3

• Reason for change: Lock Phase 0 argmax as a host reduce: I64 result (prose, not the typed-rule box), lowest-index tie-break, no VJP. argmin stays unimplemented.

• Decision impact: Greedy token ids type-check and lower on the host. Sampling and KV-cache stay out of scope.

• Follow-up actions: argmax_axis1.kina, storylm0_greedy.kina, host .so numeric check including a tie.

• Date: 2026-08-23

• Scope (files/sections): docs/10-spec/12-phase-1/16-functional-adamw.md, docs/30-decisions/42-storylm0-functional-adamw.md, retarget of Section 11 / 15 AdamW open issues

• Reason for change: Specify AdamW as existing arithmetic (PyTorch decoupled algebra) before adding the step example. No new operator. Host provides scalars including one and β**t (host pow does not lower to .so).

• Decision impact: One .kina program can update (w, m, v). Decoder-wide AdamW, argmax, and sampling stay out of scope.

• Follow-up actions: adamw_step.kina, host .so numeric check.

• Date: 2026-08-23

• Scope (files/sections): docs/10-spec/12-phase-1/15-nll-decoder-train.md, docs/30-decisions/41-storylm0-nll-decoder-train.md, retarget of Section 14 open issues 3–4

• Reason for change: Specify NLL ∘ decoder and multi-weight SGD as composition of Sections 9–14 before adding the train-step example. No new operator. Seed ones on [B, T] NLL is sum, not mean.

• Decision impact: One .kina program can return per-token NLL and SGD every trainable decoder weight. AdamW, mean NLL, and sampling stay out of scope.

• Follow-up actions: storylm0_nll_step.kina, host .so numeric check.

• Date: 2026-08-23

• Scope (files/sections): docs/10-spec/12-phase-1/14-decoder-ad.md, docs/30-decisions/40-storylm0-decoder-ad.md, retarget of Section 13 open issues

• Reason for change: Specify restricted reshape / variadic-batch matmul / 2D gather VJPs before implementing them. Gather cotangent is IR-internal ScatterAdd, not ScatterAlongAxis. Discrete parameters omitted from the reverseMode tuple.

• Decision impact: The StoryLM-0 decoder graph becomes differentiable in transform_ad. One program can SGD the embedding table. Not Phase 2 handler AD.

• Follow-up actions: Host VJP lowering, compile/golden/structural tests, .so numeric check. Device scatter-add and multi-weight SGD remain follow-on.

• Date: 2026-08-23

• Scope (files/sections): docs/10-spec/12-phase-1/13-tuple-projection.md, docs/30-decisions/39-tuple-projection.md, retarget of Section 11 / 12 open issues

• Reason for change: Specify destructuring let (y, g) = … before adding a way to name reverseMode results. Not a tensor operator.

• Decision impact: One .kina program can be loss → VJP → SGD for the neg instance. Nested patterns and AD through projection stay out of scope.

• Follow-up actions: Parser / LetTuple / ad_sgd_step.kina / .so numeric check.

• Date: 2026-08-23

• Scope (files/sections): docs/10-spec/12-phase-1/12-reversemode-result-abi.md, docs/30-decisions/38-reversemode-result-abi.md, retarget of Section 10 / 11 open issues

• Reason for change: Specify how reverseMode results leave the compiler before changing @main / fn lowering. Flat tuple type; MLIR multi-result, not tuple<>.

• Decision impact: @main and wrapper fns can return primal plus parameter gradients. Host .so grads become possible. Loss → VJP → SGD in one program still waits on tuple projection.

• Follow-up actions: Emitter flattening, ad_neg_grad.kina, .so numeric check.

• Date: 2026-08-23

• Scope (files/sections): docs/10-spec/12-phase-1/11-functional-sgd.md, docs/30-decisions/37-storylm0-functional-sgd.md

• Reason for change: Specify functional SGD as existing broadcast / mul / sub before adding examples. No new operator.

• Decision impact: Training update is a composition, not a primitive. AdamW deferred. AD→SGD wiring still waits on the reverseMode result ABI.

• Follow-up actions: sgd_step.kina, negative shape test, .so numeric check.

• Date: 2026-08-23

• Scope (files/sections): docs/10-spec/12-phase-1/10-log-softmax-and-take-along-axis-ad.md, docs/30-decisions/36-storylm0-loss-ad.md, retarget of 09-log-softmax-and-take-along-axis.md §6

• Reason for change: Specify restricted compiler VJPs for StoryLM-0 loss ops before implementing them. Scatter is IR-internal; no new surface form.

• Decision impact: neg / log_softmax / take_along_axis become differentiable in transform_ad. Not Phase 2 handler AD. No @main tuple-return ABI.

• Follow-up actions: Host VJP lowering, compile/golden/structural tests, reference-formula FD/PyTorch script. Device take and Kina-executed grads remain follow-on.

• Date: 2026-08-23

• Scope (files/sections): docs/10-spec/12-phase-1/09-log-softmax-and-take-along-axis.md, docs/30-decisions/35-storylm0-loss-ops.md, surface tables in 01-surface-kina.md / 02-surface-kina.md

• Reason for change: Specify StoryLM-0 loss ops (log_softmax, take_along_axis) before implementing them. Do not extend 2D gather. NLL is a composition.

• Decision impact: Two new primitives; AD VJPs and device take_along_axis deferred.

• Follow-up actions: Host typing, lowering, negative tests, and goldens land with this slice. AD VJPs and device take_along_axis remain follow-on.

• Date: 2026-05-08

• Scope (files/sections): Snapshot guard bootstrap (snapshots/, scripts/docs-snapshot*.sh, Justfile targets)

• Reason for change: Add an explicit mechanism to detect and review spec/documentation drift.

• Decision impact: Documentation changes are now expected to be tracked with a short rationale before snapshot baseline updates.

• Follow-up actions: Use just check-doc-snapshot in review flow; refresh baseline with just snapshot-docs after intentional doc edits.