Skip to content

Specification

Jump to bottom
Test User edited this page Jun 5, 2026 · 3 revisions

Specifications

Requirements-level documents: what astrodyn must do and why — independent of how any particular design does it.

astrodyn is young, and its designs iterate (see Frame-Tree-ECS-Native for a subsystem redesigned in flight across a dozen PRs). Design documents age with the design; the fundamental needs should not. These pages record the drivers and their rationale so that each redesign is measured against the same yardstick rather than against the previous design.

What belongs here

  • Enumerated shall-requirements, each with a stated rationale (the driver, ideally anchored to a concrete incident, JEOD behavior, or prior-art lesson), an implementation-neutral verification approach, and trace links.
  • Statements of need, not mechanism. A spec page deliberately stops short of prescribing data structures, encodings, APIs, or crate layout — those belong in design pages, issues, and source docs, and are expected to churn.

What does not belong here

  • Design contracts for planned components (precedent: Variable-Server is a design-only spec for a future implementation — a different document kind).
  • Port-fidelity invariants (docs/JEOD_invariants.md stays in-repo, consistency-checked against // JEOD_INV source tags).
  • Audit findings and gap lists (Audit-2026-05, Audit-Findings).

Conventions

  • Requirement IDs are <SYS>-NNN where the leading digit groups by theme (e.g. RFS-3xx = failure behavior). IDs are never reused or renumbered; a superseded requirement is marked superseded in place, with rationale and a pointer to its replacement, so old citations stay resolvable.
  • Each requirement carries: the shall-statement, Rationale, Verification (kept implementation-neutral), and Trace (issues, JEOD_INV rows, incidents, prior art).
  • Changing a requirement is a project decision, not an edit: argue it in a GitHub issue first and reference it in the wiki commit message. Spec pages carry no change-log section — the wiki commit history is the changelog.
  • The above binds once a spec is Accepted. While a spec is in Draft (initial review), it is edited freely and IDs may still change.

Index

Spec System Status
Spec-Reference-Frame-Requirements Reference frame system (typed facade + runtime layer + exchange) Draft — under review

Clone this wiki locally