Document record-structure dictionary counts and the encoding they measure

[kriszyp]

Companion to the core change for HarperFast/harper#2220 — Per-table msgpackr structure dictionaries grow unbounded and unobservably, which adds four fields to describe_table: typed_structures_enabled, typed_structure_count, typed_structure_limit, classic_structure_count.

Documents what a record structure is, why the dictionary only ever grows, what reaching the bound means, and how an application keeps it small — and, in response to review, documents the feature those counts describe. storage.randomAccessFields had shipped in v5.1.0 with no documentation anywhere: not in the configuration option list, not on the @table directive, and nothing explaining what the encoding buys or which tables it suits. The describe_table passage was a reader's first encounter with it. So the PR now adds a Record Encoding section to Storage Tuning covering the layout difference, what each encoding buys, when to enable it and when not to, plus the config option and the @table argument in their reference lists.

For the human reviewer

• The growth model is the part worth checking. A structure is minted per distinct shape = ordered field list × each field's encoded type and width — so {a, b} and {b, a} are different shapes, and so are {v: 1}, {v: 70000}, and {v: "ok"}. This is measured against the installed deps, not inferred: 4 key orders → 4 structures; one two-field shape across 11 value kinds → 5 structures. The issue that prompted this attributed growth to realized field subsets alone, which understates it.
• The classic bound is newly stated and is the claim to check hardest. classic_structure_count stops at 32 because msgpackr's shared named-record list defaults to maxSharedStructures: 32 (msgpackr/pack.js:43). Verified empirically — a Packr with getStructures/saveStructures fed 200 distinct field-name sets saturates the shared list at exactly 32 — and it matches the core PR's live measurement (typed 256/256, classic 32). That is why describe_table reports no classic_structure_limit: there is a bound, it is just not configurable.
• "Safe to toggle at runtime" was wrong and is now stated as restart-scoped. OpenDBIObject reads storage.randomAccessFields when the primary DBI is constructed, so an already-open table keeps the encoding it opened with. An operator who runs set_configuration and immediately polls describe_table would otherwise conclude the feature is broken.
• typed_structures_enabled needs the surrounding sentence. storage.randomAccessFields defaults off, so most tables show typed_structure_count: 0 against a limit of 256. Without the explanation an operator reads that as spare headroom rather than the feature being disabled, so the paragraph saying so is load-bearing.
• The warning's scope is stated honestly rather than simply. It fires per encoder from the post-save path, so several workers can each warn for one table and a worker that never saves after loading a full dictionary stays silent. The text says the counts are the reliable signal and the log is the heads-up, rather than implying one warning per table.
• The bound is now referred to by its reported field (typed_structure_count against typed_structure_limit, 256 by default) rather than as a literal "256 per encoder", which read as conflicting with describe_table presenting one count per table.
• Not done, deliberately: storage.randomAccessFields and the @table(randomAccessFields:) directive are v5.1.0 surface with no entry in release-notes/v5-lincoln/5.1.md. Backfilling a shipped release-notes file felt like a separate call rather than something to fold in here.
• No analytics metric is documented, deliberately. The core change originally folded these counts onto the table-size metric; that metric turns out to have no RocksDB emitter at all (The table-size analytics metric is never emitted on RocksDB harper#2249), so documenting it here would point operators at a series that never appears.

Verification

• npm run format:check clean; npm run build succeeds with no new broken links or anchors (the two it reports — /reference/v5/backups/overview and /release-notes/v5-lincoln/5.1 — are pre-existing and on untouched pages).
• The classic-dictionary bound of 32 confirmed by running a Packr with shared structures over 200 distinct field-name sets against Harper's installed msgpackr.
• Claims cross-checked against the core diff (Make per-table record-structure dictionary size observable harper#2250) and against live measurements from the core PR's integration suite (a saturated table reports typed 256/256, classic 32).

Refs HarperFast/harper#2220

_{Review-Coverage: authored=codex; ran=gemini,claude; declined=cursor-grok,cursor-composer,domain; rounds=4 @ cecf65b}

_{Human-Review-Need: 2 @ cecf65b}

[gemini-code-assist]

Code Review

This pull request updates the 'describe_table' API documentation to detail the new record-structure dictionary fields in the response. The reviewer suggested adding a version badge to indicate this behavior change, as per the repository's documentation guidelines.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-633

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-633

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-633

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-633

This preview will update automatically when you push new commits.

[github-actions]

🧹 Preview Cleanup

The preview deployment for this PR has been removed.