Release & Self-Update Strategy

Support lifetime and official artifact retention follow the Release Support Policy.

✅ Rule change, 2026-09-07 (maintainer) — Module Adoption Policy, implemented by #3648, #3649, #3650 and #3651. This page describes the mechanism as it runs after those changes: a declared floor is advisory, a refused generation falls back to the previous one, a new build is adopted eagerly, and a platform roll is held only by a module that provably cannot load on the target.

🚨 Superseded for the platform roll by policy platform-rolls-independently-of-packages (Policy Not Prose): no package answer holds the roll any more — it is an advisory; Release Gates → "What a refusal does".

The production model in one picture:

PR ──[merge preconditions]──▶ main ──[CI: build ALL images, tag by version]──▶ ACR
                                                                                 │
                                  each install polls ACR per Admin/UpdatePolicy ◀┘
                                  Stable (default) → newest clean release · Continuous + pattern → newest build the pattern admits · None → manual
                                                 │
                  AKS / local k3s: patch own deployment   MAUI: notify + relaunch

One central version, two channels (continuous build vs official release), and every install keeps itself up to date. The version mechanics live in Release Process & Versioning; where the images go is Deployment.

1. Merge preconditions

A PR may merge to main only when all four hold. CI enforces (a)+(b); branch protection + a reviewer enforce (c)+(d). The checklist is in .github/pull_request_template.md.

