docs/comprehension-history.md

@@ -472,3 +472,43 @@ Inherited architect, decided by:
 - Navigation: `data/modules.go:17` `Modules`: shipped data has a Go home inside data/, each module's manifest beside its files
 - Shape: `internal/datafiles/mount.go:13` `mounted`: seven small types fake the folders above the mount, balanced by Source keeping one form and truthful per-module packages
 - Self-sufficiency: `data/sv_SE/fs.go:1` `svse`: each module says in code which namespace it supplies and what it reads
+
+## 2026-10-11T13:18:20Z, PR #203 at 3d4131b, against bf1becb
+
+Ruling: worse
+
+| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
+|---|---|---|---|---|---|
+| Mid A | same | better | worse | same | same |
+| Inherited architect | same | worse | worse | same | worse |
+| Maintainability senior | same | worse | same | same | worse |
+| Junior A | same | worse | worse | better | worse |
+
+Mid A, decided by:
+
+- Shape: `internal/datafiles/mount.go:13` `mounted`: a hand-built virtual fs.FS of five types replaces a base string joined in dirPath
+- Locality, Shape: `internal/datafiles/datafiles.go:34` `Source.Mounted`: one field drives file reads, error labels and the manifest read, and a second Mounted call does nothing
+- Locality: `data/sv_SE/fs.go:19` `Modules`: a locale reading its country's places is a Go import with a package comment
+- Locality: `fejkdata.go:99` `New`: every source is named at the call site, where the base loaded shipped data implicitly
+- Shape: `data/modules.go:17` `Modules`: six packages, five near-identical boilerplate
+
+Inherited architect, decided by:
+
+- Locality, Shape, Overall: `internal/datafiles/mount.go:13` `mounted`: a fake fs.FS of five types with made-up folders above the mount, where the base had a base string; where it rots first
+- Locality: `internal/datafiles/datafiles.go:34` `Source.Mounted`: the mount point kept in Source.at and mounted.at, and labelled undoes it through underMount
+- Locality, Self-sufficiency: `index.go:22` `placeIndex`: index keys carry the full namespaced path, which only the mount maps back, stated nowhere at either site
+- Locality: `fejkdata.go:41` `config.given`: every source explicit and errNoData names the fix, a partial offset
+- Navigation: `data/modules.go:14` `go:generate`: the manifest generator lives in a test of the parent package
+
+Maintainability senior, decided by:
+
+- Locality, Overall: `internal/datafiles/mount.go:13` `mounted`: a fake fs.FS inventing the folders above the mount, so tracing why a file opens means following three paths in Open, where the base prefixed one base string
+- Locality: `internal/datafiles/datafiles.go:56` `labelled`: one field serves the manifest read, file opens and error labels, and labelled undoes the mount through code in mount.go
+- Locality: `fejkdata.go:99` `New`: the hidden shipped default is gone, a partial offset
+
+Junior A, decided by:
+
+- Shape, Locality, Overall: `internal/datafiles/mount.go:13` `mounted`: about 130 lines and five types fake folders so a module's root shows up under its namespace, where prefixing Category.Folders looks like the obvious alternative
+- Locality: `internal/datafiles/datafiles.go:34` `Source.Mounted`: at changes both fsys and how errors label files, and a second Mounted call does nothing silently
+- Self-sufficiency: `data/sv_SE/fs.go:1` `svse`: each package doc states its namespace and what it reads, and Modules names exactly what it pulls in
+- Self-sufficiency: `fejkdata.go:79` `errNoData`: the error names the call that loads the shipped data

internal/datafiles/mount.go

@@ -1,46 +1,45 @@
 package datafiles
 
 import (
-	"io"
 	"io/fs"
-	"path"
 	"strings"
-	"time"
 )
 
