Boruna Versioned Specifications
This directory holds formal, versioned specifications for the surfaces Boruna commits to keeping stable.
Each spec carries a language_version / format_version / schema_version field in its front matter or top-level shape. Implementations against a 1.x spec MUST keep working against any later 1.y (y >= x).
Current specs
| Surface | Latest | Status | Sprint | Reader constant |
|---|---|---|---|---|
.ax language | 1.0 | stable | W1-B | boruna_compiler::LANGUAGE_VERSION |
| Bytecode format | 1.0 | stable | W9-A | boruna_bytecode::BYTECODE_VERSION |
| Evidence bundle format | 1.0 | stable | W1-C | boruna_orchestrator::BUNDLE_FORMAT_VERSION |
| Workflow DAG schema | 1.0 | stable | W4 | boruna_orchestrator::WORKFLOW_DAG_SCHEMA_VERSION |
The narrative companion to the bytecode spec lives at docs/bytecode-spec.md; the formal spec at bytecode-1.0.md wins on any disagreement.
Authoring rules
- Specs are prescriptive, not descriptive. They are the authority. Reference docs (under
docs/reference/) and concept docs (underdocs/concepts/) are interpretive. - Each spec MUST declare its version, status, and last-revised date in YAML front matter.
- Each spec MUST include a backwards-compatibility commitment for its current major line.
- Once a spec at version
M.Nis shipped in a release tag, it is frozen. Corrections that change behavior require bumping toM.(N+1)(additive) or(M+1).0(breaking). - Frozen specs MAY be edited only for clarifications that do not change observable conformance — typo fixes, wording, examples.
Versioning policy
MAJOR.MINOR decimal:
- Major bump (1.0 → 2.0) — breaking change. A
1.xprogram may stop working. - Minor bump (1.0 → 1.1) — additive only. Every
1.0program still works.
There is no patch version on specs; clarifying edits keep the same minor.
Reader contract
- Hard reject across a major. A reader built for
N.xMUST refuseN+1.0documents with a typedUnsupported*Versionerror rather than guess. - Forward-compat within a major. A reader built for
N.xMUST acceptN.ydocuments (y >= x) and silently ignore unknown additive fields. - Replay invariant. Versions feed into the canonical-JSON serialization that produces
workflow_hash/bundle hashes, binding evidence to a specific schema generation.
Cross-links
- Stability tiers across the codebase:
../stability.md - Roadmap (which specs are planned):
../roadmap.md - User-friendly references (not specs):
../reference/ - Migration tooling for upgrades across major versions:
../guides/migration.md