Branch-protection settings to configure once (GitHub → Settings → Branches → main; gh can't set these): require the Build and Test Results status checks; require ≥1 approving review; require review from Code Owners; require conversation resolution before merging.

2. Versions: current-build vs official

Two shapes, and no others: X.Y.Z-ci.<n> for every continuous build, clean X.Y.Z for the release. No rc, no preview, no beta, no labelled line, ever — the scheme, the mint-versus-read split and the ordering consequences are stated once, authoritatively, in Release Process & Versioning §1; this page describes what the two channels do with them.

The one number is PlatformVersion in Directory.Build.props — today 3.0.0, the next release. Every build derives its version from it (details):

• Current build (continuous): 3.0.0-ci.<n> — the default. <n> is the GitHub Actions run number (monotonic), so newer builds always sort higher. 🔴 This monotonicity is load-bearing: the self-updater picks the newest version, and the old seconds-since-midnight build number reset at midnight (a morning build would sort below the prior evening's). Do not revert it.
• Official release: clean 3.0.0 — the same bytes as one continuous build, promoted by release.yml when the annotated tag v3.0.0 is pushed on a commit main-cd has promoted and sealed. Nothing is rebuilt. Cut only when every open issue is closed.

🚨 Candidates are ranked by the CD run number, not by the version string (#3542). <n> is the ordering key: a 3.1.0-ci.7841 published before 3.0.0-ci.7977 loses to it, and so does a retired 3.0.0-rc9.ci.7824 — SemVer compares pre-release identifiers as text, which is how a mislabelled line outranked every sealed set for ever and rolled both AKS portals three days backwards on 2026-09-07. An official release carries no run number of its own (it is a promotion of a sealed set), so it is ranked by version — which is what keeps a Stable install running a continuous build able to reach it. Full reference: Self-Update Target Selection.

No pre-release label on the core beyond -ci.<n>, and no rc line — retired 2026-09-05, settled 2026-09-07. -ci.<n> is a channel marker, never a version; the release is a promotion of a sealed continuous set, not a rebuild; and nothing else may ever be minted. The bump to 3.1.0 still happens the day 3.0.0 is tagged — the lane opens that pull request. Full rule: Release Process & Versioning §1.

Cutting an official release and starting the next line

1. Cut the official release: commit the notes page Doc/ReleaseNotes/3_0_0, then push an annotated v3.0.0 tag on a promoted, sealed commit. release.yml retags that commit's set with the clean version in ACR, mirrors it to GHCR, records the release marker and publishes the GitHub Release. Stable installs pick it up.
2. Start the next line: merge the pull request the lane opened — PlatformVersion 3.0.0 → 3.1.0. Continuous builds are now 3.1.0-ci.<n>, above the release.

3. CI produces ALL images, tagged by version, on ACR

Both channels publish the full image set to meshweaver.azurecr.io, tagged by the version string — that tag is what each install compares.

So the continuous build produces all images, the release names one of them, and a running install only has to list ACR tags and pick the best per its policy. (main-cd.yml still rolls the environments once as the bootstrap; steady-state updates are the self-updater below.)

Two properties of the continuous leg matter to a reader of tags:

• Only the version tag is selectable. VersionSelect.PlatformVersionTag requires ^\d+\.\d+\.\d+, so the moving main pointer and the per-run staging-<sha>-<run_id> tag are invisible to every self-updater by construction.
• Publication is all-or-nothing. Each leg pushes only its staging tag; the promote job applies the real tags after all five legs succeed, ending with memex-portal-ai:<version> — the single write the self-updater acts on.

4. The update policy — Admin/UpdatePolicy

A single mesh node, edited by platform admins under Settings → Updates (a dropdown and a pattern field bound straight to the node). Default Stable — clean releases only (maintainer, 2026-09-08: "by default we will not upgrade as long as no version without -ci… is labelled").

Fleet today (no clean release above 3.0.0 yet): every portal instance carries Continuous + 3.0.0-ci*, to be changed the day 3.0.1 is tagged. The record shapes and the semver rule are in Release Process & Versioning → "Which build an install takes".

The poller (SelfUpdateHostedService) reads this node live: changing the policy re-drives it immediately. It checks ACR a few times a day, records the latest tag it sees on the node (LatestAvailableTag, surfaced in the admin tab and to the MAUI notifier), and — where it can — applies the update.

5. How each install updates

The platform rolls independently of its packages

🚨 The platform rolls independently of its packages — policy platform-rolls-independently-of-packages (Policy Not Prose). A package-availability verdict is never a hold on the platform roll. It is an advisory: logged, recorded on Admin/UpdatePolicy, shown on the Updates and About tabs — and the roll proceeds to the newest admitted tag. Packages catch up on their own (their own update policy, the held-update lane), never the reverse.

Whichever target it is, the poller still asks the release availability gate about the newest tag the update policy admits: does every package this deployment runs have a usable artifact for it, can its framework identity be resolved, can the catalogue be read, can every landed module load against the surface it published (the link gate), and — from the combo gate — do the landed modules compile and test against it. Those are questions about packages, and under policy platform-rolls-independently-of-packages their answers never decide which platform build an instance runs:

• The gate answers yes — the roll proceeds, with whatever it reported without holding (a course with no prebuilt bake for that build, which compiles when the new build starts; a module whose loadability could not be measured, which the platform decides at start-up and keeps the previous version of if the new one cannot load).
• The gate answers no or "cannot determine" — a missing bake under Modules:RequirePrebuilt, an unresolvable framework identity, a package without an artifact, an unreadable catalogue, an unloadable module, a recorded combo Red, even an unregistered gate — the roll still proceeds. The refusal becomes the first advisory line ("the platform rolls independently of packages — N package(s) … catch up through their own update policy: …"), every package that does not follow is named, and the check verdict says PACKAGE ADVISORY. No HeldTag is written, and a hold recorded by an older build is cleared on the roll.

Everything is written to the same node (AdvisoriesTag, Advisories) and shown on the Updates tab beneath the available line; the About tab says, in one translated sentence, that the platform rolls (or rolled) with package advisories and points to the Updates tab — the advisories themselves are server-written diagnostics and stay on that admin surface — and no longer reads ⏸️ Update held — a package … is not available. The roll selection CD reads (/api/plugins/roll-target), the manual-roll check (/api/plugins/is-updatable, which now returns the waived reason as waivedHold), the reboot's image step and the Apply update now button all apply the same rule, so no roll path selects differently from the poller.

Why. Measured on an enterprise deployment on 2026-10-11: Admin/UpdatePolicy read HOLDING 3.1.10502 — the framework identity of release 3.1.10502 is not resolvable — no content bake has been published for it … (heldIndeterminate=true), while every package update on the same instance was held because it needed platform >= 3.1.10493. The platform waited for the packages and the packages waited for the platform — a deadlock only one direction can break. Another deployment ran 3.1.10502 fine.

The pure predicate (ReleaseAvailability.IsUpdatable) still answers the package question truthfully — "cannot determine" is still not "available" — because the CI build gate and every surface that lists package availability need that answer. Only the platform roll waives it (UpdatabilityVerdict.ForPlatformRoll).

Postgres ("auto-update pg")

• Schema / db_version is kept in step automatically: the migration container is rolled to the same version as the portal on every update — the migration is what applies schema changes, so the database is always current for the running code. This is the meaningful, safe "auto-update pg."
• The Postgres SERVER image stays at its pinned major (e.g. pgvector:pg17). A major upgrade is never automated — it needs pg_upgrade against the data volume (data-loss risk) and is a deliberate, manual runbook. On AKS/Container Apps Postgres is a managed Flexible Server (Azure handles minor upgrades; the in-pod updater never touches it).

6. AKS prerequisites (ACR polling; the in-pod patch only where it is still allowed)

The Helm chart (deploy/helm/templates/memex-portal/) ships these:

• serviceaccount.yaml — memex-portal-sa (the pod runs as it). It carries no Kubernetes right by default.
• rbac.yaml — rendered only with selfUpdate.canPatch: true: a Role granting get,patch on the portal + migration Deployments only (scoped by resourceNames), bound to the SA. The same value renders SelfUpdate__CanPatch into the ConfigMap, so with the default (false) the poller never attempts the PATCH — it hands the release to the control instance instead (Self-Update on the Control Lane). A helm upgrade with the default DELETES a Role a previous release created.
• deployment.yaml — sets serviceAccountName, and (when selfUpdate.azureClientId is set) the azure.workload.identity/use label + AZURE_CLIENT_ID.

For ACR polling on AKS you must, once per environment, create a user-assigned managed identity, federate it to system:serviceaccount:<ns>:memex-portal-sa, grant it AcrPull on meshweaver.azurecr.io, and set selfUpdate.azureClientId (e.g. in values.aks.yaml / via Key Vault) to its client id. (Mirrors the existing pgbackrest-sa workload-identity wiring.) The in-cluster Deployment PATCH works without this; it only authenticates the tag-list call.

7. Operate & verify

• Set the policy: Settings → Updates (platform admin). The dropdown writes Admin/UpdatePolicy.
• Watch a continuous roll (AKS): merge to main → a new …-ci.<n> tag lands on ACR → within the poll window a Continuous install patches memex-portal-deployment + memex-migration-deployment (kubectl rollout status).
• Pin an environment: set the policy to None. Stable (the default) is releases-only; a Continuous install follows only the line its pattern names.
• Manual apply: Settings → Updates → Apply available update now — on the fleet it hands the latest tag to the control instance (the same event the poller sends); on a standalone install that may self-patch it patches.

The decision logic (which tag each policy picks; "is newer") is unit-pinned in VersionSelectTest (ordering, and the three-valued "does my own tag still exist" check) and SelfUpdateStrandRecoveryTest (the poller, against a real mesh); the enum dropdown in MeshNodeEditorFieldTest.

8. Cut a release — operator runbook

Three operator actions, two independent channels, and steady state is self-update: you push images (by merging or tagging) and installs roll themselves per Admin/UpdatePolicy — you do not kubectl set image by hand. Forcing a specific tag on one instance is a Roll Hosting/InstanceAction on the control instance (OperatingFromThePortal); the manual AKS runbook is what the operator runs for it, and the break-glass path when the control plane itself cannot act.

# (a) ship a continuous build — just merge; CI builds + pushes + seals the image set
git switch main && git pull

# (b) cut the official release — an immutable, ANNOTATED tag on a commit whose CD run sealed
#     (Doc/ReleaseNotes/3_0_0 must already be committed; the lane refuses a release without notes)
git tag -a v3.0.0 -m "MeshWeaver 3.0.0" <sha> && git push origin v3.0.0

# (c) open the next line — merge the pull request release.yml opened:
#     release: PlatformVersion 3.0.0 → 3.1.0

(a) can look shipped and produce no image. CD reacts to MeshWeaver Build and Test completing on a push to main — a hand-kicked workflow_dispatch of that workflow turns main green and CD still skips. Verify the IMAGE (.github/scripts/check-image-set.sh <short-sha>), and re-drive CD with gh workflow run main-cd.yml --ref main if it is missing (it also self-heals HEAD on a hourly schedule).

(b) depends on (a): a tag can only name a set that a merge already shipped and sealed — that is the whole point of a promotion. (c) follows (b) once per release line, opened by the lane and merged by you. The version mechanics behind each step are in Release Process & Versioning; §2 above covers the same cut from the version-scheme angle.

9. See also

• The Continuous Delivery Contract — what main-cd.yml guarantees about the set: all-or-nothing publication, the promote ordering, the reconciler, and verifying the image rather than the tick.
• Release Process & Versioning — the version-number mechanics.
• Deployment — the two deploy routes (AKS vs Container Apps).
• DeploymentAKS · LocalColimaMac.
• Request via stream.Update · Controlled I/O pooling — the patterns the poller is built on.