Make great documentation goal 1.2, and plan the README's reorganisation and the nested-template gaps #33

Open
lilleman wants to merge 966 commits from worktree-todo-relative-dates-exact-counts into main
2 changed files with 7 additions and 8 deletions
Showing only changes of commit b6f3df2c9f - Show all commits
+5 -6
View File
@@ -832,11 +832,10 @@ Valid while names are read only inside the category binding them.
## The template engine stays the root package until item 107, and what stands alone lives in `internal/`
2026-10-05, Lilleman auf Larv. Serves goals 3.2 and 3.4. Two architect reviews found the
engine's types, `template`, `table`, `arm`, `op`, `nameBinding` and the draw state, bound in
one cycle because several passes each write part of the same structs; the template
engine's types, `template`, `table`, `arm`, `op` and `nameBinding`, bound in one cycle because several passes each write part of the same structs; the template
language's recursion needs only a little of it. Moving the engine before items 101 to 106
give each value one writer would spread that knot across packages, behind forwarding calls
from every public method. The grammar, the draw state and the reading of data files read no
engine type; `DataType`, the proofs' bounds, the builtins and a table's rows stop reading one
once items 99, 100 and 102 cut their edges, so they move now, each behind an import list a
test checks. Valid until `todo.md` item 107 moves the engine.
from every public method. The draw state and `DataType` read no engine type, and `DataType`
moves with the proofs' bounds keyed by it; the grammar, the reading of data files, the
proofs' bounds, the builtins and a table's rows stop reading one once items 98 to 103 cut
their edges, so they move now, each behind an import list a test checks. Valid until `todo.md` item 107 moves the engine.
+2 -2
View File
@@ -256,7 +256,7 @@ Needs item 5 to score 7.0 or above, per `AGENTS.md`'s comprehension rule. Goal 1
### 102. Move a table's rows, with their family, proofs, pins, row draws and lookups, into `internal/rows`, and walk a path through one per-step function that refuses a level carrying a `repeat` in the load check and in `Fake` alike.
Needs items 97 and 101. `internal/rows` owns the parent and child links; the root's table holds `{rows, format, cellTemplates}` and finds its relatives through those links, so the family has one writer and `internal/rows` never sees a template. The lookups keep the weights `sumWeights` parsed, where `builtLookup` parses them again. Today `pathCheck.walk` and `probePath` are two loops over one rule for passing a choice, a table or a field, and they have drifted: `probePath` skips `pathCheck.enter`, so `Fake("x.a")` under `"repeat":3` renders one draw where the README's Correlated fields section refuses it; the refusal owes a `CHANGELOG.md` entry. The shared step takes its state as parameters, as `drawSteps` does: one loop switching on a mode raised a repeat of a reference path from 66 to 106 allocations (decision "A path draws through its compiled steps"). Technical principle: DRY.
Needs items 98 and 101. `internal/rows` owns the parent and child links, and each rows table carries the engine table holding it as a payload set when it is built, so a step to a relative reaches its format and cells with no side map: the family has one writer, and `internal/rows` never sees a template. The rows code reads `checkName` and the selector spelling from `internal/grammar`. The lookups keep the weights `sumWeights` parsed, where `builtLookup` parses them again. Today `pathCheck.walk` and `probePath` are two loops over one rule for passing a choice, a table or a field, and they have drifted: `probePath` skips `pathCheck.enter`, so `Fake("x.a")` under `"repeat":3` renders one draw where the README's Correlated fields section refuses it; the refusal owes a `CHANGELOG.md` entry. The shared step takes its state as parameters, as `drawSteps` does: one loop switching on a mode raised a repeat of a reference path from 66 to 106 allocations (decision "A path draws through its compiled steps"). Technical principle: DRY.
### 97. Move the seeded randomness and its `{seq()}` counters into `internal/drawstate`, built from a seed, and test which packages each package may import.
@@ -294,7 +294,7 @@ The decision "With only the shipped set, a category loads on the first call reac
### 99. Move `DataType` into `internal/datatype`, aliased by the root, and what a proof knows of a value, `proven`, into `internal/proven`.
Needs item 98. `proven` is keyed by `DataType`, and a package the root imports cannot import the root, so the type moves first. The root declares `type DataType = datatype.DataType` and its four constants by name, so the public spelling stays one; pkg.go.dev then lists the methods under the internal package, which the maintainer accepted on 2026-10-05. `internal/proven` takes `proven` and the arithmetic over it, `combine`, `bounded`, `printing` and the literal and number readers; proving a node stays with the engine in `valueproof.go`.
Needs item 98. `proven` is keyed by `DataType`, and a package the root imports cannot import the root, so the type moves first. The root declares `type DataType = datatype.DataType` and its four constants by name, so the public spelling stays one; pkg.go.dev then lists the methods under the internal package, which the maintainer accepted on 2026-10-05. `internal/datatype` takes `dataTypeNames` and `dataTypeNouns` with the type. `internal/proven` takes `proven` and the arithmetic over it, `combine`, `bounded`, `printing`, `shortestDecimals` and the literal and number readers, and imports `internal/grammar` for the `calc` syntax `combine` reads; proving a node stays with the engine in `valueproof.go`.
### 105. Link each template in steps that each return what they build — its references, its bindings' heads and addressed keys, its compiled arms, its column read — so no step writes into what an earlier one built.