Answer stability round 1: README's pick.go and datatype.go rows name what stayed, geo.py's options sort with each script's own, geo.py claims only shared steps, route defines fromRow as pathPos does, and disagreement's panic names the kinds

README.md

@@ -967,7 +967,7 @@ node.go         the node model and JSON -> node compilation
 table.go        tables: their options, format and cells, the link to the parent beside them, and how a path passes and draws a table
 name.go         names: {x as n} bindings, the scopes they live in, the reads they answer, and what each resolves to at load: its target, its reads and the keys they address
 namefence.go    the load fences over names
-pick.go         a render's named picks: the frames of the name scopes rendering, the memo a pick keeps, and the reads kept under it
+pick.go         a render's named picks: the frame of each name scope rendering, the memo a pick keeps, and the reads kept under it
 env.go          renderEnv: what a render reads names and rows through, the stack of frames it renders in, and the frames a read opens and finds
 path.go         the dotted-path walks, and proving a path reaches a node
 render.go       Fake, the recursive renderer (choices, format strings, expansions) and the reads its tokens make
@@ -981,7 +981,7 @@ resolve.go      resolving templates against the assembled tree in steps, each ov
 graph.go        the node graph: tree walks, containment and render edges, and the cycle and repeat fences
 sorted.go       sortedNames: a map's keys, sorted
 calc.go         the {calc()} operand checks: never a number, and a constant zero divisor
-datatype.go     column datatypes: DataType, where datatype and null may sit, a column's datatype
+datatype.go     column datatypes: DataType, a template's declared datatype, a column's datatype
 valueproof.go   the value proof: what a typed column, calc operand or struct field holds, checked at load
 data.go         the load path: the categories internal/datafiles hands over, compiled into one merged tree, and the load pipeline every entry point runs
 cmd/fejkdata/   the fejkdata CLI

data-import/geo-se.py

@@ -170,9 +170,7 @@ def streets(segments, codes, localities, per_locality):
 
 
 def main():
-    p = geo.parser(__doc__, "SE")
-    p.add_argument("--key-file", help="file holding the Trafikverket API key; TRAFIKVERKET_API_KEY otherwise")
-    a = p.parse_args()
+    a = geo.parser(__doc__, "SE", key_file={"help": "file holding the Trafikverket API key; TRAFIKVERKET_API_KEY otherwise"}).parse_args()
     key = Path(a.key_file).read_text().strip() if a.key_file else os.environ.get("TRAFIKVERKET_API_KEY")
     if not key:
         sys.exit("set TRAFIKVERKET_API_KEY or pass --key-file")

data-import/geo-us.py

@@ -154,9 +154,7 @@ def streets(cache, counties, locality_of_zcta, per_locality):
 
 
 def main():
-    p = geo.parser(__doc__, "US")
-    p.add_argument("--min-population", type=int, default=25000)
-    a = p.parse_args()
+    a = geo.parser(__doc__, "US", min_population={"type": int, "default": 25000}).parse_args()
     cache, out = geo.directories(a)
 
     state_population = {r["STATE"]: r[ESTIMATE] for r in csv_rows(cache, STATES, "nst-est2025.csv") if r["SUMLEV"] == "040"}

data-import/geo.py

@@ -1,4 +1,4 @@
-"""The steps every country's geo import takes."""
+"""The steps a country's geo import may share with another's."""
 import argparse
 import collections
 import math
@@ -9,12 +9,12 @@ DATA = Path(__file__).resolve().parent.parent / "data" / "geo"
 CACHE = Path(__file__).resolve().parent / "cache"
 
 
-def parser(doc, country):
-    """The options every country's import takes; a script adds its own before parse_args."""
+def parser(doc, country, **own):
+    """The options every country's import takes and the script's own, keyed by name with "_" for "-", in name order."""
+    options = {"cache": {"default": str(CACHE)}, "out": {"default": str(DATA / country)}, "streets_per_locality": {"type": int, "default": 10}, **own}
     p = argparse.ArgumentParser(description=doc.splitlines()[0])
-    p.add_argument("--cache", default=str(CACHE))
-    p.add_argument("--out", default=str(DATA / country))
-    p.add_argument("--streets-per-locality", type=int, default=10)
+    for name in sorted(options):
+        p.add_argument("--" + name.replace("_", "-"), **options[name])
     return p
 
 

datatype.go

@@ -156,7 +156,7 @@ func disagreement(a *template, da DataType, b *template, db DataType) error {
 	}
 	message, ok := disagreements[[2]itemKind{kindOf(c.fix), kindOf(c.other)}]
 	if !ok {
-		panic(invariant.Broken("two text items hold one datatype, so they never disagree"))
+		panic(invariant.Broken("disagreement has no message for item kinds %d and %d; two text items hold one datatype, so they never disagree", kindOf(c.fix), kindOf(c.other)))
 	}
 	return message(c)
 }

table.go

@@ -246,7 +246,7 @@ type tableRoute struct {
 }
 
 // route is how tail passes t. fromRow means the previous route stepped into t
-// from a row of an ancestor table, so t reads a row even where tail is empty; a
+// from a row of a table linked to it, so t reads a row even where tail is empty; a
 // table reached otherwise, with no selector and an empty tail, is left to a render's
 // own draw.
 func (t *table) route(tail []string, fromRow bool) (tableRoute, error) {