docs(nook): record measured tree-sitter subset size finding

Author: truffle-dev

docs/nook/design/02-tree-sitter-highlighting.md

@@ -95,15 +95,59 @@ primary highlighter with chroma as the fallback for unwired languages.
 Nothing here changes the render path until the size question is settled,
 so the first-paint rule and the binary-size north star both hold.
 
-## Open questions for the build hour
-
-- Does subset-embedding one grammar actually avoid the 542 init
-  registrations, or is the registry all-or-nothing? (Determines slice 1
-  vs. runtime-blob-loading vs. WASM.)
-- Is upstream willing to expose per-grammar subpackages / DCE-friendly
-  registration? A lean single-language import would make this trivial and
-  is worth an issue against odvcencio/gotreesitter once the spike pins the
-  exact constraint.
+## Measured: the subset path holds (2026-07-04, v0.20.9)
+
+The size-gate spike ran. A standalone `CGO_ENABLED=0` module that imports
+`grammars`, resolves Go via `DetectLanguage("main.go")`, loads the grammar
+through `entry.Language()`, and highlights a Go snippet with
+`ts.NewHighlighter(lang, entry.HighlightQuery)`:
+
+| build | tags | size |
+| --- | --- | --- |
+| bare Go binary | (none, no ts import) | 2.29 MB |
+| subset, Go only | `grammar_subset grammar_subset_go` | **9.10 MB** |
+| subset, Go + Python | `grammar_subset grammar_subset_go grammar_subset_python` | 9.18 MB |
+| umbrella (all 206) | (none) | 30.83 MB |
+
+All four highlight the same snippet to the same 14 spans (comment 1,
+keyword 4, property 1, string 2, type 2, variable 4). Findings:
+
+- **Subset-embedding does escape the 542 inits.** Under `grammar_subset`,
+  `registry_builtin_gen.go` is tag-excluded and `registry_builtin_subset.go`
+  makes `registerBuiltinLanguages()` a no-op; only the wired
+  `z_subset_registry_register_<lang>.go` init runs. 9.10 MB vs 30.83 MB is
+  a 70% / 21.7 MB cut. The naive umbrella import is off the table; the
+  build-tag subset is the path.
+- **The runtime is the fixed cost; grammars are nearly free.** Go-only over
+  bare is ~6.8 MB (the pure-Go parser/query engine). A second grammar
+  (Python) adds ~0.08 MB. Per-language cost is the ~hundreds-of-KB the
+  design predicted, so wiring more languages later is cheap; the one-time
+  ~6.8 MB runtime is the number that has to clear the north star.
+- **No runtime blob dir, no WASM fallback needed.** `grammar_subset` embeds
+  the chosen blobs into the binary, so there is no
+  `GOTREESITTER_GRAMMAR_BLOB_DIR` to ship beside `nook` and no wazero
+  dependency to pay for. Slice-1 succeeds; slices 2 (disk blobs) and the
+  WASM family stay unused.
+
+Net for nook: adding tree-sitter-go pushes the binary from ~15 MB toward
+~21-22 MB before any chroma weight is reclaimed. Whether that ~6.8 MB
+one-time add clears "lightest, fastest terminal IDE" is the real go/no-go,
+and it is now a decision on measured numbers rather than an unknown. The
+next slice measures nook-with-`tshl` minus nook-with-chroma to get the true
+net add, then wires `tshl` behind the capture-name -> style-class contract.
+
+Repro: `/tmp/tshl-spike` (throwaway module, gotreesitter v0.20.9); nook's
+own build is untouched.
+
+## Open questions (updated)
+
+- ~~Does subset-embedding one grammar avoid the 542 init registrations?~~
+  **Resolved: yes** (9.10 MB vs 30.83 MB, above).
+- ~~Is upstream willing to expose DCE-friendly per-grammar registration?~~
+  **Moot: already shipped.** The `grammar_subset` + `grammar_subset_<lang>`
+  build-tag matrix (upstream issue #88) is exactly that mechanism, with
+  committed `z_subset_*` files per language. No upstream issue is needed.
 - Highlight query dialect: gotreesitter ships `.scm` queries per language;
   confirm they match nook's expected capture vocabulary or add a small
-  capture-name remap in `tshl`.
+  capture-name remap in `tshl`. (Still open; the Go captures above map
+  cleanly onto nook's existing highlight classes, so the remap looks small.)