Name the fence drawFence and the route surveyRoute, and move the survey tests to readsurvey_test.go

AGENTS.md

@@ -110,5 +110,5 @@ In [docs/decisions.md](docs/decisions.md):
 - The Swedish ids draw Skatteverket's test series
 - The US given names come from a mirror of the SSA file
 - `List` advertises direct descents only
-- Each entry point to `readFence.hasRead` says what its caller gets
+- Each entry point to `drawFence.hasRead` says what its caller gets
 - The four path walks are four loops

data.go

@@ -246,7 +246,7 @@ func checkRenders(s nodeScope) error {
 	if err := s(heldCheck); err != nil {
 		return err
 	}
-	fence := &readFence{}
+	fence := &drawFence{}
 	refs := false
 	if err := s(func(path string, n node) error {
 		if t, ok := n.(*template); ok && len(t.link.refs) > 0 {

doc.go

@@ -37,4 +37,4 @@ package fejkdata
 //     its cells stand in as `surveyAt.wholePins`, beside `surveyAt.wholeTable`.
 //   - fence — a load-time check, so rendering a compiled tree cannot fail: `New`
 //     runs them over the data set, `NewTemplate` and `FakeStruct` over what those
-//     compile. The draw fences are `heldCheck`, `readFence` and `checkFamilies`.
+//     compile. The draw fences are `heldCheck`, `drawFence` and `checkFamilies`.

docs/decisions.md

@@ -668,7 +668,7 @@ import drops them by name rather than by a rank a regeneration would move.
 the set of every descent through a chain of five tables is every subsequence of it, and
 the direct chain is the one a reader can predict from the tables' parents.
 
-## Each entry point to `readFence.hasRead` says what its caller gets
+## Each entry point to `drawFence.hasRead` says what its caller gets
 
 2026-09-25, larv-review; approved 2026-09-25 by lilleman. Goal 2: a reader lands on
 `readsPath` or `splitsDraws` from its caller, so each doc states where that walk stops,

drawfence.go

@@ -36,11 +36,11 @@ func checkNestedDrawGroup(fields map[string]node, group string) error {
 	return nil
 }
 
-// readFence fences each template of a scope as a render of its own, remembering which nodes read a
+// drawFence fences each template of a scope as a render of its own, remembering which nodes read a
 // reference path.
 // docs/decisions.md#a-render-shares-one-reference-draw-per-category-per-group
 // docs/decisions.md#the-expansion-hold-and-the-renders-draws-are-two-fences
-type readFence struct {
+type drawFence struct {
 	memo map[hasReadMemo]bool
 }
 
@@ -51,14 +51,14 @@ type hasReadMemo struct {
 
 // checkDrawGroup refuses a draw group that splits nothing: one whose render reads every reference
 // path inside a repeat or a nested draw group, which draw apart from it whatever it names.
-func (c *readFence) checkDrawGroup(path string, n node) error {
+func (c *drawFence) checkDrawGroup(path string, n node) error {
 	if t, ok := n.(*template); ok && t.drawGroup != "" && !c.splitsDraws(t) {
 		return fmt.Errorf("%s: drawGroup %q splits nothing, since nothing it renders reads a reference path outside a repeat or a nested drawGroup; drop it", path, t.drawGroup)
 	}
 	return nil
 }
 
-func (c *readFence) checkDraws(path string, n node) error {
+func (c *drawFence) checkDraws(path string, n node) error {
 	t, ok := n.(*template)
 	if !ok {
 		return nil
@@ -116,7 +116,7 @@ func checkOwnFamily(t *template) error {
 // checkRecordDraws fences the columns of a record — a template compiled at the top without a
 // repeat — so a load proves the record view of it as well as the string view.
 // docs/decisions.md#a-category-never-references-itself-and-a-records-fences-run-at-load
-func (c *readFence) checkRecordDraws(path string, n node) error {
+func (c *drawFence) checkRecordDraws(path string, n node) error {
 	t, ok := n.(*template)
 	if !ok || !t.isRecord {
 		return nil
@@ -138,15 +138,15 @@ func (c *readFence) checkRecordDraws(path string, n node) error {
 
 // readsPath reports whether rendering n reads a reference path, short of a repeat, which renders
 // over draws of its own.
-func (c *readFence) readsPath(n node) bool { return c.hasRead(n, false) }
+func (c *drawFence) readsPath(n node) bool { return c.hasRead(n, false) }
 
 // splitsDraws reports whether rendering n reads a reference path that n's own draw group answers
 // for: one outside a repeat and outside a nested draw group, which hold their own draws.
-func (c *readFence) splitsDraws(n node) bool { return c.hasRead(n, true) }
+func (c *drawFence) splitsDraws(n node) bool { return c.hasRead(n, true) }
 
 // hasRead walks what rendering n renders for a reference path, stopping at a repeat — and at a nested
 // draw group when stopAtGroup — since each holds draws of its own.
-func (c *readFence) hasRead(n node, stopAtGroup bool) bool {
+func (c *drawFence) hasRead(n node, stopAtGroup bool) bool {
 	k := hasReadMemo{n, stopAtGroup}
 	if r, done := c.memo[k]; done {
 		return r
@@ -200,15 +200,15 @@ func checkColumnDraws(t *template, columns []string) error { return surveyColumn
 // check refuses what one draw per reference path cannot answer for: a read of a level beside a path
 // another read takes into it, and two reads of one table family that select different rows. Reads
 // are compared in path order, so which pair is reported does not vary.
-func (w *readSurvey) check() error {
-	sort.SliceStable(w.reads, func(i, j int) bool {
-		if w.reads[i].at.group != w.reads[j].at.group {
-			return w.reads[i].at.group < w.reads[j].at.group
+func (s *readSurvey) check() error {
+	sort.SliceStable(s.reads, func(i, j int) bool {
+		if s.reads[i].at.group != s.reads[j].at.group {
+			return s.reads[i].at.group < s.reads[j].at.group
 		}
-		return w.reads[i].a.path < w.reads[j].a.path
+		return s.reads[i].a.path < s.reads[j].a.path
 	})
-	for i, level := range w.reads {
-		for _, into := range w.reads[i+1:] {
+	for i, level := range s.reads {
+		for _, into := range s.reads[i+1:] {
 			if into.at.group != level.at.group || alternatives(level.at, into.at) {
 				continue
 			}
@@ -217,7 +217,7 @@ func (w *readSurvey) check() error {
 			}
 		}
 	}
-	return checkFamilies(w.reads)
+	return checkFamilies(s.reads)
 }
 
 // checkFamilies refuses reads of one table family in one draw group that cannot
@@ -303,6 +303,6 @@ func alternatives(a, b surveyAt) bool {
 	return a.pins.differs(&b.pins) || a.wholePins.differs(&b.wholePins)
 }
 
-func overlapError(route readRoute, ref string, into pathRead) error {
+func overlapError(route surveyRoute, ref string, into pathRead) error {
 	return fmt.Errorf("%s renders a level that %s reads a path into; name the fields you want instead, or draw them apart with a drawGroup", route.spelled(ref), into.at.route.spelled(into.a.spelling))
 }

drawfence_test.go

@@ -1,10 +1,6 @@
 package fejkdata
 
-import (
-	"strings"
-	"testing"
-	"testing/fstest"
-)
+import "testing"
 
 func fenceCorpus(t *testing.T) *Generator {
 	t.Helper()
@@ -58,104 +54,6 @@ func fenceRoots(t *testing.T, f *Generator) ([]fenceRoot, map[string]*table) {
 	return append(roots, fenceRoot{"inline record", record.template}), tables
 }
 
-func TestEveryReadARenderMakesIsGathered(t *testing.T) {
-	f := fenceCorpus(t)
-	roots, tables := fenceRoots(t, f)
-	traced := 0
-	for _, root := range roots {
-		traced += wantGathered(t, tables, root.label, surveyRender(root.t).reads, func(trace renderTrace) { renderRoot(f.rand, root.t, trace) })
-		if !root.t.isRecord || len(root.t.fields) == 0 {
-			continue
-		}
-		_, columns, err := recordOf(root.t)
-		if err != nil {
-			t.Fatalf("%s: recordOf = %v", root.label, err)
-		}
-		traced += wantGathered(t, tables, root.label+" as a record", surveyColumns(root.t, sortedNames(root.t.fields)).reads, func(trace renderTrace) { renderRecordRoot(f.rand, root.t, columns, trace) })
-	}
-	if traced == 0 {
-		t.Error("no render traced a reference read, so the comparison proved nothing")
-	}
-}
-
-func wantGathered(t *testing.T, tables map[string]*table, label string, gathered []pathRead, renderWith func(renderTrace)) int {
-	t.Helper()
-	var reads []pathRead
-	type traceKey struct {
-		group, path, table string
-		row                int
-	}
-	seen := map[traceKey]bool{}
-	trace := func(group, table string, row int, a arm) {
-		if !isRef(a.key) {
-			return
-		}
-		r := pathRead{at: surveyAt{group: group}, a: a}
-		if table != "" {
-			r.at.pins.add(tables[table], row)
-		}
-		if k := (traceKey{group, a.path, table, row}); !seen[k] {
-			seen[k] = true
-			reads = append(reads, r)
-		}
-	}
-	for i := 0; i < 5; i++ {
-		renderWith(trace)
-	}
-	for _, r := range reads {
-		if !gathers(gathered, r) {
-			t.Errorf("%s: the render read {%s} in draw group %q from %s, and readSurvey gathered no such read", label, r.a.spelling, r.at.group, spellPins(&r.at.pins))
-		}
-	}
-	return len(reads)
-}
-
-func gathers(gathered []pathRead, r pathRead) bool {
-	for _, g := range gathered {
-		if g.at.group == r.at.group && g.a.path == r.a.path && !g.at.pins.differs(&r.at.pins) && !g.at.wholePins.differs(&r.at.pins) {
-			return true
-		}
-	}
-	return false
-}
-
-func spellPins(p *pinSet) string {
-	var rows []string
-	p.each(func(t *table, r int) { rows = append(rows, t.selectorSpelling(r)) })
-	if len(rows) == 0 {
-		return "no row"
-	}
-	return "row " + strings.Join(rows, ", ")
-}
-
-func renderRoot(s *session, t *template, trace renderTrace) {
-	set := holdSet{trace: trace}
-	sc := renderScope{set: &set}
-	switch {
-	case t.table != nil:
-		render(s, t.table, sc)
-		for r := 0; r < t.table.rowCount(); r++ {
-			set := holdSet{trace: trace}
-			sc := renderScope{set: &set}
-			sc.groupHold().pins.pin(t.table, r)
-			render(s, t.table.pinnedRow, sc.at(t.table.pinnedRow, &sc.groupHold().pins))
-		}
-	case t.repeat > 1:
-		expand(s, t, sc)
-	default:
-		render(s, t, sc)
-	}
-}
-
-func renderRecordRoot(s *session, t *template, columns []Column, trace renderTrace) {
-	set := holdSet{trace: trace}
-	sc := renderScope{set: &set}
-	if t.table != nil {
-		t.table.drawIn(s, &sc.groupHold().pins)
-	}
-	renderRecord(s, t, columns, sc)
-}
-
 func TestReplayPairsFindsWhatAWholeReplayFinds(t *testing.T) {
 	corpus := fenceCorpus(t)
 	roots, _ := fenceRoots(t, corpus)
@@ -279,35 +177,3 @@ func eachRenderSet(reads []pathRead, fn func([]pathRead)) {
 	}
 	grow(nil, reads, nil)
 }
-
-func TestDrawWalkWalksACellByEveryRoute(t *testing.T) {
-	fsys := fstest.MapFS{
-		"g.json": {Data: []byte(`{"format":"{/x.v}","drawGroup":"g2"}`)},
-		"r.json": {Data: []byte(`"{/g} {/x}"`)},
-		"x.json": {Data: []byte(`{"format":"{/g}","rows":"x.tsv","key":"code"}`)},
-		"x.tsv":  {Data: []byte("code\tv\n1\t{/z}\n2\t{/z.a}\n")},
-		"z.json": {Data: []byte(`{"format":"{a}","a":"hi"}`)},
-	}
-	g, err := loadDir(dataSource{fsys: fsys}, ".")
-	if err != nil {
-		t.Fatalf("loadDir = %v", err)
-	}
-	if err := treeBinding(g.children).link(); err != nil {
-		t.Fatalf("link = %v", err)
-	}
-	r, isTemplate := g.children["r"].(*template)
-	if !isTemplate {
-		t.Fatalf("r is a %T, want a template", g.children["r"])
-	}
-	var pinned, whole bool
-	for _, read := range surveyRender(r).reads {
-		if read.a.path != "/z" {
-			continue
-		}
-		pinned = pinned || read.at.pins.used > 0
-		whole = whole || read.at.wholePins.used > 0
-	}
-	if !pinned || !whole {
-		t.Errorf("{/z} gathered under a pinned row %v and a whole read's row %v, want both: {/g} reaches x's cells from the root and from inside {/x}", pinned, whole)
-	}
-}

holdfence.go

@@ -18,7 +18,7 @@ func heldCheck(path string, n node) error {
 	readers := pathKeyReaders(t.compiled.ops, t.compiled.pathKeys)
 	for _, name := range heldNames(t) {
 		if _, isPath := t.compiled.pathKeys[name]; isPath && isRef(name) {
-			continue // held for the render: readFence compares every read of it, by path, across the render and its groups
+			continue // held for the render: drawFence compares every read of it, by path, across the render and its groups
 		}
 		if err := checkNameHeld(t, name, readers); err != nil {
 			return fmt.Errorf("%s: %w", path, err)

readsurvey.go

@@ -13,19 +13,19 @@ type readSurvey struct {
 	pinIDs map[pinsLink]pinsID
 }
 
-// surveyAt is where a survey stands: the draw group it draws in, how the render's root reached it, the
+// surveyAt is where a survey stands: the draw group its reads draw in, how the render's root reached it, the
 // table rows it pinned, the table a whole read draws a row of, and the rows of whole draws whose
 // cells the walk is in.
 type surveyAt struct {
 	group      string
-	route      readRoute
+	route      surveyRoute
 	pins       pinSet
 	wholeTable *table
 	wholePins  pinSet
 }
 
-// readRoute is how a render reaches a read: as its author spells it, and the root edge's label.
-type readRoute struct{ spelling, label string }
+// surveyRoute is how a render reaches a draw: as its author spells it, and the root edge's label.
+type surveyRoute struct{ spelling, label string }
 
 // pathRead is one reference a render reads: a path, or a bare reference with no tail.
 type pathRead struct {
@@ -63,32 +63,32 @@ func newReadSurvey() *readSurvey {
 }
 
 func surveyRender(t *template) *readSurvey {
-	w := newReadSurvey()
+	s := newReadSurvey()
 	for _, e := range renderEdges(t) {
-		w.edge(t, e, surveyAt{group: t.link.drawGroupKey, route: readRoute{e.reached(), e.label}})
+		s.edge(t, e, surveyAt{group: t.link.drawGroupKey, route: surveyRoute{e.reached(), e.label}})
 	}
-	return w
+	return s
 }
 
 func surveyColumns(t *template, columns []string) *readSurvey {
-	w := newReadSurvey()
+	s := newReadSurvey()
 	for _, name := range columns {
-		w.walk(t.fields[name], surveyAt{group: t.link.drawGroupKey, route: readRoute{spelling: fmt.Sprintf("column %q", name)}})
+		s.walk(t.fields[name], surveyAt{group: t.link.drawGroupKey, route: surveyRoute{spelling: fmt.Sprintf("column %q", name)}})
 	}
-	return w
+	return s
 }
 
-func (w *readSurvey) pinsID(p *pinSet) pinsID {
+func (s *readSurvey) pinsID(p *pinSet) pinsID {
 	var pins []tablePin
 	p.each(func(t *table, r int) { pins = append(pins, tablePin{t, r}) })
 	sort.Slice(pins, func(i, j int) bool { return pins[i].t.path < pins[j].t.path })
 	id := pinsID(0)
 	for _, q := range pins {
 		l := pinsLink{id, q}
-		next, ok := w.pinIDs[l]
+		next, ok := s.pinIDs[l]
 		if !ok {
-			next = pinsID(len(w.pinIDs) + 1)
-			w.pinIDs[l] = next
+			next = pinsID(len(s.pinIDs) + 1)
+			s.pinIDs[l] = next
 		}
 		id = next
 	}
@@ -99,12 +99,12 @@ func (w *readSurvey) pinsID(p *pinSet) pinsID {
 // there. A cell whose row the pins keep out has no case: a pinned table renders its pinned row
 // alone and an unpinned one draws a row inside its nearest pinned ancestor's, so that cell never
 // renders on this route.
-func (w *readSurvey) walk(n node, at surveyAt) {
-	v := nodeVisit{n, at.group, at.wholeTable, w.pinsID(&at.pins), w.pinsID(&at.wholePins)}
-	if w.seen[v] {
+func (s *readSurvey) walk(n node, at surveyAt) {
+	v := nodeVisit{n, at.group, at.wholeTable, s.pinsID(&at.pins), s.pinsID(&at.wholePins)}
+	if s.seen[v] {
 		return
 	}
-	w.seen[v] = true
+	s.seen[v] = true
 	if repeats(n) {
 		return
 	}
@@ -122,40 +122,40 @@ func (w *readSurvey) walk(n node, at surveyAt) {
 		}
 		switch {
 		case cell.table == nil:
-			w.edge(n, e, at)
+			s.edge(n, e, at)
 		case cell.table == at.wholeTable:
 			in := at
 			in.wholePins = at.wholePins.clone()
 			in.wholePins.add(cell.table, cell.row)
-			w.edge(n, e, in)
+			s.edge(n, e, in)
 		case at.pins.clash(cell.table, cell.row) == nil:
 			in := at
 			in.pins = at.pins.entered(cell.table, cell.row)
-			w.edge(n, e, in)
+			s.edge(n, e, in)
 		}
 	}
 }
 
 // edge records the reference an edge reads, then walks on with every row the read
 // pins entered, so a selected row renders only its own cells.
-func (w *readSurvey) edge(from node, e renderEdge, at surveyAt) {
+func (s *readSurvey) edge(from node, e renderEdge, at surveyAt) {
 	if e.readsRef() {
 		a := e.read
 		tr := tableReadOf(from.(*template).head(a.key), a, e.to)
-		if k := (readKey{at.group, a.path, w.pinsID(&at.pins), w.pinsID(&at.wholePins)}); !w.read[k] {
-			w.read[k] = true
-			w.reads = append(w.reads, pathRead{at, a, tr})
+		if k := (readKey{at.group, a.path, s.pinsID(&at.pins), s.pinsID(&at.wholePins)}); !s.read[k] {
+			s.read[k] = true
+			s.reads = append(s.reads, pathRead{at, a, tr})
 		}
 		if tr != nil {
 			tr.pins.each(func(t *table, r int) { at.pins = at.pins.entered(t, r) })
 		}
 	}
-	w.walk(e.to, at)
+	s.walk(e.to, at)
 }
 
 // spelled names the route, and the reference it reaches a draw by where its root edge is not that
 // reference.
-func (r readRoute) spelled(ref string) string {
+func (r surveyRoute) spelled(ref string) string {
 	if ref == "" || ref == r.label {
 		return r.spelling
 	}

readsurvey_test.go

@@ -0,0 +1,137 @@
+package fejkdata
+
+import (
+	"strings"
+	"testing"
+	"testing/fstest"
+)
+
+func TestEveryReadARenderMakesIsGathered(t *testing.T) {
+	f := fenceCorpus(t)
+	roots, tables := fenceRoots(t, f)
+	traced := 0
+	for _, root := range roots {
+		traced += wantGathered(t, tables, root.label, surveyRender(root.t).reads, func(trace renderTrace) { renderRoot(f.rand, root.t, trace) })
+		if !root.t.isRecord || len(root.t.fields) == 0 {
+			continue
+		}
+		_, columns, err := recordOf(root.t)
+		if err != nil {
+			t.Fatalf("%s: recordOf = %v", root.label, err)
+		}
+		traced += wantGathered(t, tables, root.label+" as a record", surveyColumns(root.t, sortedNames(root.t.fields)).reads, func(trace renderTrace) { renderRecordRoot(f.rand, root.t, columns, trace) })
+	}
+	if traced == 0 {
+		t.Error("no render traced a reference read, so the comparison proved nothing")
+	}
+}
+
+func wantGathered(t *testing.T, tables map[string]*table, label string, gathered []pathRead, renderWith func(renderTrace)) int {
+	t.Helper()
+	var reads []pathRead
+	type traceKey struct {
+		group, path, table string
+		row                int
+	}
+	seen := map[traceKey]bool{}
+	trace := func(group, table string, row int, a arm) {
+		if !isRef(a.key) {
+			return
+		}
+		r := pathRead{at: surveyAt{group: group}, a: a}
+		if table != "" {
+			r.at.pins.add(tables[table], row)
+		}
+		if k := (traceKey{group, a.path, table, row}); !seen[k] {
+			seen[k] = true
+			reads = append(reads, r)
+		}
+	}
+	for i := 0; i < 5; i++ {
+		renderWith(trace)
+	}
+	for _, r := range reads {
+		if !gathers(gathered, r) {
+			t.Errorf("%s: the render read {%s} in draw group %q from %s, and readSurvey gathered no such read", label, r.a.spelling, r.at.group, spellPins(&r.at.pins))
+		}
+	}
+	return len(reads)
+}
+
+func gathers(gathered []pathRead, r pathRead) bool {
+	for _, g := range gathered {
+		if g.at.group == r.at.group && g.a.path == r.a.path && !g.at.pins.differs(&r.at.pins) && !g.at.wholePins.differs(&r.at.pins) {
+			return true
+		}
+	}
+	return false
+}
+
+func spellPins(p *pinSet) string {
+	var rows []string
+	p.each(func(t *table, r int) { rows = append(rows, t.selectorSpelling(r)) })
+	if len(rows) == 0 {
+		return "no row"
+	}
+	return "row " + strings.Join(rows, ", ")
+}
+
+func renderRoot(s *session, t *template, trace renderTrace) {
+	set := holdSet{trace: trace}
+	sc := renderScope{set: &set}
+	switch {
+	case t.table != nil:
+		render(s, t.table, sc)
+		for r := 0; r < t.table.rowCount(); r++ {
+			set := holdSet{trace: trace}
+			sc := renderScope{set: &set}
+			sc.groupHold().pins.pin(t.table, r)
+			render(s, t.table.pinnedRow, sc.at(t.table.pinnedRow, &sc.groupHold().pins))
+		}
+	case t.repeat > 1:
+		expand(s, t, sc)
+	default:
+		render(s, t, sc)
+	}
+}
+
+func renderRecordRoot(s *session, t *template, columns []Column, trace renderTrace) {
+	set := holdSet{trace: trace}
+	sc := renderScope{set: &set}
+	if t.table != nil {
+		t.table.drawIn(s, &sc.groupHold().pins)
+	}
+	renderRecord(s, t, columns, sc)
+}
+
+func TestReadSurveyWalksACellByEveryRoute(t *testing.T) {
+	fsys := fstest.MapFS{
+		"g.json": {Data: []byte(`{"format":"{/x.v}","drawGroup":"g2"}`)},
+		"r.json": {Data: []byte(`"{/g} {/x}"`)},
+		"x.json": {Data: []byte(`{"format":"{/g}","rows":"x.tsv","key":"code"}`)},
+		"x.tsv":  {Data: []byte("code\tv\n1\t{/z}\n2\t{/z.a}\n")},
+		"z.json": {Data: []byte(`{"format":"{a}","a":"hi"}`)},
+	}
+	g, err := loadDir(dataSource{fsys: fsys}, ".")
+	if err != nil {
+		t.Fatalf("loadDir = %v", err)
+	}
+	if err := treeBinding(g.children).link(); err != nil {
+		t.Fatalf("link = %v", err)
+	}
+	r, isTemplate := g.children["r"].(*template)
+	if !isTemplate {
+		t.Fatalf("r is a %T, want a template", g.children["r"])
+	}
+	var pinned, whole bool
+	for _, read := range surveyRender(r).reads {
+		if read.a.path != "/z" {
+			continue
+		}
+		pinned = pinned || read.at.pins.used > 0
+		whole = whole || read.at.wholePins.used > 0
+	}
+	if !pinned || !whole {
+		t.Errorf("{/z} gathered under a pinned row %v and a whole read's row %v, want both: {/g} reaches x's cells from the root and from inside {/x}", pinned, whole)
+	}
+}