Embedded user-docs size budget

Where this stands

User docs (docs/user/**/*.md) ship inside the lattice binary, generated by crates/lattice-help/build.rs and embedded zstd-compressed against one shared dictionary, trained at build time from the docs themselves. :help works offline with no filesystem layout assumption beyond the binary itself — the property that made embedding worth it — without the binary paying raw markdown volume.

Bodies decode on first open and cache in a OnceLock, so a session that never opens :help never decompresses anything. Each topic is its own zstd frame; the dictionary is the only thing topics share, and it is prepared once per process on the first :help.

As of 2026-11-05: 178 topics, 952 KB raw → 316 KB embedded (283 KB of bodies + the 32 KiB dictionary; 3.0×). Budget is 384 KiB compressed, leaving ~77 KB.

History

The docs were embedded uncompressed (include_str!) until the doc set grew to 498 KB raw against a 512 KB budget — 14 KB of headroom, with 33 more mode pages queued. That triggered this document's own rule ("do not just bump the number") and the compressed-embed work landed.

The prediction here was ~5× compression. Measured: 2.5×. Each doc was deflated independently, and on a few KB per file the window barely warms up. This section then claimed a shared dictionary "would mean inflating everything to read one topic". That was wrong: it is true of compressing the corpus as one stream, not of a preset dictionary, where every topic stays an independent frame and only the dictionary is shared.

2026-11-04: the budget filled. 178 topics, 952 KB raw → 393,215 B of 393,216 — one byte of headroom, and a single new table row in ex-commands.md failed the test. Raw docs had grown ~140 KB/month since July.

