Module Versioning

🚨 Rule change, 2026-09-07 (maintainer) — see Module Adoption Policy. Delivery is no longer keyed on SemVer alone: a rebuilt same-version bundle for this platform's identity is adopted, and a fallback generation re-examines every new build. Implemented in PR #3661 (2026-09-08); the sections below describe the mechanism as it runs now.

A package's version is not decoration. It is the ONLY thing that decides whether anything you built reaches a portal that already has an older copy. Get it wrong and the pipeline stays green, the bytes reach the shelf, and no installation ever asks for them.

This page is the authoring reference for that number. For the node revision counter — a different number entirely — see MeshNode Versioning. For what a module IS and how a deployment activates one, see Modules.

🚨 The PLATFORM's version is a third number, and it is not authored here. PlatformVersion has exactly two shapes — X.Y.Z-ci.<n> for every continuous build and clean X.Y.Z for the release, no rc, no preview, no labelled line, ever — stated authoritatively in Release Process & Versioning §1. Read it before writing a package's content.minMeshVersion floor: a floor is a platform version, and SemVer §11.4 ranks pre-release identifiers as text, which is how 42 packages came to declare floors no shipping platform could ever satisfy (#3554). 🚨 A floor is an authoring claim checked at pack time (check-module-platform-floor.py refuses one above the platform the bundle is built against) — at runtime it is advisory and loadability is measured, never declared (issue #3648). Getting it wrong therefore fails your build; it is not a knob for keeping a module off a deployment.

🚨 The compatibility LADDER — what keys compiled bytes (policy platform-backwards-compatibility)

Policy platform-backwards-compatibility: platform builds are backwards compatible within a major and a declared compatibility epoch. This section is the manual for it; every older section below that speaks of "the framework identity" moving on a platform roll describes the scheme this one replaced and is kept as the record of why.

The ladder. platform1+plugin1 → platform2+plugin1 → platform2+plugin2 → platform3+plugin2 → …. A platform roll keeps the OLD plugin bytes — no rebuild, no re-seal. A plugin rolls independently, built against the platform that is RUNNING. Only a declared break (an epoch bump, or a major bump) steps off the ladder, and it does so on purpose.

The key. Compiled NodeType bytes and module bundles are keyed on the platform compatibility key c<major:D3>e<epoch:D3> — e.g. c003e001 — never on a per-build identity:

The per-build surface/commit identity (s<hash> / g<sha>) is provenance only — FrameworkBuildIdentity.BuildProvenance, ProducerStatedProvenance, ResolveBuildProvenanceForDirectory, FrameworkIdentity.ReadProvenance. It is logged (the pre-warmer names key, platform build and provenance together) and recorded, and it NEVER decides a cache miss, an adoption, a load or a roll. PlatformCompatibilityRatchetGuard reds any statement that compares one of those members.

The RANGE: floor and ceiling. Within one key, bytes carry a platform range:

The one rule, PlatformCompatibility.DeclineReason(producedKey, floor, ceiling, liveKey, running): same key AND floor ≤ running ≤ ceiling ⇒ adopt and bind to the running platform; anything else ⇒ declined LOUDLY, both versions named. There is no other version gate. An absent floor is "unknown producer = older" — accepted, so every record written before the field existed stays adoptable. Ordering is PlatformReleaseOrder (the ci.<n> run ordinal); a release against a continuous build is unordered and therefore never a "newer" reading.

Binding. A plugin/NodeType assembly compiled against platform 3.0.0.0 binds on a platform stamped 3.1.0.0: PlatformBinding.MayBind(compiledAgainst, running) is running >= compiledAgainst, applied by the module link probe (ModulePlatformLink: lower ⇒ linkable with an advisory, higher ⇒ BindingConflict, i.e. floor not met), and the NodeType load context and ModulesAssemblyLoadContext resolve every platform name through the default context (TPA roll-forward) — never a private copy, never an exact-version hard link.

What a mixed roll does. Two builds of one epoch serving one mesh (P2 draining, P3 new): P3 adopts every record P2 wrote (older floor ⇒ in range) and recompiles nothing. A record P3 writes (a source change) carries floor P3; P2 reads it as out of range and — because the ORDER is known from the run ordinal — yields unconditionally (NodeTypeBuildIdentity.OwnedByANewerPlatformBuild → DecideFrameworkStale = Yield), overlaying that one type instead of re-keying it backwards. No re-key war. The census (bake-report's LIVE RECORD CENSUS) counts those records as foreign on P2 by the same reader. The ONE roll that crosses from the per-build scheme to the key (old image s…, new image c003e001) behaves exactly as every roll did before this change: records re-key once (the #5353 leaving-yield keeps the draining replica from fighting it), and from then on rolls within the epoch re-key nothing.

A DECLARED BREAK. When compiled bytes must be invalidated — a public API removal or signature change compiled content can bind, or a change to the skeleton generator (DynamicMeshNodeAttributeGenerator) or any toolchain-generated compile input whose old output is no longer loadable or correct — bump "epoch" in platform-compatibility.json and append a breaks entry: { "epoch": <new>, "previousEpochCeiling": "<last platform build of the old epoch>", "reason": "…", "declaredIn": "#<PR>", "members": [...], "affected": [...] }. Everything built against the old epoch then declines (its effective ceiling is previousEpochCeiling, CompatibilityDeclaration.CeilingForEpoch), and ONLY then does a coordinated rebuild and seal of the affected plugins sit on the path. Never gate on an exact build identity, never seal or pin an image around a break: fix compatibility (an [Obsolete] forwarder, an API restore, the binder) or declare the break.

The three numbers, and who owns each

You author a series. The build derives the patch against the last published release and settles it on main in tag-modules, so a branch never races the trunk for a number.

The hash input is the Git-visible package tree: tracked files plus non-ignored untracked files in the working tree. Git-ignored local outputs (for example, a test .trx file under a package) are not package content and do not affect moduleVersion. This keeps a developer's post-merge lock identical to the lock CI derives from the commit; a new non-ignored content file still needs to be committed with its regenerated lock.

• Bump the MINOR for a feature. Bump the MAJOR for a break. That is the whole authoring rule.
• 🚨 Never hand-edit the PATCH. It is derived. A hand-set patch is a claim about a tree you did not measure.
• 🚨 Never commit a node's version field. That is MeshNode.Version, the owner's persistence clock — not authorable content. A committed counter collides with the durable row on a fresh mesh, MonotonicWriteGuard refuses the write, and the symptom surfaces four causal steps away as "never reached compilationStatus Ok". Strip version, lastModified and lastModifiedBy from anything you copy out of a live mesh.
• 🚨 A published version describes exactly one tree, forever. tag-modules.py refuses to move an existing tag onto different content. Bump; never re-cut.

Why an unchanged version means "delivered to nobody"

Module delivery is keyed on SemVer and nothing else. Two independent gates close on an unchanged version, and neither looks at the bytes:

• ModuleUpdateDecision — landedComparison == 0 → SkipUpToDate. The verdict is taken before any download, and the fetch carries no If-None-Match, so there is no byte-level fallback.
• CatalogLayoutAreas — the manual Update button returns InstallResult(0, 0) on ModuleVersion equality, before the module half is even composed. The human override does not override.

CI still rebuilds the assembly and POSTs it to bundles/<Package>?version=<unchanged>. The shelf is correct. Nobody requests it. A fresh install gets the new code; every existing portal keeps the old one forever — and the repo, CI and the registry all look green. This is MERGED is not delivered one layer down.

🚨 The blind spot: src/ and mixed packages

A mixed package declares content.module and ships an assembly built from src/.

gen-manifests.py enumerates packages with plugin_dirs(), which skips the set the repo declares in scripts/gen-manifests.config.json (see "One checker, every repo" below):

{"skip": ["src", "test", "scripts", "tools", "e2e", "app", "clients", "meshweaver", "…"],
 "hashModuleSources": true}

That skip is deliberate and correct for enumeration — src/ is not a package, and skipping it is what keeps this gate independent of step order and of validate-repos.py. Do not "fix" this by deleting "src" from the skip list. That changes what moduleVersion means for every package. The narrower, correct switch is hashModuleSources.

The defect was narrower: for a mixed package, the module's own source under src/ was never hashed into moduleVersion — so a change confined to src/ moved no version, by construction, and was therefore built, shelved and delivered to nobody.

Measured on 2026-08-29: 12 of 29 mixed packages were in exactly that state. The worst was the AI engine itself — AI/manifest.lock on main was byte-identical to the tag AI/v1.0.0 (version 1.0.0, moduleVersion be7ff235b95fb8e4) across 205 changed src/ files. Since MeshWeaver.AI left the portal image, the module bundle is its only delivery channel, and Agent/ + Skill/ content ships as embedded resources inside that assembly — so an edit to a built-in agent reached nobody, silently.

The fix belongs in the derivation, not in a checklist. For a package declaring content.module, the hash must cover what actually ships in that bundle, so a src/-only change moves the hash, moves the derived patch, and is delivered. Nothing to remember.

What "what actually ships" means — the closure is narrower than the reference graph

Do not hash the whole dependency network. A bundle's contents are decided by DepsClosure.Derive, which walks the module's own deps.json from its direct references and stops at MeshWeaver.* nodes — those are never bundled, because a bundled copy would shadow the one in /app. Diamonds ride deliberately: /app wins in the default load context while the platform carries a copy, and the module's copy takes over when the platform sheds it, which is what lets platform slim-downs land with no re-land coordination.

So for a mixed package the hash should cover:

🚨 MeshWeaver.* is not one row — the container lane split it in two

The version derivation implemented for the fix above hashes the module's own project alone, on the reasoning that a MeshWeaver.* reference is never bundled. That reasoning is only half true, and the half it misses is live.

DepsClosure.Derive does stop at MeshWeaver.*, and that is what the sdk pack path uses (--deps-closure). The container path — now the default for nearly every entry — does not use it. It reads the module's closure manifest and, for every MeshWeaver.* sibling in it, asks module-owned-platform.sh one question: is this project's source in this repo's src/ and does the platform host not already ship it? If yes, the sibling is copied into the bundle and passed as --with <Name>.dll, and the job log says so:

🚨 That second half used to read "and absent from src/platform-shipped.txt" — a hand-maintained list, which drifted in both directions and put 27 duplicate copies into 14 of 37 bundles. It is now MEASURED off the pinned image; see The Platform-Shipped Witness.

closure: MeshWeaver.Blazor.dll RIDES — module-owned (its source is in this repo's src/,
         so it is nowhere in the image's /app)

It must ride: nothing else would supply it at run time. But the version derivation does not know that, so a bundle can change its bytes without moving its version — the exact defect the src/ fix above was written to remove, one hop out.

Measured on MeshWeaver.Plugins, 2026-09-01 (35 matrix entries, 119 module-owned MeshWeaver.* projects): MeshWeaver.Blazor is module-owned and rides in 7 published bundles — Analysis, AppleMaps, EntityViews, GoogleMaps, GraphViews, OpenStreetMap, Radzen. Not one of those seven manifest.lock files hashes a single src/MeshWeaver.Blazor/ path. An edit there changes what all seven bundles ship and moves none of their versions, so every existing portal keeps the old copy — SkipUpToDate, before any bytes are read.

The MeshWeaver.AI example in the row above is currently safe only by accident of a transition: MeshWeaver.AI is listed in that repo's src/platform-shipped.txt while MeshWeaver.Blazor.Portal still references the engine. That line is marked to leave with MeshWeaver#2599 — and the moment it does, every AI-provider bundle joins the seven above. Do not read "a change to MeshWeaver.AI does not require bumping MeshWeaver.AI.OpenAI" as a standing rule; it is a statement about one entry in one exclusion list on one day.

The correct scope is the RIDING closure, not the whole reference graph. Hash the module's own project plus exactly the MeshWeaver.* siblings module-owned-platform.sh says ride in its bundle. That is neither "own project only" (which under-covers, as measured) nor "the whole closure" (which bumps every dependent on any change and destroys the signal in the number) — it is the set whose bytes are actually inside the artifact being versioned.

The ProjectReference walker for this already exists — see scripts/check-surface-manifest.py (assembly names reachable from start through ProjectReference), scripts/project-closure.py, and the floor rule in scripts/check-module-floors.py. Reuse one of those rather than writing a fourth; the module-owned/image-shipped split is .github/scripts/module-owned-platform.sh, the same script the pack step and the bundle inspection call, so the three cannot disagree.

Until that lands, registry-version ≠ manifest-version is NOT a sound publication baseline. It is proposed periodically as a way to narrow the module lane on push (Plugins#889 option 3); version equality does not imply byte equality while any sibling rides, so narrowing on it would silently under-publish exactly the bundles above. A sound baseline has to be a commit — the analogue of the bake's source-commit.txt — diffed with project-closure.py, which walks transitive in-repo ProjectReferences and therefore sees riders for free.

If you are reading this while that derivation is still landing: bump content.version's MINOR by hand for any src/-only change to a mixed package, and say in the PR that you did so and why.

🚨 Version strictness — what a platform roll ADOPTS (Modules:VersionStrictness)

Maintainer directive, 2026-09-08: "typically it should accept newer platform versions, especially within the same family ⇒ we can have a setting for version strictness; but for dev we should be very tolerant and only use min versions." And earlier: "for every new platform release we should be able to just roll it and the old modules should work — then it is fully decoupled."

Until this setting, a portal adopted a prebuilt bundle only when it was sealed under the portal's exact framework identity (<root>/<identity>/<source>/). Every platform roll therefore adopted nothing until every satellite had re-sealed for the new identity, and on 2026-09-08 — with CD unable to produce a sealed set at all — that meant no roll. The identity gate is still the safest statement there is, and it is still the default for the image's own bundles; but a bundle's real requirement is the set of platform TYPES its bytes link against, and that is measurable from the assembly's own metadata (ModulePlatformLink, the module lane's gate — see Module Platform Link Gate). So adoption now has a strictness, decided by PrebuiltAdoptionPolicy and read once per sweep:

What the policy does per bundle:

1. This identity's seal adopts as before — no link check; the bytes were compiled against exactly this platform.
2. Otherwise the identity is placed on a line through the _releases/<version> markers (SealedPublicationIndex.ReleasesOf). Family declines an identity no marker names — it cannot establish the line and does not guess; Minimum does not need the line.
3. A candidate the line and floor admit is measured: ModulePlatformLink.Check over each assembly's type references against the running platform's surface. Linkable → adopted, stamped with the live dependency ids (PrebuiltAdoptionPolicy.LiveStampOf, so the build-currency clause does not immediately call it stale); unlinkable → compiled from source on a mesh that may compile, or refused loudly — naming the type and the missing member — on a Modules:RequirePrebuilt mesh.
4. The sweep takes, for each source this identity has not sealed, the newest sealed publication among the admitted identities (ShippedPrebuiltBundles.FallbackPublishedBundlesOf). A source this identity HAS sealed is never shadowed.

What the link check does not see, so nobody assumes it does: a member that moved on a type that still exists. That surfaces at activation (MissingMethodException), where the stale-build self-heal recompiles the type from source — the same fallback a declined bundle takes, one step later.

Development. Minimum is what "very tolerant" means: yesterday's bakes load on an unreleased platform unless a type they need is genuinely gone. A developer who wants the production rule sets Modules:VersionStrictness=Family (or Exact) in the Monolith's configuration — a configured value always wins over the environment default.

🚨 What this setting does NOT decide: whether the replicas of one installation converge on one sealed set. #3417 (fix for #3395) settled the mechanism — two compiles in one process resolve one module set — and deliberately left the POLICY open: whether a replica whose pinned set no longer matches should (a) restart itself, (b) flip readiness so the rollout replaces it, or (c) decline to write NodeType compile records while it is behind (#3417 → "Still open"; Modules → "Replicas of ONE deployment can run DIFFERENT module sets"). This setting inherits that gap unchanged: every replica reads the same shared storage under the same rule, so two replicas of one image choose the same publication unless a seal lands between their boots — the in-place-republish window Sealed Publication Reads describes, which Family/Minimum neither widen in kind nor close (they only admit more candidate directories). A replica's adoption is written onto the SHARED NodeType record with that replica's coordinates, exactly as a local compile is today. Whether replicas must converge — and how — is the maintainer's decision, and it is stated here so that it is not settled as a side effect of the strictness default.

Full rebuild when the platform updates

🚨 Superseded for every platform build within one epoch — see "The compatibility LADDER" above (policy platform-backwards-compatibility). A platform release no longer moves the key a module is declined on, so it no longer obliges a rebuild; the table below still describes what the lanes COMPILE, and a full rebuild is owed only behind a DECLARED break.

A module is built against a platform pin. When the platform releases, the pin moves and EVERY module must be rebuilt and republished — not only the ones whose source changed — or every portal reads FrameworkDeclined (built against <old>, live <new>) and adopts nothing.

So the two lanes differ deliberately:

The push row is the only one where the two lanes differ, and the difference is a missing marker, not a policy: bake-scope.sh reads a source-commit.txt sealed beside the bundles, so it knows the commit its own last publication covered. The module lane's scope still answers FULL on a push — but since 2026-09-02 the module build ledger sits below the scope (ModuleBuildArchitecture → "Content-addressed outputs"): every selected module is keyed by its whole compiled+tested closure plus both image digests and the platform ref, and a key the ledger already holds as Published is reused, not rebuilt. So a push compiles every module whose key has no usable Published record — the Plugins#889 baseline, derived from content rather than from a version or a commit, which is what makes it immune to the riding blind spot above. Callers opt in with ledger: required.

One checker, every repo

gen-manifests.py is the platform's, at .github/scripts/gen-manifests.py. node-repo-validate.yml fetches it at the caller's pinned platform-ref and runs it against the caller's tree, exactly as the compile-check lane runs .github/scripts/compile-check.py (AGENTS.md → "never hand-roll a node repo's CI"; Module Build Architecture → "scripts are centralized — the lane fetches the platform's copy at the pin; repos keep only allow-files").

It was vendored per repo until 2026-09-07, and by then the six copies were five different vintages — MeshWeaver.Plugins 1157 lines, Crm 646, Education 646, Reinsurance 644, SocialMedia 643, Manufacturing 305. Each fix landed in whichever copy hit the bug and the other five kept it: #434 (a release has two witnesses), #942/#1023 (--resolve), and #1426 — the trunk baseline resolved against the remote's live tip, which reds every intermediate commit of a merge-queue group on main, because the tree under test is compared against locks committed after it. Manufacturing's copy never grew the trunk witness at all, so it also had no --resolve and no self-test.

What stays in the caller is one allow-file, scripts/gen-manifests.config.json:

Both settings are declared, never inferred from whether a file happens to exist: a capability that degrades silently on a missing input is the skip-trapdoor shape AGENTS.md forbids, and here it would change what a published version means without saying so.

🚨 The declared skip is NOT the whole rule — ask --list-packages for the effective answer

plugin_dirs() applies the declared skip and an implicit rule of its own: a top-level dot-directory is never a package. Tooling writes them (check-examples.py builds under .example-check/, platform-script.py caches under .platform-scripts/) and hashing one as a module is how a scratch build ends up demanding a manifest.lock.

That second half is what makes check-skip-sets.py — which asserts validate-repos.SKIP == skip_set(root) — unable to see a divergence it exists to catch (#4774). A repo enumerates its top-level packages twice: here, and in its own validate-repos.py. Measured on five satellites' main, the second enumerator has no dot rule, so an undeclared top-level .foo is skipped by the canonical and walked by the validator — validated as nodes it does not contain — while the two declared sets are identical and the guard passes. That is the failure check-skip-sets.py's own docstring names: "a guard whose subject moved out from under it and that answers green has checked nothing, which is worse than the drift it exists to catch."

So a guard compares effective enumerations, never declarations:

MW_REPO_ROOT=$PWD python3 <platform>/.github/scripts/gen-manifests.py --list-packages

stdout carries only the package names, one per line, sorted — a caller diffs its own enumerator's output against that and needs no copy of either rule; the count goes to stderr so an empty answer can still be told from a broken one. The canonical's --self-test pins both directions over a fixture tree holding a .example-check/, a declared skip and two real packages.

The guard is the platform's, and it calls both enumerators. node-repo-validate.yml fetches .github/scripts/check-package-enumeration.py beside the canonical and runs it on every caller. The contract is one function: the caller's scripts/validate-repos.py exposes package_dirs(root) -> list[Path] — its skip set and the dot-directory rule, a pure function of the top-level names — and its own main() enumerates through it. The guard then compares what the two enumerators return, twice:

• on the checkout, name for name; and
• on a fixture holding every name either side declares, every top-level directory the checkout has, a probe dot-directory and a probe package — so a disagreement that needs a directory the tree does not happen to contain today (the dot rule, a skip name one side forgot) is red now rather than the day a tool writes one.

That second half is what the per-repo check-skip-sets.py could never do, and it found a live instance on the first run: MeshWeaver.Plugins skipped dist in both of its SKIP sets and not in the gen-manifests.config.json the canonical actually reads — equal declarations, a divergent verdict. A repo that adopts deletes its check-skip-sets.py; the platform guard supersedes it.

🚨 The ordering. A caller whose validate-repos.py has no package_dirs yet is NAMED (::warning::package enumeration NOT compared) and not failed — reddening it first would red every satellite's required validate context for a condition none of them can fix without their own PR, the fleet-wide-red shape a dated guard already produced here. Everything else is red: a missing or unloadable validate-repos.py, a package_dirs that raises or returns anything but a list, a main() that does not enumerate through package_dirs (checked statically — a helper added beside an untouched root.iterdir() walk would otherwise pass while the gate still disagreed), a missing config, any disagreement. The flip of the absent case to red is a change to the guard once every caller has adopted, never a date. Canonical first, repos adopt, guard tightens when it can only pass.

Adoption is one commit per repo — add the config, drop the vendored copy, give validate-repos.py its package_dirs(root), retire check-skip-sets.py, and pass centralized-gen-manifests: true to the lane. Before merging one, prove it moves nothing:

MW_REPO_ROOT=$PWD python3 <platform>/.github/scripts/gen-manifests.py --check
MW_REPO_ROOT=$PWD python3 <platform>/.github/scripts/gen-manifests.py --check-versions

Both must be green on the tree as committed — the canonical has to reproduce every lock the vendored copy wrote, or the swap republishes modules that did not change. Measured that way on 2026-09-07 across all six repos: identical verdicts everywhere, and Manufacturing gained the trunk witness (verified against their tags → verified against the published tags and the trunk).

Who writes the lock

A manifest.lock is DERIVED: its files map is a function of the package's tree, its moduleVersion a hash of that map, its version a function of the hash and the last release. Two places can write it, and a repo declares which one does in gen-manifests.config.json.

lockOwner: branch (the default, and the historical contract) — every commit carries locks that describe its own tree. A pull request runs the generator and commits the output; --check reds a stale lock; main re-derives the version in its finalize-versions step.

lockOwner: main — the lock is a MAIN artifact, and a pull request commits no lock change.

Why main exists: a lock conflict cannot be prevented while branches write locks

A lock's trailer — moduleVersion, sourceCommit, version — changes on every content change to its module, and its files lines are alphabetical neighbours (git conflicts on ADJACENT changed lines, not only on the same line). So two pull requests that touch one module — or one src/ project riding into many bundles — always conflict on its lock, and each merge to main turns every open pull request that touches the same module DIRTY. GitHub decides mergeability on its own servers, where no custom merge driver runs, so a .gitattributes merge= driver cannot prevent the state; it only helps whoever merges locally, after the fact. Measured on MeshWeaver.Plugins on 2026-09-27: of 21 open pull requests, 10 were conflicting, and every conflicting non-draft one conflicted on generated manifest.lock files and nothing else (one merge, #2457, turned seven DIRTY at once; #2448 went DIRTY four times in three hours). Each DIRTY cost a merge of main and a full CI restart on shared runners.

The only state in which a merge on main cannot conflict another pull request over a lock is one in which pull requests do not write locks. So:

--materialize derives the version from the committed lock alone — same patch when the content hash still matches it, +1 when it moved, .0 for a new series or a new module. That is derive_release with its trunk witness already on disk: a main-owned tree's committed lock IS the last settled claim it descends from, and no published tag outranks it (tags are cut from settled commits). Being pure is the point — every job of one run materializes independently and must arrive at the same bytes, which a derivation reading the live remote could not promise. --settle derives with the verified remote (both witnesses, as ever) and asserts that its numbers equal what --materialize gives from the committed lock whenever the trunk it derived against is the checkout itself — the property that makes a bundle named at pull-request time the bundle main publishes.

What the other checks do on a main-owned tree:

• --check — every committed lock is well-formed (identity, schema, a version, and a moduleVersion that is the hash of its own files — a hand edit or a textual merge of two locks fails), no tree would materialize a version BELOW its committed one, and, on a pull request, the lock diff is EMPTY. The base is MW_LOCK_BASE when set, else the merge ref's first parent (what actions/checkout gives a pull_request run); a pull-request run whose base cannot be read is RED, never "no base".
• --check-versions — checks every module whose committed lock describes the tree, and NAMES the modules it could not check because main has not settled them yet (their lock claims no version for this tree). --settle refuses to finish while any module is unsettled, so the claim that is made is always checked.
• --resolve — resolves a lock conflict by ADOPTING the trunk's lock (every one of them), so the branch leaves the merge carrying no lock change and can never conflict on one again.

🚨 A caller that declares lockOwner: main MUST settle FIRST and publish only what its own settle claimed. --materialize names a changed module patch+1 over the committed lock, so two merges that touch one module before settlement would otherwise claim the same number for different trees. The first job of every main run therefore opens or refreshes one reserved bot PR from the generated lock files; it never pushes to protected main. The validator grants this PR a narrow exception only when its author, branch, same-repository origin, base branch, changed paths, and generated contents all match, and its base is the current verified main tip. Every other PR that changes a lock stays red. If locks need settlement, that main run reports that it does not own the settled tree and publishes, seals, and tags nothing. After the bot PR passes the repository's ordinary required checks and merges, the resulting main run sees the settled locks and publishes exactly what --settle derives. MeshWeaver.Plugins' settle-locks job and its own output are the reference shape.

🚨 A run that withholds its publication must say so, or it becomes the next run's baseline. node-repo-publication-base.py narrows a push's selection to git log <baseline>..HEAD, where the baseline is the newest successful main push. An unsettled merge's run is successful and publishes nothing, so taken as the baseline it would narrow the settle merge's run to the lock-only diff and none of the merge's modules would ever publish. Such a run uploads a marker artifact and the caller passes --withheld-marker <name>; a marked run is walked past like a failed one, and the history union from the older baseline carries its changes into the run that does publish.

🚨 The merge commit on main carries the locks of the commit before it until the settlement PR lands. Everything in CI reads the materialized lock, so no bundle, seal or key sees the stale one; what reads main's committed tree directly — a GitSynced portal importing main unsealed — sees the new content under the old lock until settlement and treats that module as unchanged until then (ModuleSyncDecision). A failed settlement workflow is red on main, never silent.

Before you open the PR

On a main-owned repo, none of the generator steps below apply: commit no lock, and prove the diff carries none with MW_LOCK_BASE=origin/main python3 scripts/platform-script.py gen-manifests.py --check (the lock diff is taken against the merge base, so a branch that is merely behind is not charged with the locks main settled since).

python3 scripts/platform-script.py gen-manifests.py         # after ANY change to a package folder
                                           # OR to a src/ project a package bundles — both move the lock
python3 scripts/platform-script.py gen-manifests.py --check # what CI runs on your branch

platform-script.py resolves the platform's copy at the sha this repo's lanes are pinned to, so a local verdict is CI's verdict. A repo that has not adopted yet still runs python3 scripts/gen-manifests.py.

--check is a PR gate and is entirely local: it asserts your lock describes your tree. --check-versions is main-only — a branch is never asked to win a race against the trunk.

The question to ask before merging is not "is it green" but "will anyone receive it":

1. Did I change a package's node content? → the hash moves and the patch is derived, but you still run gen-manifests.py and commit its output. "Derived, not hand-edited" does not mean "generated for you": CI regenerates-and-commits only on main (finalize-versions), and on a branch it merely runs --check, which reds Validate node repos naming every stale module.
2. Did I change only src/ of a mixed package? → the same applies — editing src/ alone moves the lock of every package that bundles that project, often a dozen at once. Run the generator, then confirm manifest.lock actually moved: if it did not, the change reaches nobody.
3. Is this a feature or a break? → bump the MINOR or the MAJOR in index.json by hand.
4. Am I tempted to edit the patch, or to re-cut an existing tag? → no.

Related

Modules · MeshNode Versioning · Plugin Packaging · Deploying Plugin Changes · Plugin Registry · Plugin Update on Green Build · Deploying Across Platform Versions