-// mounted is fsys with its root moved down to the folder at, so a file f of fsys is at/f;
-// the folders above at hold only the next folder towards it.
+// mounted is fsys with its root moved down to the folder at, so a file f of fsys is at/f. It
+// serves what a walk asks of a tree, a folder's entries and a file's bytes: the folders above
+// at list only the next folder towards it, and opening one fails.
 type mounted struct {
 	fsys fs.FS
 	at   string
 }
 
 func (m mounted) Open(name string) (fs.File, error) {
-	inner, ok := m.inner(name)
-	if ok && inner != "." {
+	if inner, below := m.inner(name); below {
 		return m.fsys.Open(inner)
 	}
-	if ok {
-		f, err := m.fsys.Open(".")
-		if err != nil {
-			return nil, err
-		}
-		return mountRoot{File: f, name: path.Base(name)}, nil
-	}
-	if next, ok := m.towards(name); ok {
-		return &mountDir{name: path.Base(name), next: next}, nil
-	}
 	return nil, &fs.PathError{Op: "open", Path: name, Err: fs.ErrNotExist}
 }
 
+func (m mounted) ReadFile(name string) ([]byte, error) {
+	if inner, below := m.inner(name); below {
+		return fs.ReadFile(m.fsys, inner)
+	}
+	return nil, &fs.PathError{Op: "read", Path: name, Err: fs.ErrNotExist}
+}
+
 func (m mounted) ReadDir(name string) ([]fs.DirEntry, error) {
-	if inner, ok := m.inner(name); ok {
+	if inner, below := m.inner(name); below {
 		return fs.ReadDir(m.fsys, inner)
 	}
-	if next, ok := m.towards(name); ok {
-		return []fs.DirEntry{mountEntry(next)}, nil
+	rest, above := strings.CutPrefix(m.at, name+"/")
+	if name == "." {
+		rest, above = m.at, true
 	}
-	return nil, &fs.PathError{Op: "readdir", Path: name, Err: fs.ErrNotExist}
+	if !above {
+		return nil, &fs.PathError{Op: "readdir", Path: name, Err: fs.ErrNotExist}
+	}
+	next, _, _ := strings.Cut(rest, "/")
+	return []fs.DirEntry{folderEntry(next)}, nil
 }
 
 // inner is name as fsys spells it, where name lies at or below at.
@@ -63,78 +62,12 @@ func underMount(at, name string) (string, bool) {
 	return strings.CutPrefix(name, at+"/")
 }
 
-// towards is the folder below name on the way to at, where name lies above at.
-func (m mounted) towards(name string) (string, bool) {
-	rest := m.at
-	if name != "." {
-		var above bool
-		if rest, above = strings.CutPrefix(m.at, name+"/"); !above {
-			return "", false
-		}
-	}
-	next, _, _ := strings.Cut(rest, "/")
-	return next, true
+// folderEntry is a folder above the mount, as a folder's entries list it.
+type folderEntry string
+
+func (e folderEntry) Name() string      { return string(e) }
+func (e folderEntry) IsDir() bool       { return true }
+func (e folderEntry) Type() fs.FileMode { return fs.ModeDir }
+func (e folderEntry) Info() (fs.FileInfo, error) {
+	return nil, &fs.PathError{Op: "stat", Path: string(e), Err: fs.ErrNotExist}
 }
-
-// mountRoot is fsys's root, named as the folder it is mounted at.
-type mountRoot struct {
-	fs.File
-	name string
-}
-
-func (r mountRoot) Stat() (fs.FileInfo, error) {
-	info, err := r.File.Stat()
-	if err != nil {
-		return nil, err
-	}
-	return renamed{FileInfo: info, name: r.name}, nil
-}
-
-func (r mountRoot) ReadDir(n int) ([]fs.DirEntry, error) {
-	if d, ok := r.File.(fs.ReadDirFile); ok {
-		return d.ReadDir(n)
-	}
-	return nil, &fs.PathError{Op: "readdir", Path: r.name, Err: fs.ErrInvalid}
-}
-
-type renamed struct {
-	fs.FileInfo
-	name string
-}
-
-func (r renamed) Name() string { return r.name }
-
-// mountDir is a folder above the mount, holding only the folder next towards it.
-type mountDir struct {
-	name, next string
-	read       bool
-}
-
-func (d *mountDir) Stat() (fs.FileInfo, error) { return mountEntry(d.name), nil }
-func (d *mountDir) Read([]byte) (int, error) {
-	return 0, &fs.PathError{Op: "read", Path: d.name, Err: fs.ErrInvalid}
-}
-func (d *mountDir) Close() error { return nil }
-
-func (d *mountDir) ReadDir(n int) ([]fs.DirEntry, error) {
-	if d.read {
-		if n > 0 {
-			return nil, io.EOF
-		}
-		return nil, nil
-	}
-	d.read = true
-	return []fs.DirEntry{mountEntry(d.next)}, nil
-}
-
-// mountEntry is a folder above the mount, as both its DirEntry and its FileInfo.
-type mountEntry string
-
-func (e mountEntry) Name() string               { return string(e) }
-func (e mountEntry) IsDir() bool                { return true }
-func (e mountEntry) Type() fs.FileMode          { return fs.ModeDir }
-func (e mountEntry) Info() (fs.FileInfo, error) { return e, nil }
-func (e mountEntry) Size() int64                { return 0 }
-func (e mountEntry) Mode() fs.FileMode          { return fs.ModeDir | 0o555 }
-func (e mountEntry) ModTime() time.Time         { return time.Time{} }
-func (e mountEntry) Sys() any                   { return nil }