# Versioning

> How Tórculo is numbered, how each part writes its version inside its files, what each kind of version may change, and how the conformance suite and the libraries are versioned on t

URL: https://torculo.joseluissaorin.com/en/governance/versioning · Reviewed: 2026-10-15 · Español: https://torculo.joseluissaorin.com/gobernanza/versioning.md

How Tórculo is numbered, how each part writes its version inside its files, what each
kind of version may change, and how the conformance suite and the libraries are versioned
on their own. The normative rules are in [SPEC §22](../spec/SPEC.md#versioning); this
document repeats them and adds the policy around them. The key words MUST, SHOULD and MAY
are to be read as described in BCP 14 (RFC 2119 and RFC 8174) when, and only when, they
appear in capitals.

## The specification

The specification is numbered **MAJOR.MINOR**, with editorial releases as a third number.

| Kind | Example | May change | Needs |
|---|---|---|---|
| Major | 1.0 → 2.0 | anything, including breaking changes, with the legacy rules below | RFCs |
| Minor | 1.0 → 1.1 | only additions that conforming products of 1.0 can ignore, and new epochs of the language | RFCs |
| Editorial | 1.0.0 → 1.0.1 | wording, examples, translations, corrections that change no behaviour | no RFC |

Releases are tagged `spec-vMAJOR.MINOR.PATCH` (the first is `spec-v1.0.0`), separately
from the libraries. Each published text states its maturity: **working draft** (stable
enough to implement, open to change by RFC; Tórculo 1.0 has been one since 2026-10-15) or
**final** (every RFC it contains is implemented by two independent implementations and the
suite covers every testable MUST).

## The version inside each file

| Part | Where the version is written | Tórculo 1.0 |
|---|---|---|
| Pliego language | `MESA v<epoch>` in the preamble (optional) | epoch 2 |
| Portable project | `MANIFIESTO.json` → `formato` | `mesapack 1` |
| Pieces | the card's `nivel` and the contract version | 1 |
| Canon | `canon.toml` → `version`, copied to every generated file | 1 |
| Láminas | signature `LAMINA\0\x01` and `manifiesto.json` → `version` | 1 |
| Materias | the convention (group 0 and `Plano`, 96 bytes) | 1 |
| Takes | START → version | `0x8000_0002` (reads `0x8000_0001`) |

## The language: epochs

- **The constitution: a pliego that compiled once compiles always.** A compiler that
  claims an epoch compiles every pliego of that epoch and of the earlier ones it claims.
- An epoch's vocabulary is **frozen**, reserved words included. A new epoch may add words,
  lines and profiles; it may not change the meaning of a valid pliego of an earlier epoch.
- A word can only be retired by a new epoch that declares it legacy; pliegos that declare
  the older epoch keep it.
- Epoch 1 (`SPEC-MESA.md` of manim-saorín) is legacy: compilers SHOULD read it.

## The other parts

- `mesapack`: a new major is a new format; a minor (`mesapack 1.1`) only adds members.
- Láminas: a new layout is version 2, with its own signature byte.
- Takes: the fork's range starts at `0x8000_0000`; every layout or opcode change takes the
  next version, and readers keep reading the versions this standard lists.
- Canon: any change of value bumps `version`; additions of keys too.
- Materias: the convention changes only with a major version of the specification.

## Deprecation

A feature is deprecated by RFC, marked as such in the specification with the version that
deprecated it, and removed no earlier than the next major version and at least 24 months
later. Reserved words never expire within their epoch.

## The conformance suite

The suite (`conformance/manifest.json`) is versioned on its own, `MAJOR.MINOR.PATCH`:
a patch fixes a wrong case, a minor adds cases, a major follows a major of the
specification. Every report names the suite version and its `cases_sha256`. **Pending**
cases (known deviations of the reference implementation, SPEC Appendix D) are reported
apart and do not count as passed or failed.

## Implementations and packages

Libraries and tools have their own semantic versions, starting at `0.x` until Tórculo 1.0
is final and the parts they implement have two independent implementations. The reference
implementation of the language reports its epoch (`MESA v2 beta`) and its version
(`1.0.0b1`).