docs: the Module Adoption Policy — keep what you have, load on measurement, take what ships by rbuergi · Pull Request #3652 · Systemorph/MeshWeaver

rbuergi · 2026-09-07T21:55:59Z

What

Doc/Architecture/ModuleAdoptionPolicy — the maintainer's rule of 2026-09-07 for what an installation runs, and the plan that implements it:

R1 continuity: an installation runs the newest module version that loads; if nothing newer ships for its platform, it keeps the one it has.
R2 measured, never declared: loadability is the type-level link probe and the load itself; a declared minMeshVersion or module-version dependency is advisory.
R3 eager adoption: a newly shipped version that loads is adopted within minutes.

Four implementation issues, in order: #3648 (floors advisory at every runtime decision point — also the exit from today's self-update deadlock without a production write), #3649 (keep the previous generation as the boot fallback), #3650 (eager adoption + a publish broadcast), #3651 (the roll gate on measured loadability against the target's published surface; a missing bake is a boot compile, not a hold).

Twelve architecture pages that state the superseded rule (Modules, ReleaseGates, SelfUpdateTargetSelection, ModulePlatformLinkGate, RollSelection, ReleaseStrategy, ModuleVersioning, ModuleSetConvergence, PluginPackaging, ReleaseGateDenominator, CiContentBake, SelfUpdateSchemaWall) carry a banner naming the issue that rewrites them; their mechanism text stays accurate until then. Plus a What's New.

Why now

On 2026-09-07 every production portal was held on the morning build (3.0.0-ci.8009) for the whole day: the installed Plugins/* records carried rc / 3.0.0 floors, NuGetVersionComparer ranks ci < rc < clean, and the self-updater declined all 11 candidates ("77 plugins required … every one declined") while every one would have loaded. The one-time exit is a pipeline roll; the policy is what stops it recurring.

Docs only. The survey the page rests on covered every decision point in MeshWeaver.PluginCatalog, Compiler.Pipeline, Hosting, GitSync and the self-updater, and every architecture page mentioning a floor, a hold or adoption.

🤖 Generated with Claude Code

…ement, take what ships Maintainer directive, 2026-09-07: if no plugin version is shipped we use the old one; we make it load despite a newer dependency on the platform or another module; as soon as a new module version ships we start using it; deployments must become far more robust. The page states the three rules, what "loads" means per lane, what the platform roll gates on, the four-step implementation plan (#3648 floors advisory, #3649 keep the previous generation, #3650 eager adoption, #3651 roll gate on measured loadability) and what stays. Twelve architecture pages that state the superseded rule carry a banner naming the issue that rewrites them. Plus a What's New. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

…olicy banner Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Copilot

🟡 Changes recommended

A few doc-metadata/wording issues were found in the changed lines (invalid WhatsNew Category value and minor grammar in multi-issue banners).

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a new architecture policy page defining how installations should adopt and retain modules (“keep what you have, load on measurement, take what ships”), and annotates existing module/self-update docs with a 2026-09-07 rule-change banner pointing readers to the new authority page.

Changes:

Add Doc/Architecture/ModuleAdoptionPolicy documenting the maintainer directive and the four-step implementation plan (#3648–#3651).
Add a “What’s New” entry describing the policy change and linking to the new policy page.
Add rule-change banners to affected architecture pages to explicitly mark them as superseded pending the implementing issues.

File summaries

File	Description
src/MeshWeaver.Documentation/Data/WhatsNew/2026-09-07-your-installation-keeps-running-what-it-has-and-takes-what-loads.md	New What’s New entry announcing the module adoption policy and linking to the authority doc.
src/MeshWeaver.Documentation/Data/Architecture/ModuleAdoptionPolicy.md	New architecture authority page defining the adoption rules and implementation plan.
src/MeshWeaver.Documentation/Data/Architecture/SelfUpdateTargetSelection.md	Add banner deferring to Module Adoption Policy and naming the implementing issue.
src/MeshWeaver.Documentation/Data/Architecture/SelfUpdateSchemaWall.md	Add banner clarifying what is and isn’t superseded by the new policy.
src/MeshWeaver.Documentation/Data/Architecture/RollSelection.md	Add banner redefining roll selection under the new measured-loadability rule.
src/MeshWeaver.Documentation/Data/Architecture/ReleaseStrategy.md	Add banner describing updated “hold” semantics under the new policy.
src/MeshWeaver.Documentation/Data/Architecture/ReleaseGates.md	Add banner deferring gate semantics to Module Adoption Policy.
src/MeshWeaver.Documentation/Data/Architecture/ReleaseGateDenominator.md	Add banner clarifying bake-missing becomes advisory under the new policy.
src/MeshWeaver.Documentation/Data/Architecture/PluginPackaging.md	Add banner clarifying `minMeshVersion` becomes advisory at runtime.
src/MeshWeaver.Documentation/Data/Architecture/ModuleVersioning.md	Add banner clarifying same-version rebuild adoption and fallback re-examination.
src/MeshWeaver.Documentation/Data/Architecture/ModuleSetConvergence.md	Add banner clarifying HELD/fallback semantics under the new policy.
src/MeshWeaver.Documentation/Data/Architecture/Modules.md	Add banner deferring module-lane floor/hold semantics to the new policy.
src/MeshWeaver.Documentation/Data/Architecture/ModulePlatformLinkGate.md	Add banner deferring gating/fallback semantics to the new policy.
src/MeshWeaver.Documentation/Data/Architecture/CiContentBake.md	Add banner clarifying bake-missing becomes advisory (boot compile) under the new policy.

Review details

Files reviewed: 14/14 changed files
Comments generated: 4
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.


 # The Module Platform Link Gate

+> 🚨 **Rule change, 2026-09-07 (maintainer) — see [Module Adoption Policy](@/Doc/Architecture/ModuleAdoptionPolicy).** The link probe becomes the ONLY platform gate on the module lane (the declared floor no longer gates first), and a refused generation no longer leaves the module absent: the previous loadable generation is loaded and named. The mechanism described below is what runs until [#3648](https://github.com/Systemorph/MeshWeaver/issues/3648) and [#3649](https://github.com/Systemorph/MeshWeaver/issues/3649) lands; this page is rewritten by that change.


 Icon: <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3l8 4.5v9L12 21l-8-4.5v-9L12 3z"/><path d="M12 12l8-4.5M12 12v9M12 12L4 7.5"/></svg>
 ---

+> 🚨 **Rule change, 2026-09-07 (maintainer) — see [Module Adoption Policy](@/Doc/Architecture/ModuleAdoptionPolicy).** A declared `minMeshVersion` no longer refuses, holds or skips a module anywhere on this page's lane — loadability is measured by the link probe, and an installation keeps its previous generation when a newer one does not load. The mechanism described below is what runs until [#3648](https://github.com/Systemorph/MeshWeaver/issues/3648) and [#3649](https://github.com/Systemorph/MeshWeaver/issues/3649) lands; this page is rewritten by that change.



 # Release Availability Gates

+> 🚨 **Rule change, 2026-09-07 (maintainer) — see [Module Adoption Policy](@/Doc/Architecture/ModuleAdoptionPolicy).** The module floor is no longer a release gate, as a regression check or otherwise; a missing content bake is reported as a boot compile, not held; the only module-lane hold is measured loadability on the target. The mechanism described below is what runs until [#3648](https://github.com/Systemorph/MeshWeaver/issues/3648) and [#3651](https://github.com/Systemorph/MeshWeaver/issues/3651) lands; this page is rewritten by that change.


github-actions · 2026-09-07T22:27:13Z