[rbuergi]

Maintainer directive, 2026-09-17, verbatim across three messages:

"the grain keeps serving old state until we send dispose request" / "write this prominently in all repos" / "in pull request skill etc"

The mechanism, established from the code before a word was written

A per-node hub resolves its HubConfiguration once, while it is activating, and is then pinned by address. src/MeshWeaver.Graph/Configuration/MeshNodeHubFactory.cs:

"The binding above is made ONCE and then PINNED by address: routing short-circuits on GetHostedHub for an already-hosted address and never resolves the path again, so nothing re-reads the NodeType for the hub's whole lifetime."

So a merge, a seal, an image, a roll and even a pod restart change what the next activation would load, while an address already up keeps answering from what it bound — with no error, no log line and nothing to grep. That is the missing half of "merged and rolled is not loaded", of a NodeType recompiled while the hub still serves the previous assembly, and of a fix that is live in the image and invisible in the running mesh.

Two halves of the rule are load-bearing and both are stated:

• Content is live. stream.Update and node CRUD route to the owning activation and MeshDataSource holds a long-standing own-node subscription — activation only seeds the workspace. Nobody should ever recycle to make a write visible; if they do, the write is the bug.
• A dispose makes the activation RE-READ; it does not change what the re-read FINDS. The assembly store is keyed (nodeTypePath, LastCompiledVersion), a recompile of an already-Ok type does not rewrite its node, and the release request the recycle verb stamps adopts before it compiles (Modules:VersionStrictness defaults to Family) — so the same local copy, or the same prebuilt bundle sealed against another platform surface, lands the identical bytes again. Measured on memex over 30+ minutes and six recycles (A portal can serve STALE compiled code while reporting Ok/compiled — recycles, forced compile and the stale-build banner are all inert #2471), which is exactly why a same-path build mismatch is reported and deliberately NOT offered as a recycle. The remedy is a rebake and republish for this framework identity, or a forced recompile of the live source.

What lands here

• AGENTS.md — a new ABSOLUTE section, wrapped as the shared-rule block dispose-to-serve-new-state and registered in .github/shared-rules.json with required-in naming only the hub. That is step 1 of 3 per SharedRuleBlocks.md: the id becomes known and the gate is green on its own, so no spoke marker is ever undeclared. Step 2 is the six spoke PRs; step 3 widens required-in to all seven.
• Doc/Architecture/StaleStateUntilRecycle — the mechanism in one citable place, which it did not have: it was scattered over a comment in MeshNodeHubFactory, a class doc in NodeTypeRebindWatcher, a type doc in ServedBuildIdentity, an enum doc in BuildProvenance and four sections of a 2,660-line compilation page. It covers what an activation pins vs what stays live; the one framework surface (hub.RecycleNode — cold, the wait is a READ not a poll, install-lease deferral, the caller must outlive the target); the operator verb and the fact that the Compile button posts no DisposeRequest; the three posting rules (off-router per RecycleCore posts DisposeRequest from the root mesh hub instead of the NodeOperationIssuingHub seam #4463, the root mesh hub's outright refusal, carry a Reason per A package root is disposed while its own install is in flight (CD 7950): the creates' write-through streams lose their owner, no reply is ever sent, and the install runs out its bound — neither #3501 nor #3505 covers it #3510); the four automatic recyclers and the one config key (Modules:AutoRecycleOnStaleBuild, default OFF, so a portal is a mixture of old and new assemblies for as long as viewers do not click); and the four things a recycle does not do.
• The skills — pullrequest first, as the directive named it ("…and MERGED is not LIVE", with the four-step verification and the PR-body obligation to name addresses a deploy must recycle), plus deployment, release, mesh-data and debug.
• Cross-links from HubDisposalModel and NodeTypeCompilation, a topic-map line, and a What's New entry for the new page.

Not in this change, deliberately

Systemorph/MeshWeaver.Crm is not added to the register: it is absent from repos, so the gate never reads it, and registering it needs the read-only fleet-reader App installed there and Crm carrying every block already registered — an unreadable repo is RED here by design. Crm will carry this block's text anyway, so a later registration is a one-line change rather than a rollout. The register entry says so.

#4464 is not in this repo (git log --all --grep=4464 finds nothing about it); the off-router change is #4463, merged as #4477.

Verification

• check-shared-rules.py --self-test — 18 cases, all correct.
• check-shared-rules.py --local across all seven repos with the new block registered — ✅ All 5 shared rule block(s) are identical everywhere they are carried, across 7 repos.
• dotnet build test/MeshWeaver.Documentation.Test -c Release -warnaserror — 0 Error(s), then the doc guards on that build: 12 tests, 12 passed, 0 failed (DocumentationLinkIntegrityTest, ArchitectureTopicMapTest, WhatsNewEntryIntegrityTest, NoConflictMarkersGuard, MigrationWorkloadModelGuard).

Pairs-with: none — documentation and agent instructions only; no src/ surface changes.

🤖 Generated with Claude Code

[github-actions]

Test Results (shard 3)

429 tests  ±0   429 ✅ ±0   1m 2s ⏱️ +3s
  2 suites ±0     0 💤 ±0 
  2 files   ±0     0 ❌ ±0 

Results for commit 176734a. ± Comparison against base commit cc59e37.

♻️ This comment has been updated with latest results.

[github-actions]

Test Results (shard 0)

264 tests  ±0   264 ✅ ±0   2m 42s ⏱️ +12s
  1 suites ±0     0 💤 ±0 
  1 files   ±0     0 ❌ ±0 

Results for commit 176734a. ± Comparison against base commit cc59e37.

♻️ This comment has been updated with latest results.

[github-actions]

Test Results (shard 1)

533 tests  ±0   533 ✅ ±0   1m 0s ⏱️ -2s
  1 suites ±0     0 💤 ±0 
  1 files   ±0     0 ❌ ±0 

Results for commit 176734a. ± Comparison against base commit cc59e37.

♻️ This comment has been updated with latest results.

[Copilot]

🟡 Changes recommended

Multiple unresolved accuracy issues remain in the operational and architecture guidance.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR documents stale per-node activation state, recycle behavior, and deployment verification guidance.

Changes:

• Adds the canonical architecture page and What's New entry.
• Updates agent, release, deployment, debugging, pull-request, and mesh-data guidance.
• Registers the shared rule for staged rollout.

File summaries

File	Change	Final review findings
src/MeshWeaver.Documentation/Data/WhatsNew/2026-09-17-why-a-page-can-keep-showing-the-old-version-after-an-update.md	Adds user-facing stale-state guidance.	Nit (1 vote): Qualify Recycle as a remedy because same-path build mismatches may persist.
src/MeshWeaver.Documentation/Data/Architecture/StaleStateUntilRecycle.md	Adds the canonical activation and recycle model.	Nit (2 votes): Qualify pod-restart behavior. Nit (2 votes): Qualify RecycleNode read guarantees for root-hub callers. Nit (1 vote): Limit release stamping and account for prebuilt adoption. Nit (1 vote): Correct the initial-load echo explanation. Nit (2 votes): Correct SettleRetypedRoot routing behavior.
src/MeshWeaver.Documentation/Data/Architecture/NodeTypeCompilation.md	Adds a cross-link to stale-state guidance.	—
src/MeshWeaver.Documentation/Data/Architecture/HubDisposalModel.md	Adds lifecycle cross-links.	—
src/MeshWeaver.Documentation/Data/Architecture.md	Adds the architecture topic-map entry.	—
AGENTS.md	Adds the shared stale-state rule.	Nit (2 votes): Qualify pod-restart behavior. Nit (1 vote): Distinguish sender/origin from root-target refusal. Nit (2 votes): Correct forced release compilation behavior. Nit (3 votes): Limit operator recycling scope and account for prebuilt adoption.
.github/shared-rules.json	Registers the shared rule for staged rollout.	—
.claude/skills/release/SKILL.md	Adds release verification guidance.	Nit (3 votes): Account for the effective AKS auto-recycle setting. Nit (1 vote): Distinguish operator recycle from dispose-only recycling.
.claude/skills/pullrequest/SKILL.md	Adds post-merge live verification steps.	Nit (2 votes): Qualify pod-restart behavior. Nit (2 votes): Correct operator recycle compilation behavior.
.claude/skills/mesh-data/SKILL.md	Clarifies content and binding freshness.	Nit (3 votes): Limit release stamping to NodeType targets and account for prebuilt adoption.
.claude/skills/deployment/SKILL.md	Adds deployment verification guidance.	Nit (3 votes): Account for the effective AKS auto-recycle setting. Nit (2 votes): Distinguish operator recycle from dispose-only recycling.
.claude/skills/debug/SKILL.md	Adds stale-activation debugging guidance.	Nit (2 votes): Qualify pod-restart behavior. Nit (2 votes): Correct operator recycle compilation behavior. Nit (2 votes): Qualify the isolated-test exception.

Review details

Suppressed comments (7)

.claude/skills/release/SKILL.md:297

• This says any recycle leaves the bytes unchanged, but the operator recycle verb stamps a forced NodeType release and compiles the live source; that behavior is different from the dispose-only hub.RecycleNode extension. Clarify which surface the release procedure is prescribing.

name them. A recycle makes the activation re-read, it does not change what the re-read finds — so a
second one that answers the same is a delivery question, not an activation one. Full reference:

AGENTS.md:70

• HandleDispose refuses only when the target hub has Address.Type == "mesh"; it does not refuse a DisposeRequest posted by the root mesh hub to a node. #4463 was exactly that accepted delivery, which is why the off-router hop is required. Reword this to separate sender/origin from root-target refusal.

**Tearing the activation down is the ONLY thing that makes it re-read**, and the next access re-creates the hub from its node — a fresh NodeType resolution, a fresh compile-or-adopt, fresh data loads. In code that is `hub.RecycleNode(path, reason: "…")`, the ONE framework surface: cold (it posts on Subscribe, so an unsubscribed chain tears nothing down), the wait is the framework's own READ rather than a poll or a sleep, and it defers while a package install holds that root. As an operator or agent it is the `recycle` verb — the MCP tool, a node's **Recycle** menu entry, `mw recycle <path>` — which also checks `Update` permission and stamps a release request BEFORE the dispose so the fresh activation recompiles instead of re-binding. (The **Compile** button writes that same release-request stamp and posts NO `DisposeRequest`: it rebuilds the type, it does not re-bind a live instance.) 🚨 The caller's hub must OUTLIVE the target: a dying hub cannot deliver its own last frame, so never recycle from the hub being recycled. 🚨 Issue it off the router (`hub.NodeOperationIssuingHub()` — #4463), never off the DI-injected root mesh hub, which `HandleDispose` refuses outright because disposing it over the bus wedged every node operation until the process restarted. 🚨 ALWAYS carry a `Reason` — an omitted one prints as *"reason not stated by the caller"*, and that blank cost #3510 six occurrences and four bake seals.

src/MeshWeaver.Documentation/Data/Architecture/StaleStateUntilRecycle.md:152

• RequestedReleaseForce is the opposite of what this says. MeshOperations.RecycleCore writes it, and the compile watcher then skips on-demand prebuilt adoption and dispatches a live-source compile (NodeTypeCompilationHelpers.cs:382-402). The documented same-bundle outcome is therefore not the behavior of the operator recycle; it applies only to a dispose-only recycle.

**And the recompile can re-choose the same bundle.** The release request the `recycle` verb stamps
runs *adopt-before-compile*: the deployment's prebuilt bundle sources get one bounded chance to
supply the assembly first, and an adopted type then satisfies its release request without Roslyn
ever running. `Modules:VersionStrictness` decides what counts as a candidate, and its default is
**`Family`** — a bundle sealed for another identity of the same major line is adopted when its

src/MeshWeaver.Documentation/Data/Architecture/StaleStateUntilRecycle.md:92

• RecycleLayoutArea explicitly drives the node menu through the circuit's hub.RecycleNode(path) flow, and that extension only posts DisposeRequest/waits; it does not stamp a release. MeshOperations.RecycleCore stamps only when IsNodeTypeNode(curr) is true, so an instance/menu recycle does not recompile its NodeType. This paragraph conflates the surfaces and promises a compile that does not happen.

The **`recycle` verb** (`MeshOperations.Recycle`) backs the `recycle` MCP tool, a node's **Recycle**
menu entry and `mw recycle <path>`. It is more than a dispose: it checks `Update` permission on the
target (a refusal is an *answer* rendered in the operation's envelope, not a fault), waits on the
same install lease, **stamps a release request on the NodeType before the dispose** — so the fresh
activation recompiles rather than re-binding — and broadcasts a cache invalidation on the change

src/MeshWeaver.Documentation/Data/Architecture/StaleStateUntilRecycle.md:95

• MeshOperations.Recycle only stamps a release request when the target node is itself a NodeType definition (IsNodeTypeNode); recycling an ordinary instance/page does not stamp its NodeType. Also, the release path can adopt a compatible prebuilt bundle without running Roslyn. This description overstates both the scope and effect of the operation.

same install lease, **stamps a release request on the NodeType before the dispose** — so the fresh
activation recompiles rather than re-binding — and broadcasts a cache invalidation on the change
feed. The stamp is *sequenced* before the dispose, never merely issued alongside it: when the dispose
won that race, the reactivated hub re-ran its source query against a half-invalidated state, matched
zero `Code` nodes and recompiled the **pre-fix** source.

src/MeshWeaver.Documentation/Data/Architecture/StaleStateUntilRecycle.md:176

• MeshDataSource deliberately suppresses the initial-load echo: a node just loaded from persistence is already durable and must not be written back. Thus the reason a recycle clears no data is a fresh read/no delete, not that the own-node source re-saves the loaded node; this sentence currently describes the opposite behavior.

- **It clears no data.** Reactivation re-loads from the store and the own-node source re-saves what
  it loaded, so a recycle is not a delete: a node removed underneath the mesh comes back on the next
  activation, and clearing in-memory-only state takes a process restart.

src/MeshWeaver.Documentation/Data/WhatsNew/2026-09-17-why-a-page-can-keep-showing-the-old-version-after-an-update.md:21

• This presents Recycle as a universal remedy, but the page itself documents same-path build mismatches where a fresh activation finds the same bytes. Qualify the user-facing guidance so readers do not repeatedly recycle a node when the delivery/build artifact—not the activation—is stale.

answering exactly as it did before, with nothing anywhere reporting a problem. The remedy is the
**Recycle** action on that node: it stops the worker, and the next visit starts a fresh one that
reads everything again.

• Files reviewed: 12/12 changed files
• Comments generated: 15
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[rbuergi]

Valid, and it was the worst error in the change — thanks. Confirmed: a restart tears down every activation the pod hosts, so those addresses re-activate and re-read on next access, and a roll does the same for the pods it replaces. The claim now reads "every change a portal absorbs WHILE IT KEEPS RUNNING", with an explicit note that a restart or a roll is NOT the gap — what a roll leaves open is only what the FRESH activation then chooses, plus what is pinned at process start (the store modules). Fixed in AGENTS.md, StaleStateUntilRecycle.md (which now carries the restart case as its own 🚨 paragraph), and the pullrequest, deployment, release and debug skills.

[rbuergi]

Valid, and I had it backwards. Verified in code: MeshOperations.WithReleaseRequest stamps RequestedReleaseAt AND RequestedReleaseForce = true, and NodeTypeCompilationHelpers short-circuits on exactly that flag — "A FORCE MEANS BUILD THE LIVE SOURCE, NOT SERVE ME WHATEVER A BUNDLE STILL RESOLVES" (#2818, which exists because a force used to re-adopt the very bytes the operator was replacing, #2813). So the operator recycle of a NodeType is the rebuild-from-source remedy, not a re-adoption. The same-bytes text is now scoped to (a) a dispose-only recycle, which compiles nothing and re-binds the same store key, and (b) an UNFORCED trigger or a Modules:RequirePrebuilt mesh. Fixed everywhere it was copied.

[rbuergi]

Valid — the blanket exception was wrong and TestStateIsolation.md says so directly: with a shared TestCluster per xUnit collection "the grain caches its config, Test B activates a different node at the same path, reads stale state from Test A". The debug skill now says a test is NOT automatically exempt — a fixture that builds and tears down its own mesh is, a shared one is not — and links TestStateIsolation.md. The Architecture page carries the same qualification in its pinning section.

[rbuergi]

Valid — I quoted the code default as if it were the fleet default. Verified: PrebuiltAdoptionPolicy-side the runtime default is off, and deploy/aks/values.aks.yaml:342 sets Modules__AutoRecycleOnStaleBuild: "true" fleet-wide (deploy/helm .../deployment.yaml also calls convergence "on fleet-wide"). The text now states BOTH and tells the reader to read the EFFECTIVE value, keeping the off-case consequence (banner only, viewers must click) separate from the configured-true case, and notes that neither setting fires for a same-path byte change.

[rbuergi]

Valid, and I had it backwards. Verified in code: MeshOperations.WithReleaseRequest stamps RequestedReleaseAt AND RequestedReleaseForce = true, and NodeTypeCompilationHelpers short-circuits on exactly that flag — "A FORCE MEANS BUILD THE LIVE SOURCE, NOT SERVE ME WHATEVER A BUNDLE STILL RESOLVES" (#2818, which exists because a force used to re-adopt the very bytes the operator was replacing, #2813). So the operator recycle of a NodeType is the rebuild-from-source remedy, not a re-adoption. The same-bytes text is now scoped to (a) a dispose-only recycle, which compiles nothing and re-binds the same store key, and (b) an UNFORCED trigger or a Modules:RequirePrebuilt mesh. Fixed everywhere it was copied.

[rbuergi]

Valid. MeshOperations.RecycleCore stamps through Update(curr => IsNodeTypeNode(curr) ? WithReleaseRequest(curr, ...) : curr), so an ordinary page or instance is a plain teardown that recompiles nothing. The text now says "only when the target is a NodeType node" and states that recycling an ordinary node stamps nothing. Combined with the RequestedReleaseForce correction above: on a NodeType the verb forces a live-source compile; on anything else it is dispose-only.

[rbuergi]

Valid, and I had it backwards. Verified in code: MeshOperations.WithReleaseRequest stamps RequestedReleaseAt AND RequestedReleaseForce = true, and NodeTypeCompilationHelpers short-circuits on exactly that flag — "A FORCE MEANS BUILD THE LIVE SOURCE, NOT SERVE ME WHATEVER A BUNDLE STILL RESOLVES" (#2818, which exists because a force used to re-adopt the very bytes the operator was replacing, #2813). So the operator recycle of a NodeType is the rebuild-from-source remedy, not a re-adoption. The same-bytes text is now scoped to (a) a dispose-only recycle, which compiles nothing and re-binds the same store key, and (b) an UNFORCED trigger or a Modules:RequirePrebuilt mesh. Fixed everywhere it was copied.

[rbuergi]

Valid, and it was the worst error in the change — thanks. Confirmed: a restart tears down every activation the pod hosts, so those addresses re-activate and re-read on next access, and a roll does the same for the pods it replaces. The claim now reads "every change a portal absorbs WHILE IT KEEPS RUNNING", with an explicit note that a restart or a roll is NOT the gap — what a roll leaves open is only what the FRESH activation then chooses, plus what is pinned at process start (the store modules). Fixed in AGENTS.md, StaleStateUntilRecycle.md (which now carries the restart case as its own 🚨 paragraph), and the pullrequest, deployment, release and debug skills.

[rbuergi]

Valid. HubRecycleExtensions states the exception itself: from the ROOT hub the dispose and the read leave different off-router hubs (portal/nodeops-* and portal/reads-*), whose action blocks are independent, so the read can overtake the teardown and be answered by the still-live activation. The guarantee is now scoped to "every caller this class documents", with the root-hub case written out as the one documented exception — and a one-line form of it is in the AGENTS.md block, since that is where a reader decides which hub to call from.

[rbuergi]

Valid. PackageInstaller.SettleRetypedRoot posts via hub.NodeOperationIssuingHub() at the package ROOT and then waits for it to answer, so it is a routed teardown, not a self-post; only the rebind watcher, the overlay self-heal and the stale-build convergence post to their own instance hub. The page now says "the first three post to their own instance hub" and names SettleRetypedRoot as the exception, and the router-exception sentence no longer claims all four are self-directed.

[github-actions]

Test Results (shard 4)

    3 files  ±0      3 suites  ±0   5m 39s ⏱️ -19s
2 341 tests ±0  2 341 ✅ ±0  0 💤 ±0  0 ❌ ±0 
2 342 runs  ±0  2 342 ✅ ±0  0 💤 ±0  0 ❌ ±0 

Results for commit 176734a. ± Comparison against base commit cc59e37.

♻️ This comment has been updated with latest results.

[github-actions]

Test Results (shard 2)

1 496 tests  ±0   1 494 ✅ ±0   7m 33s ⏱️ -6s
    4 suites ±0       2 💤 ±0 
    4 files   ±0       0 ❌ ±0 

Results for commit 176734a. ± Comparison against base commit cc59e37.

♻️ This comment has been updated with latest results.

[github-actions]

Test Results (shard 5)

    6 files  ±0      6 suites  ±0   11m 23s ⏱️ -6s
3 199 tests +5  3 007 ✅ +5  192 💤 ±0  0 ❌ ±0 
3 203 runs  +5  3 011 ✅ +5  192 💤 ±0  0 ❌ ±0 

Results for commit 176734a. ± Comparison against base commit cc59e37.

[github-actions]

Test Results

   17 files  ±0     17 suites  ±0   29m 23s ⏱️ -16s
8 262 tests +5  8 068 ✅ +5  194 💤 ±0  0 ❌ ±0 
8 267 runs  +5  8 073 ✅ +5  194 💤 ±0  0 ❌ ±0 

Results for commit 176734a. ± Comparison against base commit cc59e37.