Documentation · Releases · Perseus

Perseus — H.1.6

v.Chronos.1.Perseus — legacy v.H.1.6

One canonical coordinate-addressed forest. One grammar. Every surface a pure derivation — and this change versions itself under its own scheme.

Perseus is the comprehensive versioning rehaul. Before it the project presented its versions through four independent surfaces that each read a different model, three rosters that drifted out of agreement, a version axis that could regress, a codename listed twice, and a build stamp whose active version and phase code came from unrelated nodes. Perseus replaces all of that with exactly one canonical source of truth: an ordered, coordinate-addressed per-Release forest. Every identity is a coordinate in the four-designator grammar v.<Release>.<Era>.<Name>-<fix> — the Release is a major deity whose leading letter IS its ordinal (A=1, B=2, … Z=last), the Era is an integer within a Release, the Name is a minor figure within an Era, and the optional fix is a lowercase patch letter. The full coordinate is the authoritative key; the compact three-letter short code is a deterministic derivation for badge real estate only and can never drift from or collide with the coordinate it represents. Touching already-shipped work does not open a new head node — it mints a retroactive fix under that Name at its historical coordinate (the next-unused fix letter, max existing plus one), so a patch stays attached to the work it patched. Every major-tier deity that occupies a Release slot is permanently reserved: a reserved name may never appear at the Name layer and no codename bound to a shipped coordinate is ever reused, so the 'same name listed twice' class of defect becomes structurally impossible rather than something to watch for. The four previously-divergent surfaces — the about/versioning grammar page, the releases index, the roadmap, and the public + admin changelog — are re-derived so they all read the same model and can no longer disagree; the legacy roster files lose their independent roster role and become pure derivations too, with the extractor-managed sentinel region reconciled. A new unified canonical page renders the entire Release→Era→Name→fix forest in one place with the grammar, the retroactive-fix rule, and the uniqueness invariant documented inline, so the scheme is self-describing to any visitor. Exported symbol names and type shapes are preserved, so existing consumers compile unchanged and the rehaul stays phase-isolatable. Finally the change dogfoods itself: it is minted as a new Release/Era/Name node through the canonical model — the Perseus node this page describes — with the build stamp bumped via the model rather than hand-edited, so the rehaul ships under its own scheme.

Why “Perseus”

Perseus is the hero who could not safely look at Medusa directly — any direct glance turned the looker to stone — so he acted through a single reflected, authoritative view and struck true. The codename captures the shape of this release relative to the state before it: the project had been looking at its own version identity through four direct, contradictory glances — four surfaces each reading a different model, three rosters that had drifted apart, a version axis that could regress, a codename that appeared twice, and a build stamp whose two halves read unrelated nodes. Perseus introduces the one reflected view that is safe to act on: a single canonical, coordinate-addressed forest under the four-designator grammar, with every surface rendered as a pure derivation of that one model so no two surfaces can ever describe the same milestone two different ways again. And, like Perseus carrying back the head as proof of the deed, this change carries itself: the rehaul is minted as a node in the very forest it created, so the scheme is dogfooded rather than merely asserted.

Headline changes

  • One canonical, coordinate-addressed forest replaces four independent models. There is now exactly one source of truth for the entire version model: an ordered set of coordinate records arranged as a per-Release forest(Release → Era → Name → fix). The previously independent surfaces no longer each read their own roster — they all read this one forest, so the “same milestone described two different ways” and “Iris listed twice” classes of defect are eliminated at the model, not patched per surface.
  • The four-designator grammar v.<Release>.<Era>.<Name>-<fix> is the canonical key. Every release identity is a single coordinate: the Release is a major deity whose leading letter isits ordinal (A = 1, B = 2, … Z = the final release, no skipped letters), the Era is an integer within a Release, the Name is a minor figure within an Era, and the optional fix is a lowercase patch letter. The full coordinate is the only key; the compact three-letter short code is a deterministic derivation for badge real estate that can never drift from or collide with the coordinate it represents.
  • Touching shipped work mints a retroactive fix at its historical coordinate. A retroactive patch to already-shipped work no longer opens a new head node — it mints the next-unused fix letter (the maximum existing fix plus one) under that Name at its historical coordinate, so a fix stays attached to the work it patched rather than masquerading as a brand-new head of the current Release. A genuinely-distinct new sub-effort still draws a new Name from the unused pool, never a fix letter.
  • Codename uniqueness & Release reservation is now a model invariant. Every major-tier deity that occupies a Release slot is permanently reserved: a reserved Release-tier name may never appear at the Name layer, and no codename bound to a shipped coordinate is ever reused. A historical Name that collides with a reserved slot is re-drawn from the unused pool deterministically — never silently kept, never used twice. Uniqueness is an invariant of the model, not a per-page convention someone has to remember to enforce.
  • Four surfaces re-derived, joined by one unified canonical page. The about/versioning grammar page, the releases index, the roadmap, and the public + admin changelog are all re-derived from the one model so they can no longer disagree (this also fixes the lexicographic-sort defect, links the previously unlinked H-arc pages, and resolves the multi-dns slug mismatch). The legacy roster files lose their independent roster role and become pure derivations too, with the extractor-managed sentinel region reconciled. A new unified canonical page renders the entire Release→Era→Name→fix forest in one place with the grammar, the retroactive-fix rule, and the uniqueness invariant documented inline.
  • The rehaul dogfoods its own scheme — it ships as the node it minted. This change is itself versioned as a new Release/Era/Name node minted throughthe canonical model — the Perseus node at the new coordinate this page describes — and the build stamp’s active version and phase code derive from that same active node rather than from a hand-edited literal, so the historical anomaly where the active version read one Era and the phase code read another cannot recur. The version stamp on this page is read live from the model, not frozen into the page.

For operators

Every version reference you see — the footer, the admin chrome, the docs, the changelog, the release pages — now agrees on one identity per release, because they all read the same canonical forest. You will never again see the same milestone described two different ways, and a codename means exactly one thing forever. The changelog’s flat newest-first sprawl is regrouped into per-Release collapsible logs — every historical entry is preserved, only relabeled and regrouped under its Release.

Old v0.7.x strings in commit prose, issues, and notes stay resolvable to their new coordinate, so historical references never become dead ends. To follow the scheme end to end, start at the unified canonical page (the whole forest in one view) and read the grammar explainer for the four designators, the retroactive-fix rule, and why a Release codename is never reused.

Related

  • The canonical release forest — the new unified page this change shipped: the entire Release→Era→Name→fix forest rendered in one place, with the four-designator grammar, the retroactive-fix rule, and the codename-uniqueness invariant documented inline.
  • Versioning — the grammar explainer, re-derived from the same canonical model: the four designators, the A–Z deity Release roster, the retroactive-fix model, and the codename-uniqueness / Release-reservation invariant.
  • Nemesis — H.1.5 — the immediately preceding arc; Perseus opens nameSeq 7 of the Chronos Era 1 on top of Nemesis v.H.1.5, carrying its economic gate forward while rebuilding how every version surface is addressed and derived.