Platform Versioning (SemVer)

Policy platform-semver-versioning. Continuous platform builds are versioned as plain SemVer <major>.<minor>.<run>. The patch is the monotonic CD run number. The minor changes only when someone bumps it on purpose, and the major changes only on a declared break. Main builds carry no pre-release label. Images also carry the floating tags <major>-latest and <major>.<minor>-latest, which the arm step moves forward and never backward. A deployment record follows a version pattern resolved against the registry. It never names a floating tag.

1. The scheme

Why the patch is the run number. The rule "higher number ⇒ newer code" is what every self-updater, retention plan and floor check depends on (Self-Update Target Selection). The run number is the one counter the pipeline never gets wrong. If the patch is that counter, the old notation and the new one share one lineage. The last 3.0.0-ci.<n> and the first 3.1.<n+1> are then ordered by when they were published, and nothing can roll backwards across the cut-over. SemVer gives the same order, because a minor bump is deliberate and always later than the builds before it.

The boundary is a declared constant, never inferred. A plain X.Y.Z is read as a build of the new notation only when its line is at or above PlatformReleaseOrder.SemVerEraStart (3.1) and its patch is non-zero. That keeps every tag the old notation published meaning exactly what it meant. A clean 3.0.0 stays a promotion. The withdrawn slip 3.1.0-ci.7841 is still ranked by its ci number, so it can never outrank the new notation. Floors like 3.1.0 or 4.0.0 are still compared by their numeric core, so a floor that says "needs the 3.1 line" holds a 3.0.0-ci.* portal and is met by every 3.1.<run>.

Stable does not start following main. A new-notation build carries no pre-release label, so to NuGet it is as "clean" as a release. VersionSelect.PickTargets therefore keeps any tag with a run number out of Stable, so Stable keeps following exactly what it follows today: deliberately cut releases (3.0.0, 3.1.0, …), which release.yml promotes. See decision 1 in §6.

2. What 3-latest means for consumers

• It is a starting point, never a record value. CD moves 3-latest and 3.<minor>-latest at every arm (main-cd.yml phase D, and control-first for memex-control), and only forward: a newer armed set holds them. A fresh install or a Helm overlay's seed image may name 3-latest, so it boots on the newest armed build.
• A record follows a PATTERN, not a tag. updatePattern: "3.*" admits every build of major 3 in both notations. The self-updater lists the registry, drops pointers (VersionSelect.MovingPointer), per-RID images and git-sha tags, and ranks what remains by run number. A floating tag is never written into a Hosting/Deployment record, because records are never pinned to a tag. A pointer is mutable, so a record that named one would describe whatever the pointer happens to hold, not a decision.
• 3.0.0-latest keeps moving only while the old notation is minted. The new notation moves no three-part pointer, because 3.1.10050-latest would point at exactly one build. Consumers that seed from 3.0.0-latest (the Memex overlays, resolve-line-pointer.sh, preflight-provision.py) switch to 3-latest before the minter flips. After the flip 3.0.0-latest is frozen on the last old-notation set.

3. Inventory: every place the old notation is produced or parsed

Line numbers are as of this change. P = produces the notation, R = parses it. "Handled" means this change teaches the place both notations. "Owed" means a later step of the migration has to change it.

Core (Systemorph/MeshWeaver)

MeshWeaver.Plugins

Nothing in Plugins calls PlatformReleaseOrder. Every platform-version reader there is hand-written, and most of them recognise only ci.N. That is the largest share of the owed work. The cure is to delegate to core's order, not to add another regex.

Memex (Systemorph/Memex)

