Phase 566: whiteboard annotation sidecar serializer contract

[ExplodingUFO]

Context

Phase 565 will refresh the queue after the Phase 560-564 annotation-store planning gates. Before workspace save/load can persist whiteboard annotations, AsterGraph needs a bounded sidecar document and serializer contract that can carry the internal annotation-store snapshot without changing GraphDocument itself.

Scope

Define and verify the internal sidecar document/serializer contract for whiteboard annotations:

• map GraphWhiteboardAnnotationStoreSnapshot, metadata, identity/reference, primitive payload, and migration metadata into a sidecar payload shape;
• keep ownership separate from GraphDocument and workspace graph serialization;
• define deterministic round-trip and validation behavior for malformed or incompatible sidecar payloads;
• add focused tests/docs for the serializer contract and compatibility boundary.

Out of scope

No workspace save/load integration, no file/database I/O beyond focused serializer contract tests, no GraphDocument schema change, no schema version bump, no clipboard/export behavior change, no screenshot manifest expansion, no renderer or pointer behavior change, no toolbar or eraser change, no public API exposure, and no full React Flow whiteboard parity claim.

Dependency / Stack

Depends on Phase 565 / GitHub #253 / avalonia-node-map-wml. Do not start implementation before the Phase 565 queue refresh lands.

Acceptance Criteria

• Internal sidecar document and serializer contract is covered by focused tests.
• Round-trip tests preserve annotation metadata, identity/reference, primitive payload, and migration metadata.
• Compatibility tests reject or isolate unsupported payloads without mutating GraphDocument.
• Docs keep the claim internal and explicitly state no workspace save/load behavior change, no GraphDocument schema change, no public API exposure, and no full whiteboard parity.

[ExplodingUFO]

Read-only implementation prep (do not start before Phase 565 lands)

Checked the Phase 565 stacked baseline (docs/phase-565-post-annotation-proof-queue-refresh at 61c4a8a) rather than current master, because Phase 566 is stacked after #259.

Relevant internal annotation-store contract already exists on that baseline:

• src/AsterGraph.Core/Models/GraphWhiteboardAnnotationStoreContract.cs
  • GraphWhiteboardAnnotationStoreContract.Current
  • GraphWhiteboardAnnotationStoreMetadata
  • GraphWhiteboardAnnotationMigrationMetadata.Current (StoreSchemaVersion: 1)
  • GraphWhiteboardAnnotationIdentity
  • GraphWhiteboardPrimitiveReference
  • GraphWhiteboardAnnotationPrimitivePayload
  • GraphWhiteboardAnnotationRecord
  • GraphWhiteboardAnnotationStoreSnapshot
  • IGraphWhiteboardAnnotationStoreBoundary
  • InMemoryGraphWhiteboardAnnotationStoreBoundary

Closest serializer patterns to mirror:

• src/AsterGraph.Core/Serialization/GraphDocumentSerializer.cs + GraphDocumentCompatibility.cs for current-schema payloads, explicit legacy import, and unknown/future schema rejection wording.
• src/AsterGraph.Editor/Services/Persistence/Clipboard/GraphClipboardPayloadSerializer.cs + GraphClipboardPayloadCompatibility.cs for a separate versioned payload contract that is not folded into GraphDocument.
• Keep the sidecar contract internal and separate from workspace save/load integration in this phase.

Candidate focused tests for Phase 566:

• Round-trip a GraphWhiteboardAnnotationStoreSnapshot preserving metadata, store schema/migration policy, identity, primitive reference, geometry/style, z-index, and edit lifecycle.
• Reject malformed payloads and unknown/future sidecar schema versions with deterministic guidance.
• Prove GraphDocumentSerializer.Serialize(...) output still contains no annotation-store or whiteboard-annotation members.
• Prove the sidecar payload contract remains independent from clipboard/export/workspace integration.
• Reuse WhiteboardAnnotationStoreContractTests, SerializationCompatibilityTests, and EditorClipboardAndFragmentCompatibilityTests as local templates.

Related cleanup found during prep:

• Current master had EN/ZH serialization docs still describing workspace schema version 5 while code/tests already use GraphDocumentCompatibility.CurrentSchemaVersion = 6.
• Tracked separately as Align serialization contract docs with schema version 6 #260 / Beads avalonia-node-map-4da; implemented in PR Align serialization docs with schema version 6 #261 (docs/issue-260-serialization-schema-6). PR Align serialization docs with schema version 6 #261 is green but review-blocked, so Phase 566 docs should either wait for that PR to land or avoid reintroducing stale schema-version wording.

This note is preparation only. Phase 566 remains blocked until Phase 565 / #253 / #259 lands and the lower stack is review-unblocked.