Platform Versioning (SemVer)

Policy platform-semver-versioning. Every platform build CD publishes from main is a plain SemVer release <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. No version carries a channel word: no ci, no rc. A build that publishes nothing (pull request, local, a satellite lane compiling core) is <major>.<minor>.0-dev. 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.

Why the line is 3.1, and why the patch continues the run number

The first build of the minter is 3.1.<run> with <run> the next main-cd run (≈ 10330 at the cut-over). Two other choices were considered and rejected:

• 3.0.<run>. Every deployed reader already reads a clean 3.0.x as a PROMOTION with no run number, so 3.0.10331 would land in the promotion band and lose to every 3.0.0-ci.* set. Moving the boundary would need a second fleet-wide roll of the readers before the minter could flip.
• Restarting the patch at 1 (3.1.1, 3.1.2, …). SemVer would still order 3.1.1 above 3.0.0-ci.10330, but the self-updater, retention, floors and the never-backwards guards rank by RUN NUMBER (one lineage, #3542), and 1 < 10330: every Continuous install would freeze on its last 3.0.0-ci set. Continuing the run number keeps SemVer and the lineage in agreement, so no reader has to choose between them.

The cut-over: what keeps working

• Existing images and floors. 3.0.0-ci.<n> tags stay in the registries and keep their order: 3.0.0-ci.10330 < 3.1.10331 by run number and by SemVer. A floor stamped 3.0.0-ci.10317 is met by every 3.1.<run>; a floor 3.1.<run> holds a portal still on the old notation until it rolls.
• Patterns. 3.* (every Systemorph record, Memex step 3) admits both notations. A record still on 3.0.0-ci* admits NO new build and freezes silently — the PartnerRe estate's records (Systemorph/PartnerRe.Memex) are widened in their own repository.
• Mixed fleets. A portal decides WHICH tag through its own VersionSelect and hands it to the control lane. A portal whose image predates the step-1 readers (merged 2026-10-07 15:01Z) ranks 3.1.<run> below every 3.0.0-ci.* set, so it takes TWO hops: first the newest old-notation set (which carries the readers), then the new notation. Measured at the cut-over: control and memex had the readers; memex-cloud (3.0.0-ci.10148) and pearl did not, and were already not rolling for an unrelated reason. The control lane's own lag check (SelfUpdateRouting.RollInsteadOfRestart, Plugins step 2) reads both notations and opens a roll to control's newest seen tag on a restart-pending.
• Binding identity. AssemblyVersion moves 3.0.0.0 → 3.1.0.0 with the line, as designed (PlatformBinding.MayBind): every module compiled against 3.0.0.0 binds on a 3.1 portal by roll-forward, and a module compiled on a 3.1 build meeting a lagging 3.0 portal is declined loudly as a binding conflict — the same answer its floor gives. MeshWeaver.Plugins and MeshWeaver.SocialMedia derive their AssemblyVersion from the platform's PlatformVersion, so they follow without a change of their own. (Pinning it per major was tried in review and rejected: it changes the expression those repositories verify, turning a version bump into a paired change.)
• CD targets the newest VOUCHED commit, not main's tip. main-cd's workflow file is main's, but the tree it builds is the gate's target, which can predate the minter for a tick or two after it merges. Such a run mints the retired <line>-ci.<run> with THIS run's number — still one lineage — and main-cd's shape assertion accepts exactly that, never a -dev or another run's number. Measured on the cut-over: main-cd #10351 targeted c6310ff (the minter's tip 118dd05 had no completed required check yet), composed 3.0.0-ci.10351, and the first version of the assertion refused it.
• The release. release.yml promotes a <major>.<minor>.<run> build by adding <major>.<minor>.0, moves no pointer for it, and still promotes a retired-notation set the old way.

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 (done, MeshWeaver#6208): 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 (done, MeshWeaver.Plugins#3091): 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 (done, Memex#676): 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> for a main CD build (-p:PlatformBuildNumber, passed only by main-cd) and <major>.<minor>.0-dev for every other build, 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.
• PlatformVersionSchemeGuard (step 4), through real MSBuild: the line is <major>.<minor>.0; a main CD build composes <major>.<minor>.<run>; -p:PublicRelease=true composes the line; a CIRun build WITHOUT -p:PlatformBuildNumber (a pull-request run) and a local build compose <major>.<minor>.0-dev; an invalid build number never mints a release version; no composition contains ci. Its control arm reintroduces a labelled line and a non-zero patch and requires both to be rejected.
• PlatformReleaseOrderTest.TheFirstSemVerBuild_OutranksEveryOldNotationSet (step 4): the real boundary pair 3.0.0-ci.10330 / 3.1.10331 for IsNewer, Newest, SemVer, PlatformFloor in both directions, and IsSourceBuild. -dev reads as run 0 and is advisory against every floor.
• FailureFromOlderPlatformRedriveTest.AFailureFromTheLastOldNotationBuild_IsRetriedOnce_OnTheFirstSemVerBuild (step 4): a compile failure stamped on the last old-notation build (FailedPlatformVersion, #6349) is retried once on the first new build and never by an older replica; a -dev live build never retries.
• 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.