Phase 558: internal whiteboard annotation store contract skeleton

[ExplodingUFO]

Summary

• Adds an internal Core-only whiteboard annotation-store contract skeleton for metadata, identities, primitive references, payloads, records, snapshots, migration metadata, and a persistence-neutral boundary.
• Adds focused contract tests proving the skeleton stays internal, public-API-free, GraphDocument-free, and neutral to persistence/export/screenshot/renderer/pointer behavior.
• Updates EN/ZH React Flow parity docs and docs tests to record Phase 558 after the Phase 557 contract gate.

Stack

• Base: docs/phase-557-whiteboard-annotation-store-contract / PR Phase 557: record whiteboard annotation store contract gate #238.
• Bead: avalonia-node-map-84u.
• GitHub issue: Phase 558: internal whiteboard annotation store contract skeleton #239
• Closes Phase 558: internal whiteboard annotation store contract skeleton #239
• This PR is blocked until Phase 557 and the lower whiteboard stack land.

Verification

• RED: focused contract test failed to compile before the boundary/snapshot types existed.
• WhiteboardAnnotationStoreContractTests: 2/2 pass.
• Focused Phase 558 roadmap-doc test: 1/1 pass.
• Whiteboard-filtered AsterGraph.Editor.Tests: 26/26 pass.
• ReactFlowParityRoadmapDocsTests: 58/58 pass.
• Full AsterGraph.Editor.Tests: 884/884 pass.
• Full AsterGraph.Demo.Tests: 303/303 pass.
• Release net9.0 public API validation: PUBLIC_API_SURFACE_OK:4292, PUBLIC_API_SCOPE_OK:AsterGraph.Abstractions,AsterGraph.Core,AsterGraph.Editor,AsterGraph.Avalonia, PUBLIC_API_DIFF_GATE_OK:True.
• git diff --check: clean except existing CRLF notices.

[ExplodingUFO]

Pre-merge review finding: GraphWhiteboardAnnotationRecord accepts a GraphWhiteboardPrimitiveReference and a GraphWhiteboardAnnotationPrimitivePayload, and both carry a GraphWhiteboardPrimitiveKind, but the record does not enforce that the two kinds match. That means the new contract can represent an invalid annotation where the primitive reference says Rectangle while the payload serializes Freehand geometry/style/lifecycle.

Evidence: GraphWhiteboardPrimitiveReference.Kind is defined separately from GraphWhiteboardAnnotationPrimitivePayload.Kind, and the GraphWhiteboardAnnotationRecord constructor only null-checks the three objects before assigning them. The new focused test only covers the matching Freehand/Freehand case, so this invalid state is currently allowed by the contract skeleton.

Because this PR is specifically defining the future annotation-store contract shape and primitive reference rules, please either remove the duplicated kind from one side or validate PrimitiveReference.Kind == Payload.Kind in GraphWhiteboardAnnotationRecord, with a regression test for the mismatched-kind case.

[ExplodingUFO]

Fixed the annotation primitive kind consistency blocker in 246a0c3.

What changed:

• Added a regression test for a mismatched GraphWhiteboardPrimitiveReference.Kind and GraphWhiteboardAnnotationPrimitivePayload.Kind.
• GraphWhiteboardAnnotationRecord now rejects mismatched reference/payload primitive kinds with ArgumentException.
• Kept the contract skeleton internal and persistence-neutral; no GraphDocument/schema/workspace/export behavior changed.

Verification:

• Red test reproduced the invalid state first: mismatched Rectangle reference + Freehand payload was accepted.
• Focused WhiteboardAnnotationStoreContractTests: 3/3 passing.
• dotnet build AsterGraph.sln -c Release -v:minimal: 0 warnings, 0 errors.
• Full AsterGraph.Editor.Tests: 885/885 passing.
• Full AsterGraph.Demo.Tests: 303/303 passing.
• Public API validation: PUBLIC_API_SURFACE_OK:4292:net9.0.
• git diff --check: no whitespace errors; CRLF notices only.
• GitHub PR checks are all green; PR reports MERGEABLE/CLEAN.

[ExplodingUFO]

Final restack verification for PR #240 after the Phase 557 rewrite:

• Base: 52c02fb8bf03cb8f1a45b547c523fe49eb0f5235 (docs/phase-557-whiteboard-annotation-store-contract)
• Head: a1872e805c4ea560317eff48afa57cf0e58ac006 (feature/phase-558-whiteboard-annotation-store-contract-skeleton)
• git range-diff 5c0469e..246a0c3 52c02fb..HEAD shows the two Phase 558 commits are equivalent after restack.

Local verification in .worktrees/phase-558-whiteboard-annotation-store-contract-skeleton:

• dotnet test tests\AsterGraph.Editor.Tests\AsterGraph.Editor.Tests.csproj -c Release --filter "FullyQualifiedName~WhiteboardAnnotationStoreContractTests" -> 3/3 passed
• dotnet test tests\AsterGraph.Demo.Tests\AsterGraph.Demo.Tests.csproj -c Release --filter "FullyQualifiedName~ReactFlowParityRoadmapDocsTests" -> 58/58 passed
• dotnet build AsterGraph.sln -c Release --no-restore -> 0 warnings, 0 errors
• dotnet test tests\AsterGraph.Editor.Tests\AsterGraph.Editor.Tests.csproj -c Release --no-build -> 885/885 passed
• dotnet test tests\AsterGraph.Demo.Tests\AsterGraph.Demo.Tests.csproj -c Release --no-build -> 303/303 passed
• pwsh -NoProfile -ExecutionPolicy Bypass -File eng\validate-public-api-surface.ps1 -Configuration Release -Framework net9.0 -> PUBLIC_API_SURFACE_OK:4292:net9.0 and related scope/guidance/diff markers passed
• git diff --check 52c02fb..HEAD -> clean

Note: I first tried the public API validation with the obsolete -TargetFramework parameter; that invocation failed before validation. The command above is the corrected -Framework net9.0 invocation and passed.

GitHub remote verification is now MERGEABLE / CLEAN; all duplicate checks passed: hygiene-proof, framework-matrix net8.0/net9.0/net10.0, linux-validation, macos-validation, contract-proof, and release-validation.

PR remains blocked only for stacked merge ordering behind Phase 557 / PR #238 and the lower stack.