Heal durable self-typed NodeType declaration rows at startup by rbuergi · Pull Request #2605 · Systemorph/MeshWeaver

rbuergi · 2026-08-28T12:03:12Z

Fixes #2425. Fixes #2506.

The defect that survived two fixes

UserIdentityCache logged As<User> for User: value is NodeTypeDefinition (MeshWeaver.Graph), not convertible ~600 times/hour on memex.systemorph.com (and ~70/4h on memex.meshweaver.cloud) — on image ci.6096, which already carried BOTH prior fixes:

A NodeType declaration declares itself a NodeType, never the type it declares #2245 retyped the three self-typed built-in declarations (User, VUser, Partition) in their STATIC registrations (NodeType = "NodeType"), and
Refuse a NodeType declaration write that claims to be its own instance #2378 added NodeTypeDeclarationSelfTypingValidator, refusing any NEW write that re-introduces the collision.

Neither touches a row that was persisted self-typed before they landed. Verified live: search nodeType:User on prod still returns {path: "User", nodeType: "User", version: 2, lastModified: 2026-06-02} — the durable declaration fossil, answering the user-directory query beside real accounts. Reads are bad-data tolerant by design, and the row is unreachable through the serve path (the static claim shadows it — the #2534 mechanism), so "until it is next written" was never: the defect had moved from the code into the data, and no code-only guard could end it.

The fix — heal the data, once, at startup

SelfTypedDeclarationDurableRepair (hosted service, registered by AddGraph beside the validator) runs once at startup, at the storage seam where LegacyUserPartitionRepair already writes (the only seam that can reach a static-shadowed row):

one batched IStorageAdapter.ReadMany over the statically-registered declaration paths (the same multi-path probe the URL resolver runs constantly — absent partitions answer "absent", never fault: the PG routing adapter's reads catch 42P01 by contract);
rewrites exactly the rows matching the write guard's own predicate — extracted as NodeTypeDeclarationSelfTypingValidator.IsSelfTypedDeclaration (public, shared), so what the guard refuses and what the repair heals can never drift apart;
the rewrite is A NodeType declaration declares itself a NodeType, never the type it declares #2245's correction applied to the row: NodeType = "NodeType", version minted forward, content/identity untouched;
everything else is left alone — already-correct declarations, real user instances, package roots typed as an unrelated type (the UWDeepfield shape). A healthy store reads one batch and writes nothing;
fire-and-forget and failure-tolerant like InstalledPackageRepairService: a skipped pass heals on the next boot; concurrent replicas write the same value under the monotonic-version guard.

The adapter change feed fires on the heal, so live nodeType:User subscriptions (UserIdentityCache's directory query) converge without a restart.

Repro test — red on main for the right reason

SelfTypedDeclarationDurableRepairTest boots a mesh over a store already carrying the fossils (seeded straight into the adapter before boot — exactly how production got them):

FossilSelfTypedDeclarationRows_AreRetypedAtStartup — the User and VUser fossils flip to NodeType = "NodeType" (content preserved, version forward); an already-correct Partition declaration row and a real user instance are untouched.
TheUserDirectory_NoLongerReturnsTheFossilDeclaration — UserIdentityCache.DirectoryQuery (verbatim) returns the real account and NOT the declaration; every returned row reads as a User.

On main both fail with TimeoutException waiting for a heal that never happens (Failed: 2, Passed: 0); with the fix, Passed: 2 in <1s.

Verification

MeshWeaver.Graph and MeshWeaver.Hosting.Monolith.Test build clean -c Release -warnaserror.
Adjacent guards stay green: NodeTypeDeclarationSelfTypingValidatorTest (9 — the predicate extraction is behavior-preserving), NodeTypeDeclarationSelfTypingTest (2), WhatsNewEntryIntegrityTest.
What's New entry included (Category: Fix).

🤖 Generated with Claude Code

The User/VUser/Partition declarations shipped self-typed and were PERSISTED that way on live stores. #2245 fixed the static registrations and #2378 refuses any new write carrying the collision — but a row already persisted with nodeType:"User" keeps answering every nodeType:User query beside the real accounts, forever: reads are bad-data tolerant by design, and the serve path cannot reach the row (the static claim shadows it, #2534). On production that was ~600 UserIdentityCache "As<User> for User: value is NodeTypeDefinition" errors per hour on an image that already carried both fixes (#2425, #2506) — the defect had moved from the code into the data. SelfTypedDeclarationDurableRepair (a hosted service registered by AddGraph) retypes such rows once at startup, at the storage seam where LegacyUserPartitionRepair already writes: one batched ReadMany over the statically-registered declaration paths, then a rewrite (NodeType = "NodeType", version minted forward) of exactly the rows matching the write guard's own predicate — extracted as NodeTypeDeclarationSelfTypingValidator.IsSelfTypedDeclaration so the guard and the repair can never drift apart. Already-correct declarations, real instances and package roots typed as an unrelated type are untouched, so a healthy store reads one batch and writes nothing. The adapter change feed fires on the heal, so live nodeType: query subscriptions (UserIdentityCache's directory) converge without a restart. Repro pinned by SelfTypedDeclarationDurableRepairTest: a mesh booted over a store already carrying the fossil rows — red on main (the rows never heal; the user directory keeps returning the declaration), green with the repair. Fixes #2425. Fixes #2506. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Copilot

Pull request overview

Adds a startup-time durability repair in MeshWeaver.Graph to retroactively fix persisted NodeType declaration rows that were historically self-typed (e.g., durable User declaration with nodeType:"User"), which caused nodeType:User queries (notably UserIdentityCache.DirectoryQuery) to return a declaration row alongside real user instances.

Changes:

Introduces SelfTypedDeclarationDurableRepair as an IHostedService to batch-read statically-registered declaration paths and rewrite only rows matching NodeTypeDeclarationSelfTypingValidator.IsSelfTypedDeclaration.
Extracts and publishes the self-typing predicate (IsSelfTypedDeclaration) so the write-guard and the durable repair share one definition.
Adds a monolith integration test that seeds “fossil” rows directly into the storage adapter and verifies both the durable retype and the corrected user directory behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
test/MeshWeaver.Hosting.Monolith.Test/SelfTypedDeclarationDurableRepairTest.cs	Seeds fossil rows into an in-memory adapter pre-boot and asserts startup healing + user directory exclusion.
src/MeshWeaver.Graph/Security/SelfTypedDeclarationDurableRepair.cs	New hosted service that repairs persisted self-typed declaration rows via storage-layer reads/writes at startup.
src/MeshWeaver.Graph/Security/NodeTypeDeclarationSelfTypingValidator.cs	Refactors to use/expose a shared predicate (`IsSelfTypedDeclaration`) used by both guard and repair.
src/MeshWeaver.Graph/Configuration/GraphConfigurationExtensions.cs	Registers the new hosted service alongside existing graph validators.
src/MeshWeaver.Documentation/Data/WhatsNew/2026-08-28-user-directory-declaration-repair.md	Adds a “What’s New” entry documenting the user-directory repair behavior.

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

github-actions · 2026-08-28T12:15:16Z