Spec

Writing spec

The spec (docs/website/src/spec/) describes observable behavior — what a contract or validator can detect. How this codebase achieves it goes to impl-spec/. If a sentence starts describing internals (caches, native limits, threads), either drop it or reduce it to one normative requirement on implementations.

Be brief

• One concern per section; a few paragraphs or one list is the right size.
• Enumerate cases with #. lists instead of prose walkthroughs; name the actors precisely (caller/callee, leader/validator) and describe each case once.
• State what happens, not why the design is good. Rationale goes to ADRs (docs/adr/).
• Cover the edges (unwinding, host boundary, validation-time rejection) in one sentence each — omitting them is sweeping under the rug, but they rarely deserve a paragraph.

Link, don't inline

Never write a literal value or error string in spec text — link the anchor, so generated pages stay the single source of truth:

• Constants: :ref:gvm-def-consts-value-- / `:ref:`gvm-def-const-<name> from spec/appendix/constants.rst (generated from executor/codegen/data/public-abi.json), internal-constants.rst (from internal-constants.json) or constants-pending.rst (from public-abi-pending.json). Never edit these .rst by hand — edit the JSON and regenerate (genvm-tool.md). Constants a contract cannot read go to the internal JSON, not-yet-stabilized ones to the pending JSON.
• Error outcomes: :ref:gvm-def-str-trie-value-vm-error-...`` — every "traps with" / "rejected with" must link the exact vm_error entry.
• Glossary terms: :term:sub-VM`` etc. on first use in a section.
• Other spec pages: :doc: relative links instead of restating their content.

Verify

Build the website (docs.md) and check for undefined label warnings on your pages — a broken :ref: is a silent dead link otherwise. Verify claims against the implementation before writing them; every behavioral sentence should have a code location you can point to (but do not link it to the specification).