Runtime specs
Spec pages describe the current runtime contract — what the Holon runtime actually does today, verified against implementation and tests.
Specs are not tutorials or user guides. They are authoritative contracts for contributors, maintainers, and integrators who need to understand or change how the runtime behaves.
How specs fit into the documentation model
| Layer | What | Audience |
|---|---|---|
| Guides | Task-oriented workflows | Users |
| Concepts | Mental model | Users, evaluators |
| Reference | CLI, config, control-plane snapshots | Users, integrators |
| Specs (here) | Current runtime contracts | Maintainers, contributors |
| RFCs | Design records and rationale | Maintainers |
Specs bridge the gap between user-facing docs and RFC design history. When an RFC stabilizes into runtime behavior, the current contract is extracted here. The RFC remains the design record; the spec is the living contract.
Reading a spec
Each spec page follows a consistent shape:
- Contract — the normative behavior the runtime implements.
- Validation — how the contract was checked against implementation, tests, and RFCs.
- RFCs — linked source design records.
- Known gaps — tracked follow-up issues for unresolved drift.
Current spec pages
Relationship to docs/runtime-spec.md
docs/runtime-spec.md
is now an aggregate index that maps the original v0 monolithic spec to the
current focused spec pages. It no longer contains normative content.
Focused spec pages here are the sole authoritative implementation-facing contracts. When a topic has a dedicated spec page, that page is the current authority.
For contributors
When you change runtime behavior, update the relevant spec page alongside the RFC. Spec pages are verified against implementation — if the implementation and spec disagree, fix the one that is wrong and open an issue for the other.