docs: a declined bundle risks stale TYPES, not just a slower boot (Plugins#1585)

[rbuergi]

Opened as a draft on purpose — draft is the documented auto-arm opt-out, so nothing can merge this while the finding is reviewed.

Why

Re-measuring MeshWeaver.Plugins#1585 this morning showed the symptom is already resolved, and that the issue's own conclusion is wrong in a way worth recording.

#1585 reported that ModelDefinition served on memex lacked reasoningEffort (Plugins#1556) and that ThreadMessage lacked timing (Plugins#1552), and concluded (comment, 03:16Z) that "the registry itself serves the stale bytes" for AI@1.5.1.

The instance's own health falsifies that:

bundle_adoption: Degraded — 25 adoption attempt(s), 0 assembly/assemblies adopted, 25 MISS(es) —
content the registry was meant to serve is compiled here instead: AI: FrameworkDeclined
(built against framework s72c27afab89c1007…, live framework is s546f29f90e235e61…)

The registry's AI bundle was never adopted, so its bytes were never in play. What served was the previously resolved build, kept alive by the same-MAJOR stale-but-serving rule #3844 introduced the evening before (in this portal's core, 2287decb) — a moved source fingerprint is deliberately not a refusal. That is why a Store RefreshModules re-land and two restarts each reloaded the identical generation and changed nothing, and why the fix was a new {package}@{version} shelf entry (AI/index.json 1.5 → 1.6, no source change, Plugins#1586) for which no previously adopted build existed.

The layer matters: the model code was never at fault. src/MeshWeaver.AI/ModelDefinition.cs on Plugins origin/main hashes to 89fd0a2264…, byte-identical to what the portal's install record claims, and declares public string? ReasoningEffort { get; init; } at line 177.

What changed

One section on Module Adoption Policy. The page already treats no adopted bundle as a cost paid in boot time ("the content compiles in the mesh… a missing bake is a cost, not a reason to hold a roll"). It adds the second consequence measured here — the types served can lag the installed source with nothing red on any surface — plus:

• the three consequences (installed-and-current ≠ running these types; re-landing is not re-building; a version bump is a delivery lever and the discriminating experiment);
• the discriminator, bundle_adoption on /health, because from the consumer a stale adopted build and a stale registry shelf are identical — same [ModuleLoad] line, same generation, same mvid, and [ModuleLoad] never names the commit a bundle was built from.

Documentation only. No code, no public surface, no in-mesh (Source/*.cs) node sources.

Verification and control

MeshWeaver.Documentation.Test, Release + -warnaserror, one project per invocation: 0 Warning(s), 0 Error(s); full suite 368/368 passed.

Control (the gate is live, not vacuous): with ../ExecuteTimeInterlock changed to ../ExecuteTimeInterlockZZZ and the project REBUILT (the doc is an embedded asset, so --no-build would have given a false verdict), DocumentationLinkIntegrityTest fails, exit 1, naming it:

Doc/Architecture/ModuleAdoptionPolicy: (../ExecuteTimeInterlockZZZ) — resolves to
/Doc/Architecture/ExecuteTimeInterlockZZZ, which does not exist, but found 1 item(s).
Failed!  - Failed: 1, Passed: 0

Restored and rebuilt, it passes. The rebuild also confirms the embedded .md really does refresh, so the passing run is a real pass.

Not done here

The residual class defect #1585 asks for — [ModuleLoad] naming the assembly a NodeType's content type actually resolves to, and a bundle manifest recording its built-from commit — is real and unaddressed, but it is a core change in the #3583/#3732 delivery area rather than anything in the model, and it deserves its own scoped issue rather than riding a docs commit.

Pairs-with: none — documentation only; no public type or member is removed or renamed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01S25PJZbVeCbkWhCfMub9P7

[Copilot]

🟡 Changes recommended

Final review comments request wording, scope, grammar, and documentation-convention updates.

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

Pull request overview

This documentation-only PR explains how declined bundles can leave stale types serving and how to diagnose this via bundle_adoption.

Changes:

• Documents the measured stale-type incident and its consequences.
• Distinguishes re-landing from version bumps.
• Adds /health diagnostic guidance.

File summaries

File	Summary
src/MeshWeaver.Documentation/Data/Architecture/ModuleAdoptionPolicy.md	Adds stale-type adoption guidance and operational diagnostics.

Review details

Suppressed comments (3)

src/MeshWeaver.Documentation/Data/Architecture/ModuleAdoptionPolicy.md:110

• FrameworkDeclined is emitted by PluginBundleClient.Adopt for the index-level prebuilt NodeType-content lane. The separate AdoptModule path uses per-bundle metadata and is not represented by this ledger, so this observation rules out the registry's prebuilt-content bytes for these attempts, not necessarily all AI module bytes; narrow the claim accordingly.

The registry's bytes were therefore never in play. What served was the previously resolved build,

src/MeshWeaver.Documentation/Data/Architecture/ModuleAdoptionPolicy.md:135

• BundleAdoptionLedger is an append-only, process-scoped history, so one FrameworkDeclined outcome describes only that attempt and does not prove that the registry's bytes were never adopted earlier. The stronger conclusion in this incident comes from the aggregate zero-adopted result above; keep that scope explicit before directing an operator toward the shelf.

`bundle_adoption` on `/health` — `FrameworkDeclined` means the registry's copy was never adopted,
so a fix aimed at the shelf would be aimed at bytes this instance never ran.

src/MeshWeaver.Documentation/Data/Architecture/ModuleAdoptionPolicy.md:89

• This page is embedded and served under /Doc/Architecture, so the new operational guidance is user-visible. The repository convention requires a dated WhatsNew node for user-visible changes, but this PR currently changes only the architecture page; add that entry or explicitly justify why this documentation is internal-only.

## A declined bundle risks stale TYPES, not just a slower boot

• Files reviewed: 1/1 changed files
• Comments generated: 2
• Review effort level: Lite

---

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

[github-actions]

Test Results (shard 0)

254 tests   254 ✅  2m 13s ⏱️
  1 suites    0 💤
  1 files      0 ❌

Results for commit 054f4e5.

[github-actions]

Test Results (shard 1)

496 tests   496 ✅  43s ⏱️
  1 suites    0 💤
  1 files      0 ❌

Results for commit 054f4e5.

[github-actions]

Test Results (shard 3)

389 tests   389 ✅  1m 1s ⏱️
  2 suites    0 💤
  2 files      0 ❌

Results for commit 054f4e5.

[github-actions]

Test Results (shard 4)

1 885 tests   1 885 ✅  3m 18s ⏱️
    4 suites      0 💤
    4 files        0 ❌

Results for commit 054f4e5.

[github-actions]

Test Results (shard 2)

1 213 tests   1 211 ✅  3m 42s ⏱️
    3 suites      2 💤
    3 files        0 ❌

Results for commit 054f4e5.

[github-actions]

Test Results (shard 5)

    6 files      6 suites   5m 0s ⏱️
2 580 tests 2 388 ✅ 192 💤 0 ❌
2 584 runs  2 392 ✅ 192 💤 0 ❌

Results for commit 054f4e5.

[github-actions]

Test Results

   17 files     17 suites   15m 59s ⏱️
6 817 tests 6 623 ✅ 194 💤 0 ❌
6 821 runs  6 627 ✅ 194 💤 0 ❌

Results for commit 054f4e5.