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 | Spec document | Implementation | Status | Reader constant |
|---|---|---|---|---|
.ax language | 1.1 | 1.1 | stable | boruna_compiler::LANGUAGE_VERSION |
| Bytecode format | 1.0 | 1.1 | stable | boruna_bytecode::BYTECODE_VERSION |
| Evidence bundle format | 1.0 | 1.1 | stable | boruna_orchestrator::BUNDLE_FORMAT_VERSION |
| Workflow DAG schema | 1.0 | 1 | stable | boruna_orchestrator::WORKFLOW_DAG_SCHEMA_VERSION |
The bytecode and evidence-bundle implementations are at 1.1 (additive changes; 1.0 documents still read) but their spec documents have not yet been updated for the 1.1 additions. See the CHANGELOG for what 1.1 added. These format versions are independent of the Boruna release version (currently 3.x).
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