From edec28f58f4ea3cb1cc0aeab9fa2f05b8fc0c93a Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Fri, 9 Oct 2026 13:07:59 +0200 Subject: [PATCH] Answer prose round 1: the Data paragraph names the set first, the choice comment says what shared counts, and the plan's new items read once --- README.md | 10 +++++----- data-import/tsv.py | 2 +- docs/decisions.md | 2 +- node.go | 2 +- todo.md | 16 ++++++++-------- 5 files changed, 16 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 25494f9..9c673f7 100644 --- a/README.md +++ b/README.md @@ -160,10 +160,10 @@ it to a name and read the name ## Data -The shipped set under [`data/`](data) — one folder per locale (`en_US`, `sv_SE`), -a `geo` folder holding a tree of places per country (`SE`, `US`), and a -locale-neutral `misc` folder — is embedded, so the CLI and the library work with -no data on disk. A directory is a namespace: each JSON file is a category named +The shipped set under [`data/`](data) is embedded, so the CLI and the library +work with no data on disk. It holds one folder per locale (`en_US`, `sv_SE`), a +`geo` folder with a tree of places per country (`SE`, `US`), and a +locale-neutral `misc` folder. A directory is a namespace: each JSON file is a category named after the file, each subdirectory a dot-path segment, so `mydata/sv_SE/person.json` is `sv_SE.person` and replaces the shipped one. Sources merge in order; matching folders combine, any other clash is won by the @@ -1018,7 +1018,7 @@ internal/proven/ what a proof knows of a value, and the bounds a calc takes from internal/rows/ a table's rows: the TSV, the options proved over it, the links between tables, row selection and draws, and the pin set one path or one named pick fixes data/ shipped data (JSON, and a TSV per table), embedded at build: locale folders, geo, misc data-import/ the scripts that rebuild each sourced table (see DATA-LICENSES.md), and the modules they share -docs/ the decision log, the register research behind the shipped data, the survey of other libraries, panels' scores of how readable the code is, and what each change cost to read +docs/ the decision log, the register research behind the shipped data, the survey of other libraries, panels' scores and rulings on how readable the code is, and what each chunk cost an agent to read release-tooling/ the release CI publishes from the changelog heading testdata/ the pinned shipped shape (see Versioning) ``` diff --git a/data-import/tsv.py b/data-import/tsv.py index 510f721..3d08a93 100644 --- a/data-import/tsv.py +++ b/data-import/tsv.py @@ -5,7 +5,7 @@ from pathlib import Path def write(path, columns, rows): - """Write the rows as a TSV of at least one row, each cell stripped, non-empty and free of tabs, newlines and braces.""" + """Write the rows as a TSV of a header and at least one row, each cell stripped, non-empty and free of tabs, newlines and braces.""" lines = ["\t".join(columns)] for row in rows: cells = [str(row[c]).strip() for c in columns] diff --git a/docs/decisions.md b/docs/decisions.md index 0b954a7..f2899a0 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -853,7 +853,7 @@ Valid while names are read only inside the category binding them. Shipped under the floor by the maintainer's decisions of 2026-10-07, each with the scoring run and its ratchet waived: the CLI reading its template from stdin; and goal 5.7 loading whatever is well-formed and means one thing, dropping every refusal that guessed at a mistake. -The scoring runs are in [the comprehension history](comprehension-history.md). The nine-seat panel at depth 1, run beside the scoring run of 2026-10-09 on commit b9d1af6: Navigation 7.33, Locality 6.17, Shape 6.67, Self-sufficiency 6.83, overall 6.67. Against the panel on ad59967, its overall rose from 6.56, its Navigation from 7.17, its Locality from 6.06 and its Self-sufficiency from 6.56, and its Shape held at 6.67. Locality is lowest again, as at every panel since 2026-09-22. All 13 seats of the two runs named the named-pick keep rule hardest: `keptInPick` and `readUnder`, whose keys must equal those `addressedKeys` builds at load, with `readField`, `readName` and the frames `enter` shares. What the two runs found is filed in `todo.md`, and `todo.md` item 177 runs both again. Valid while `AGENTS.md` gates goal 3 at 7.0. +The scoring runs are in [the comprehension history](comprehension-history.md). The nine-seat panel at depth 1, run beside the scoring run of 2026-10-09 on commit b9d1af6: Navigation 7.33, Locality 6.17, Shape 6.67, Self-sufficiency 6.83, overall 6.67. Against the panel on ad59967, its overall rose from 6.56, its Navigation from 7.17, its Locality from 6.06 and its Self-sufficiency from 6.56, and its Shape held at 6.67. Locality is lowest again, as at every panel since 2026-09-22. All 13 seats of the two runs found the named-pick keep rule hardest to follow: `keptInPick` and `readUnder`, where a key `pickKey.under` builds at render must equal one `addressedKeys` built at load, with `readField` and `readName` around them. What the two runs found is filed in `todo.md`, and `todo.md` item 177 runs both again. Valid while `AGENTS.md` gates goal 3 at 7.0. ## The template engine stays the root package until item 107; what reads no engine type, a table's rows included, sits in `internal/` diff --git a/node.go b/node.go index 375cc47..62ff5e8 100644 --- a/node.go +++ b/node.go @@ -29,7 +29,7 @@ func (*folder) isNode() {} // choice draws one of its items. cum holds cumulative weights for a weighted // draw; when nil the choice is uniform and selection is O(1). shared is the set of -// relative dot paths every item can address, into a repeat too. +// relative dot paths every item carries, counting paths inside a repeated template. type choice struct { items []node cum []float64 diff --git a/todo.md b/todo.md index 90928fb..a78bd32 100644 --- a/todo.md +++ b/todo.md @@ -86,9 +86,9 @@ | 171 | 0.1.0 | | **Handle a template that only reads one record column in one place, so `checkColumns`, `itemDatatype`, `proveColumnItem` and `renderLeaf` no longer each special-case `readsColumn`.** | 3 | 3 | 2 | 7 | 3, 3.2 | 12.8 | | 176 | 0.1.0 | question | **Group the root package's files by area in their names, so a listing shows the load, names, render, proof and API groups the README's Layout lists.** | 2 | 4 | 1 | 7 | 3.2 | 11.6 | | 175 | 0.1.0 | | **Rewrite the comments the 2026-10-09 panel needed several reads of, and delete those it read as restating their code.** | 1 | 2 | 1 | 6 | 3.4 | 11.3 | -| 172 | 0.1.0 | | **Pass `drawSteps` the kind of read it draws by name, where a nil `pins` means a sibling path and a nil `memo` a fresh read.** | 2 | 2 | 1 | 6 | 3.2 | 10.3 | +| 172 | 0.1.0 | | **Pass `drawSteps` the kind of read it draws as an argument of its own, so no caller signals a sibling path by a nil `pins` or a fresh read by a nil `memo`.** | 2 | 2 | 1 | 6 | 3.2 | 10.3 | | 173 | 0.1.0 | | **Call what a token reads its spelling, never a name, in `format.go`, `arm.go` and `reference.go`, so a name in the engine is only a bound name.** | 2 | 3 | 1 | 6 | 3.2 | 10.1 | -| 174 | 0.1.0 | | **Spell once the fact that a walk's next step leaves a selected row, which `pathPos.fromRow` and `tableRoute.nextLinked` name twice.** | 1 | 1 | 1 | 5 | 3.2 | 9.8 | +| 174 | 0.1.0 | | **Spell once the fact that a walk's next step leaves a selected row, which `pathPos.fromRow` and `tableRoute.nextLinked` each spell today.** | 1 | 1 | 1 | 5 | 3.2 | 9.8 | | 58 | 0.2.0 | | **Ship prebuilt binaries, a container image, and packages for Homebrew, Scoop and the biggest Linux package managers, so the CLI needs no Go.** | 3 | 7 | 8 | 9 | 1.1, 7 | 29.2 | | 113 | 0.2.0 | defect | **Draw `{iban(CC)}` with its country's national check digits, and SE's with a real bank's id, so a validator checking more than mod 97 accepts it.** | 3 | 5 | 7 | 9 | 4 | 25.0 | | 154 | 0.2.0 | | **Add `en_US.routing`, an ABA routing number over the Fed's prefix ranges with its check digit drawn by `{aba()}`.** | 2 | 2 | 6 | 7 | 2.2, 15 | 22.8 | @@ -185,7 +185,7 @@ Needs item 77. Ten streets per place crowds 500 Stockholm customers onto ten str ### 61. Add a locale, with its `geo/` tree, for each of the ten most-spoken languages and each Nordic country. -Pick the ten from a published ranking of languages by total speakers, such as Ethnologue's, each in the country where it has the most speakers, and record the ranking in the decision that names them. The Nordic ones are sv_SE (shipped), nb_NO, da_DK, fi_FI and is_IS. The extender seat of the 2026-10-09 panel, reading for this item, found nothing saying which of `geo-se.py`'s rules a new country takes: `well_cased` drops a name spelled in capitals, as Bring's register spells every poststed; a locality is keyed by name in SE and by code in US; and `data_test.go`'s `geoPlaces` reads every country but US by SE's column positions. A second country reading GeoNames' postal codes moves `geonames()` from `geo-se.py`, and the nearest-centroid street assignment in its `streets()`, into `geo.py`. Each locale carries goal 2.2's categories, and its `address` reads its country's `geo/` tree by reference. `rows.Pins` holds eight pins inline, sized for a five-deep geo tree; a deeper tree needs more to keep a render off the heap. +Pick the ten from a published ranking of languages by total speakers, such as Ethnologue's, each in the country where it has the most speakers, and record the ranking in the decision that names them. The Nordic ones are sv_SE (shipped), nb_NO, da_DK, fi_FI and is_IS. A new country decides three rules `geo-se.py` fixes for SE: `well_cased` drops a name spelled in capitals, and Bring's register spells every poststed so; a locality is keyed by name in SE and by code in US; and `data_test.go`'s `geoPlaces` reads every country but US by SE's column positions. A second country reading GeoNames' postal codes moves `geonames()` from `geo-se.py`, and the nearest-centroid street assignment in its `streets()`, into `geo.py`. Each locale carries goal 2.2's categories, and its `address` reads its country's `geo/` tree by reference. `rows.Pins` holds eight pins inline, sized for a five-deep geo tree; a deeper tree needs more to keep a render off the heap. ### 16. Add locale categories: company, phone, finance, vehicle, words. @@ -297,7 +297,7 @@ The maintainer ruled so on 2026-10-09. Today `bindOptions` in `internal/rows` re ### 170. Decide in one function whether a read lands in a name's pick, which `refuseTwiceDrawnIn` calls at load and `keptInPick` at render. -All 13 seats of the 2026-10-09 panel on b9d1af6 named `keptInPick` and `readUnder` hardest, and 12 would least want to modify the rule they apply. A key `addressedKeys` builds at load must equal the one `pickKey.under` builds at render, and a mismatch splits a correlated draw without an error. `refuseTwiceDrawnIn` applies the same rule at load in code of its own. Say there why a fresh read's levels start at its head, `levelKeys(…, 1)` in `pathArm`, and a named read's at its target, `levelKeys(full, 0)` in `compileArm`, which three seats rebuilt by hand. +All 13 seats of the 2026-10-09 panel on b9d1af6 named `keptInPick` and `readUnder` hardest, and 12 named the rule both apply as the code they would least want to change. A key `addressedKeys` builds at load must equal the one `pickKey.under` builds at render, and a mismatch splits a correlated draw without an error. `refuseTwiceDrawnIn` applies the same rule at load in code of its own. In the new function's comment, say why a fresh read's levels start at its head, `levelKeys(…, 1)` in `pathArm`, and a named read's at its target, `levelKeys(full, 0)` in `compileArm`, which three seats rebuilt by hand. ### 127. Give a Swedish street only postal codes whose delivery digit means street or rural delivery, dropping codes whose delivery digit is 9, or record why they stay. @@ -313,7 +313,7 @@ The maintainer ruled so on 2026-10-09. Today `checkSelectorCells` in `internal/r ### 171. Handle a template that only reads one record column in one place, so `checkColumns`, `itemDatatype`, `proveColumnItem` and `renderLeaf` no longer each special-case `readsColumn`. -Eleven seats of the 2026-10-09 panel named the field's "change them together" (`node.go`) as action at a distance across `datatype.go`, `valueproof.go` and `render.go`. +Eleven seats of the 2026-10-09 panel named the "change them together" in `readsColumn`'s comment (`node.go`) as action at a distance across `datatype.go`, `valueproof.go` and `render.go`. ### 176. Group the root package's files by area in their names, so a listing shows the load, names, render, proof and API groups the README's Layout lists. @@ -321,9 +321,9 @@ The architect seats of both 2026-10-09 runs named the 25 flat root files the wor ### 175. Rewrite the comments the 2026-10-09 panel needed several reads of, and delete those it read as restating their code. -Reread: `readField`'s note on clearing the pick (`render.go`), `pickKey.under`, which three seats read backwards, `scopeAround`'s "short of the frames n renders itself", `enter` returning `env.base` as the pop mark, and `walkEvery`'s three-index slice, which three seats found unmarked. Restating: `compileCells`, `columnOrLinked`, `render`'s first line, `categorySites`, `madeFolder`, `categoryOf`, `rendersInside`, `templateSite`, `templateOptions`, `compileFrom`, `flagArg`, `drawSeed`, the `calc` parser's precedence line in `internal/grammar`, and `compileChoice`'s note that a uniform choice draws in O(1), which `choice`'s doc already says. A doc comment `go doc` shows on an exported name stays. +Reread: `readField`'s note on clearing the pick (`render.go`), `pickKey.under`, which three seats read backwards, `scopeAround`'s "short of the frames n renders itself", `enter` returning `env.base` as the pop mark, and add a line at `walkEvery`'s three-index slice, which three seats found unmarked. Restating: `compileCells`, `columnOrLinked`, `render`'s first line, `categorySites`, `madeFolder`, `categoryOf`, `rendersInside`, `templateSite`, `templateOptions`, `compileFrom`, `flagArg`, `drawSeed`, the `calc` parser's precedence line in `internal/grammar`, and `compileChoice`'s note that a uniform choice draws in O(1), which `choice`'s doc already says. A doc comment `go doc` shows on an exported name stays. -### 172. Pass `drawSteps` the kind of read it draws by name, where a nil `pins` means a sibling path and a nil `memo` a fresh read. +### 172. Pass `drawSteps` the kind of read it draws as an argument of its own, so no caller signals a sibling path by a nil `pins` or a fresh read by a nil `memo`. Ten seats of the 2026-10-09 panel named `drawSteps` (`path.go`); three named the nil arguments as the mode they had to infer. @@ -331,7 +331,7 @@ Ten seats of the 2026-10-09 panel named `drawSteps` (`path.go`); three named the `checkReads` "proves each name t reads", `splitArm` "splits one name into head and tail" and asks `t.isName` of the result in `compileArm`, and `refTokens` returns "reference names". Both architect seats of the 2026-10-09 panel and the scoring run's architect named the word as one name over several concepts, against the decision "One name, one meaning". Item 136 did this for `internal/grammar`. -### 174. Spell once the fact that a walk's next step leaves a selected row, which `pathPos.fromRow` and `tableRoute.nextLinked` name twice. +### 174. Spell once the fact that a walk's next step leaves a selected row, which `pathPos.fromRow` and `tableRoute.nextLinked` each spell today. `compileStep` copies one into the other (`path.go`). Two seats of the 2026-10-09 panel named it.