The agent-facing prose that teaches the old notation (AGENTS.md and skills in Plugins and Memex, Memex docs/*) is updated in the step that changes the behaviour it describes.

4. Migration order

Readers go first, then the data, then the minter. Each step is safe on its own. The tests in §5 show it.

1. Core readers (this change): PlatformReleaseOrder, VersionSelect (Stable), the resolver, arm-promoted-set.py, platform-version.py, main-cd.yml's readers, the gate lane. It merges and rolls to every portal, the control instance included. Until a portal runs this reader it ranks 3.1.N below every 3.0.0-ci.*, because a clean tag without a run number used to fall into the promotion band.
2. Plugins readers: SelfUpdateRouting.BuildOrder, RollGates, ImageLine, ModuleInventoryContent, DeploymentStatus delegate to PlatformReleaseOrder. InstanceComposition seeds 3.* / 3-latest. The freeze regexes, platform-requirement.py, mesh-floors.py, ceiling-adoption.py and the ci.yml floor-stamp gate accept both notations. Rolled to the control instance (it hosts the operator and the roll lane).
3. Memex data: every record's updatePattern → 3.*, overlays' SelfUpdate__DefaultPattern → 3.*, seeds → 3-latest, check-no-pins.py, resolve-line-pointer.sh, resolve-portal-image.py, image-contains.py, ci-platform-refresh.py, preflight-provision.py. Widening a pattern to 3.* before any 3.1.N exists changes nothing. The withdrawn 3.1.0-ci.7841 matches the glob but is ranked 7841. The record change goes through the governed record path. Nobody edits live records by hand.
4. Core minter: PlatformVersion → 3.1.0, Version → <major>.<minor>.<run> under CI and <major>.<minor>.0-ci.0 locally, with the scheme guard rewritten to the new shapes. From this merge on, CD mints 3.1.<run>, arm moves 3-latest/3.1-latest, and 3.0.0-latest freezes.
5. Plugins minter: portal-ai-image.yml mints the new notation. Floors are stamped as 3.<minor>.<run>.
6. Retire the 3.0.0-ci* examples in docs, skills and AGENTS files. Leave 3.0.0-latest frozen until no overlay seeds from it.

Do not reorder steps 3 and 4. A record still on 3.0.0-ci* admits no new-notation build, so every Continuous install freezes on its last old-notation set. Its only signal is "no newer release", and that verdict is easy to misread.

5. What the tests prove

• PlatformReleaseOrderTest.TheOldAndTheNewNotation_InterleaveByPublicationOrder: 3.0.0-ci.9999 < 3.1.10000, while a later old-notation set 3.0.0-ci.10002 still outranks 3.1.10001 (the run decides, not the notation). The slip stays at 7841. A mixed set sorts in one total order, and TheTotalOrder_IsTransitive_AcrossBothNotations checks it for every permutation.
• Negative control: with the new-notation reading reverted (SemVerBuildPatch returning null), the interleave, transitivity and BuildOrdinal cases fail, and so do three VersionSelect cases. Without the reader, 3.1.N lands in the promotion band and is never chosen.
• VersionSelectTest.TheOldFleetPattern_NeverSelectsTheNewNotation: why step 3 comes before step 4.
• VersionSelectTest.WideningThePattern_BeforeTheCutOver_ChangesNothing: why step 3 is safe early.
• VersionSelectTest.Stable_NeverSelectsANewNotationBuild: decision 1 in §6, as implemented.
• AFloor_IsOrderedAcrossTheCutOver: a floor in either notation is ordered against a build in the other.
• The script self-tests (platform-version.py, arm-promoted-set.py, resolve-platform.py, test-gate-lane-forwards-the-callers-set.py) check the same table. A negative control on the resolver (moving its boundary to 9.9) fails exactly the new-notation cases.

6. Decisions taken (maintainer can override)

These were open when the scheme was drafted. Each was settled the conservative way: nothing already published is renamed, the minor moves only by an explicit, governed action, and Stable keeps following what it follows today. Overriding one is a follow-up change to this page and the code it names. None of them affects the one-lineage order in §1.

1. Stable keeps following deliberately cut releases. Stable excludes every run-numbered tag (VersionSelect.PickTargets, pinned by VersionSelectTest.Stable_NeverSelectsANewNotationBuild), so a Stable install, the seeded default, never starts following main. It reaches a new-notation line only through a release (decision 2). Not chosen: a stable channel pointer (Release Channels), or Stable as "Continuous with a minor-pinned pattern". Either would change what every Stable install follows on the day it lands.
2. release.yml keeps promoting, and renames nothing. A v<major>.<minor>.0 tag on a sealed commit adds the clean tag <major>.<minor>.0 to that commit's already-published <major>.<minor>.<run> set, copies its release marker and opens the next-line pull request, exactly as it does for v3.0.0 today. The <major>.<minor>.<run> tag stays where it is. In the new notation the release moves no -latest pointer: the set it promotes was armed by CD, which already moved 3-latest/3.<minor>-latest to it or past it, so a release-side move could only move them backwards. GHCR latest still follows releases. This is implemented with the minter (step 4). Not chosen: retiring the promotion step, or a git-tag-only release with a channel pointer.
3. The minor is bumped only by a merged pull request that edits PlatformVersion. In practice that is the next-line pull request release.yml opens after a release (3.1.0 → 3.2.0), which goes through the same review and required checks as any other change. No workflow, script or self-updater edits PlatformVersion on its own. The run number keeps increasing across the bump, so the order is unaffected.

A known risk, not a decision: the counter is GITHUB_RUN_NUMBER of main-cd.yml. Renaming or recreating the workflow resets it. That risk exists today. With the patch as the run number it becomes visible in every version, so it is now a SemVer regression as well as a lineage one.