2026-11-05: shared dictionary. Measured on the exact embedded bodies before choosing (sizes include the dictionary's own bytes):

SchemeEmbeddedRatio
deflate-9 per topic (the scheme being replaced)393.2 KB2.42×
zstd-19 per topic, no dictionary388.4 KB2.45×
deflate-9 + 32 KiB preset dictionary334.0 KB2.85×
zstd-19 + 32 KiB trained dictionary313.7 KB (Python est.), 316.1 KB shipped3.01×
zstd-19 + 64 KiB / 128 KiB dictionary323.4 / 357.3 KBworse — past 32 KiB the dictionary grows faster than the bodies shrink

Zstd on its own buys nothing (2.45× vs 2.42×); the win is entirely the dictionary. The shipped figure trails the estimate by 2.4 KB because the Python estimate and the Rust build script run different training parameters over the same libzstd.

Two properties were checked before committing to it, because either failing would have made the scheme worse than it looks:

  • Docs written after training still compress well. Trained on a random 80% of topics, the dictionary compressed the unseen 20% at 3.34× (deflate: 2.41×). The build retrains every time docs change anyway, but this is what says a dictionary is not overfit to the set it was trained on.
  • Training is deterministic — identical bytes across runs, in both the Python estimate and the Rust build script — so builds stay reproducible. It costs ~0.5 s, on a lattice-help rebuild only.

Binary cost of the decoder: zero. wasmtime's cache already links zstd 0.13 with default features off; lattice-help depends on it the same way, and only its build script turns on zdict_builder, which resolver 2 keeps out of the runtime build. miniz_oxide stays in the binary through flate2, so dropping the direct edge saves nothing either; the net change is the docs bytes alone, −77 KB.

What it does not do: end the budget question. 77 KB at ~3.3× is ~250 KB more raw markdown, or roughly two months at the July–November growth rate. The levers below still apply when it fires again.

The budget

384 KB of compressed bytes, asserted by embedded_user_docs_stay_under_size_budget.

It measures the embedded size now, not the raw markdown. Raw size stopped being the cost the moment compression landed; measuring it would fire the alarm on volume the binary never pays for.

The total counts the dictionary's bytes as well as the bodies'; it is in the binary too, and a budget that summed only bodies could be met by growing the dictionary.

Further tests guard the scheme itself: embedded_bodies_are_actually_compressed (a regression that embedded bodies raw would otherwise slip under the budget while the binary grew), every_embedded_topic_decompresses_to_its_original_length, the_shared_dictionary_is_embedded_and_within_its_cap (training that silently fell back to no dictionary, or a cap raised without re-measuring), and topics_need_the_shared_dictionary_to_decode (the dictionary riding along without being referenced).

Cost, measured

crates/lattice-help/benches/topics.rs (Apple Silicon; the rest of benchmarks.md is measured on the Ryzen box — not comparable):

BenchMedianWhat it is
help_registry_boot_ns~17.8 µsbuiltin_topics() at editor boot. Decompresses nothing — if this grows with the doc set, laziness has been lost.
help_topic_first_open_ns~66.6 µsInflate + cache fill for the largest topic (modal-editing). The one-time cost per topic per session.
help_topic_cached_open_ns~562 nsEvery subsequent open — a clone of the cached string.

All three sit on the dispatch path of an explicit user action, never per-keystroke or per-frame, so the bar is "imperceptible within a command" rather than the frame budget.

Deflate vs. shared-dictionary zstd, 2026-11-05 — decode only, on the bytes that actually ship, release build, Ryzen / WSL2 (a scratch harness against the same zstd / miniz_oxide versions the binary links; not the criterion bench, so not comparable to the table above):

TopicRawdeflatezstd + dictionary
largest (magit-transient)50.9 KB38.6 µs29.2 µs
p90 (languages)13.6 KB12.7 µs8.8 µs
median (toml-mode)2.5 KB4.6 µs1.1 µs
smallest0.6 KB2.3 µs1.2 µs
prepare the dictionary, once per process——3.2 µs

Faster at every size, so the change is a pure size win: nothing a user does got slower, and the worst first open is ~30 µs against an 8–16 ms frame. The bench now carries help_dictionary_prepare_ns and help_topic_first_open_median_ns, and picks its topics by size at run time — the pinned modal-editing had quietly stopped being the largest.

What to do when the budget fires again

Do not bump the number. Compression is now spent twice over — per-topic first, then the shared dictionary (2026-11-05), whose sizing above shows no further cheap gain: a bigger dictionary loses. The next lever is moving docs out of the binary into a runtime directory.

For scale when weighing it: the whole embedded doc set is ~0.4% of a release binary (316 KB of ~88 MB), so the budget is a discipline line rather than a binary-size emergency, and raising it is a real option for the owner to take — it is just not one to take silently, in a slice that happened to trip it.

That lever used to carry a second justification — it was also read as the only model that lets plugins ship :help pages. That is no longer true, and the plugin half has been decided the other way (2026-08-22): a plugin's markdown is include_str!'d into its own .wasm and registered through a help WIT seam against a runtime-writable registry handle. Docs travel with the artefact that owns them, and a plugin's pages never enter this budget at all. See ../architecture/contributable-registries.md §4.

So what follows is now a builtin-volume lever only, and it is the weaker for having lost its other reason. If the budget fires, weigh it against simply writing less, or writing more densely, first.

The runtime-directory model

Every editor in this class does the same thing, and the convention is worth following rather than reinventing:

EditorLocationPlugin docs
Vim / Neovim$VIMRUNTIME/doc/ + generated tagsevery plugin ships doc/ on runtimepath; :helptags indexes it
Helixruntime/, found via repo-sibling → user config → $HELIX_RUNTIME → compile-time HELIX_DEFAULT_RUNTIME → exe-relative—
Kakoune../share/kak/doc/*.asciidoc, exe-relative:doc also searches the autoload dir
Zed, VS Codea websiten/a — no offline manual

Zed's answer is out for lattice: the TUI is a first-class peer for headless / SSH, so :help has to work with no browser.

Proposed shape when this lands (decided 2026-07-29, deferred):

resolution order
  1. $LATTICE_RUNTIME/doc
  2. ~/.config/lattice/runtime/doc
  3. LATTICE_DEFAULT_RUNTIME/doc     (compile-time, for packagers)
  4. <exe>/../share/lattice/doc
  5. the embedded set                (always present — the floor)

user      ~/.config/lattice/doc/*.md

The plugins <plugin>/doc/*.md, overlaid at load line this block used to carry is struck — plugin docs ship inside the component now (§ above).

Scoped docs-only but named for growth: build runtime/doc/ and the resolution chain, wire only docs through it, and leave the path shape free for runtime/themes/ and runtime/queries/ later without a second migration.

Keeping the embedded set as the floor matters because of how lattice is installed: cargo install and a scp'd static binary both produce a binary with no runtime directory anywhere, and those are first-class paths for a Rust TUI editor. Helix lives with the equivalent gap, but there a missing runtime also kills syntax highlighting — loud, and self-correcting. A missing docs directory is quiet, and it fails the user least equipped to diagnose it.

Rejected: remote fetch

Embed names + summaries, serve bodies from a URL. Breaks the offline-works property unconditionally.

Anchors

  • Build script: crates/lattice-help/build.rs
  • Registry + tests: crates/lattice-help/src/topics.rs
  • Bench: crates/lattice-help/benches/topics.rs
  • Slice plan: slice-plans/archive/help-docs.md