Phase 549: whiteboard persistence decision gate

docs/en/phase-0-reactflow-parity-audit.md

@@ -238,6 +238,10 @@ Phase 547 is GitHub #217 / `avalonia-node-map-rs0`, the first whiteboard primiti
 
 Phase 548 is GitHub #219 / `avalonia-node-map-10p`, the first whiteboard primitive renderer adapter skeleton. This internal Core adapter slice records `WHITEBOARD_PRIMITIVE_RENDERER_ADAPTER_SKELETON`: `GraphWhiteboardPrimitiveRendererAdapter` maps rectangle/freehand primitive projection into `GraphWhiteboardPrimitiveSceneSnapshot` scene items, and `GraphWhiteboardPrimitiveHitTestResult` records topmost primitive hit-testing evidence with z-order plus edit lifecycle metadata. The adapter remains renderer-neutral and separate from `GraphDocument`, `GraphEditorSceneSnapshot`, and `NodeCanvasConnectionSceneRenderer`. Phase 548 is stacked after PR #218 and must not merge before Phase 547. It authorizes no GraphDocument schema change, no public drawing API, no Avalonia renderer rewrite, no NodeCanvasConnectionSceneRenderer edits, no pointer coordinator changes, no toolbar/tool activation, no eraser behavior, no persistence/schema work, no schema version bump, no screenshot manifest expansion, no Cookbook visual proof implementation, no UI redesign, no retained API removal, and no full React Flow whiteboard parity.
 
+## Phase 549 Update
+
+Phase 549 is GitHub #221 / `avalonia-node-map-3l6`, the whiteboard primitive persistence decision implementation gate. This internal Core policy slice records `WHITEBOARD_PRIMITIVE_PERSISTENCE_DECISION_GATE`: `GraphWhiteboardPrimitivePersistenceDecision` chooses a separate annotation surface and `ExcludedFromCurrentGraphDocumentSchema` for current whiteboard primitives, while keeping `GraphDocumentCompatibility`, `GraphDocumentSerializer`, and `CurrentSchemaVersion` graph-document scoped. The contract lists migration policy, compatibility tests, workspace persistence boundary tests, clipboard fragment boundary tests, and screenshot artifact boundary tests as required before any future GraphDocument schema change. Phase 549 is stacked after PR #220 and must not merge before Phase 548. It authorizes no GraphDocument schema change, no schema version bump, no workspace persistence behavior change, no public drawing API, no Avalonia pointer coordinator edits, no toolbar/tool activation, no eraser behavior, no screenshot manifest expansion, no Cookbook visual proof implementation, no UI redesign, no retained API removal, and no full React Flow whiteboard parity.
+
 ## Phase 489 Update
 
 Phase 489 closed GitHub #101 / `avalonia-node-map-6sc` through PR #102 as a renderer virtualization design spike on branch `perf/renderer-virtualization-spike`. This slice was docs/tests only: it defined the proof contract required before any future ItemsRepeater/Skia-style renderer virtualization, background graph index, or graph-size claim expansion. It made no public API change and no runtime change. The current evidence remains viewport-budgeted scene projection/rendering, not a true renderer virtualization contract; `xlarge` stays telemetry-only.
@@ -567,6 +571,8 @@ Phase 547 records the first whiteboard primitive model skeleton through GitHub #
 
 Phase 548 records the whiteboard primitive renderer adapter skeleton through GitHub #219 / `avalonia-node-map-10p`. It adds only internal renderer-neutral projection and topmost primitive hit-testing evidence for the Phase 547 primitive model; persistence/schema, Avalonia pointer coordinators, toolbar activation, eraser behavior, screenshot manifests, Cookbook implementation, and any full React Flow whiteboard parity claim remain later tracker-backed work.
 
+Phase 549 records the whiteboard primitive persistence decision implementation gate through GitHub #221 / `avalonia-node-map-3l6`. It adds only the internal `GraphWhiteboardPrimitivePersistenceDecision` policy contract: current whiteboard primitives use a separate annotation surface, remain `ExcludedFromCurrentGraphDocumentSchema`, and do not change `GraphDocumentCompatibility`, `GraphDocumentSerializer`, `CurrentSchemaVersion`, workspace persistence, clipboard fragments, screenshot artifacts, or public drawing APIs.
+
 | GitHub | Bead | Title | Priority | Likely write set | Parallelism |
 | --- | --- | --- | --- | --- | --- |
 | #193 | `avalonia-node-map-8l6` | Phase 535: refresh post-lasso visual feedback parity queue | P2 | parity roadmap docs and focused docs tests | Current docs/test queue refresh. Blocks the next implementation wave because it replaces the stale Phase 534 current row with tracker-backed follow-ups. |
@@ -583,7 +589,7 @@ Phase 548 records the whiteboard primitive renderer adapter skeleton through Git
 | #215 | `avalonia-node-map-0l9` | Phase 546: post-Phase-545 whiteboard implementation queue refresh | P4 | parity roadmap docs and focused docs tests | Stacked after PR #214; do not merge before Phase 545. This queue refresh records the next candidates without runtime/API/model/schema/renderer/screenshot-manifest behavior. |
 | #217 | `avalonia-node-map-rs0` | Phase 547: whiteboard primitive model skeleton | P2 | Core/Editor primitive model tests, internal model types, and renderer-neutral contract docs | Stacked after PR #216; do not merge before Phase 546. This slice adds the internal model skeleton only and must not touch renderer adapters, persistence/schema, pointer coordinators, screenshot manifests, toolbar UX, or eraser behavior. |
 | #219 | `avalonia-node-map-10p` | Phase 548: whiteboard primitive renderer adapter skeleton | P2 | renderer adapter tests, scene snapshot projection proof, and topmost primitive hit-testing evidence | Stacked after PR #218; do not merge before Phase 547. Must keep persistence/schema, Cookbook screenshot rows, pointer coordinators, and toolbar activation out of scope. |
-| TBD | TBD | Phase 549: whiteboard primitive persistence decision implementation gate | P3 | persistence decision tests, schema/surface choice, migration criteria, and compatibility coverage | Candidate after Phase 547 and the Phase 544 policy gate. Must decide storage ownership before any saved whiteboard primitive claim. |
+| #221 | `avalonia-node-map-3l6` | Phase 549: whiteboard primitive persistence decision implementation gate | P3 | persistence decision tests, schema/surface choice, migration criteria, and compatibility coverage | Stacked after PR #220; do not merge before Phase 548. Chooses separate annotation surface and keeps GraphDocument schema/version/workspace persistence unchanged before any saved whiteboard primitive claim. |
 | TBD | TBD | Phase 550: whiteboard primitive Cookbook screenshot implementation gate | P3 | Cookbook screenshot implementation gate docs/tests, route metadata, shell state, and non-overlap visual proof | Candidate after model, renderer, and persistence decisions. Must add visual proof before any whiteboard visual parity claim. |
 
 ## Recommended Parallel Worktree Plan

docs/zh-CN/phase-0-reactflow-parity-audit.md

@@ -238,6 +238,10 @@ Phase 547 是 GitHub #217 / `avalonia-node-map-rs0`，承接第一条 whiteboard
 
 Phase 548 是 GitHub #219 / `avalonia-node-map-10p`，承接第一条 whiteboard primitive renderer adapter skeleton。本 internal Core adapter slice 记录 `WHITEBOARD_PRIMITIVE_RENDERER_ADAPTER_SKELETON`：`GraphWhiteboardPrimitiveRendererAdapter` 将 rectangle/freehand primitive projection 映射为 `GraphWhiteboardPrimitiveSceneSnapshot` scene items，`GraphWhiteboardPrimitiveHitTestResult` 记录带 z-order 与 edit lifecycle metadata 的 topmost primitive hit-testing evidence。该 adapter 保持 renderer-neutral，并继续与 `GraphDocument`、`GraphEditorSceneSnapshot` 和 `NodeCanvasConnectionSceneRenderer` 分离。Phase 548 stacked after PR #218，不能早于 Phase 547 合并。它不授权 no GraphDocument schema change、no public drawing API、no Avalonia renderer rewrite、no NodeCanvasConnectionSceneRenderer edits、no pointer coordinator changes、no toolbar/tool activation、no eraser behavior、no persistence/schema work、no schema version bump、no screenshot manifest expansion、no Cookbook visual proof implementation、no UI redesign、no retained API removal 或 no full React Flow whiteboard parity。
 
+## Phase 549 更新
+
+Phase 549 是 GitHub #221 / `avalonia-node-map-3l6`，记录 whiteboard primitive persistence decision implementation gate。本 internal Core policy slice 记录 `WHITEBOARD_PRIMITIVE_PERSISTENCE_DECISION_GATE`：`GraphWhiteboardPrimitivePersistenceDecision` 为当前 whiteboard primitives 选择 separate annotation surface，并标记 `ExcludedFromCurrentGraphDocumentSchema`，同时继续把 `GraphDocumentCompatibility`、`GraphDocumentSerializer` 和 `CurrentSchemaVersion` 限定为 graph-document scope。该 contract 记录任何后续 GraphDocument schema change 前必须补齐 migration policy、compatibility tests、workspace persistence boundary tests、clipboard fragment boundary tests 和 screenshot artifact boundary tests。Phase 549 stacked after PR #220，不能早于 Phase 548 合并。它不授权 no GraphDocument schema change、no schema version bump、no workspace persistence behavior change、no public drawing API、no Avalonia pointer coordinator edits、no toolbar/tool activation、no eraser behavior、no screenshot manifest expansion、no Cookbook visual proof implementation、no UI redesign、no retained API removal 或 no full React Flow whiteboard parity。
+
 ## Phase 489 更新
 
 Phase 489 通过 PR #102 关闭 GitHub #101 / `avalonia-node-map-6sc`，完成 `perf/renderer-virtualization-spike` 分支上的 renderer virtualization design spike。本 slice 只做 docs/tests：先定义未来声明 ItemsRepeater/Skia-style renderer virtualization、background graph index 或扩大 graph-size claim 前必须满足的 proof contract。不做 public API change，也不做 runtime change。当前证据仍只支持 viewport-budgeted scene projection/rendering，不是真正的 renderer virtualization contract；`xlarge` 继续保持 telemetry-only。
@@ -567,6 +571,8 @@ Phase 547 通过 GitHub #217 / `avalonia-node-map-rs0` 记录第一条 whiteboar
 
 Phase 548 记录 whiteboard primitive renderer adapter skeleton，通过 GitHub #219 / `avalonia-node-map-10p`。它只为 Phase 547 primitive model 添加 internal renderer-neutral projection 与 topmost primitive hit-testing evidence；persistence/schema、Avalonia pointer coordinators、toolbar activation、eraser behavior、screenshot manifests、Cookbook implementation，以及任何 full React Flow whiteboard parity claim 都保留为后续 tracker-backed work。
 
+Phase 549 记录 whiteboard primitive persistence decision implementation gate，通过 GitHub #221 / `avalonia-node-map-3l6`。它只添加 internal `GraphWhiteboardPrimitivePersistenceDecision` policy contract：当前 whiteboard primitives 使用 separate annotation surface，保持 `ExcludedFromCurrentGraphDocumentSchema`，并且不修改 `GraphDocumentCompatibility`、`GraphDocumentSerializer`、`CurrentSchemaVersion`、workspace persistence、clipboard fragments、screenshot artifacts 或 public drawing APIs。
+
 | GitHub | Bead | 标题 | 优先级 | 可能 write set | 并行边界 |
 | --- | --- | --- | --- | --- | --- |
 | #193 | `avalonia-node-map-8l6` | Phase 535: refresh post-lasso visual feedback parity queue | P2 | parity roadmap docs 和 focused docs tests | Current docs/test queue refresh。它用 tracker-backed follow-ups 替换 stale Phase 534 current row，因此会阻塞下一批 implementation wave。 |
@@ -583,7 +589,7 @@ Phase 548 记录 whiteboard primitive renderer adapter skeleton，通过 GitHub
 | #215 | `avalonia-node-map-0l9` | Phase 546: post-Phase-545 whiteboard implementation queue refresh | P4 | parity roadmap docs 和 focused docs tests | Stacked after PR #214；do not merge before Phase 545。本 queue refresh 只记录下一批 candidates，不做 runtime/API/model/schema/renderer/screenshot-manifest behavior。 |
 | #217 | `avalonia-node-map-rs0` | Phase 547: whiteboard primitive model skeleton | P2 | Core/Editor primitive model tests、internal model types 和 renderer-neutral contract docs | Stacked after PR #216；do not merge before Phase 546。本 slice 只添加 internal model skeleton，不得触碰 renderer adapters、persistence/schema、pointer coordinators、screenshot manifests、toolbar UX 或 eraser behavior。 |
 | #219 | `avalonia-node-map-10p` | Phase 548: whiteboard primitive renderer adapter skeleton | P2 | renderer adapter tests、scene snapshot projection proof 和 topmost primitive hit-testing evidence | Stacked after PR #218；do not merge before Phase 547。persistence/schema、Cookbook screenshot rows、pointer coordinators 和 toolbar activation 都保持 out of scope。 |
-| TBD | TBD | Phase 549: whiteboard primitive persistence decision implementation gate | P3 | persistence decision tests、schema/surface choice、migration criteria 和 compatibility coverage | Phase 547 与 Phase 544 policy gate 后的 candidate。任何 saved whiteboard primitive claim 前必须先决定 storage ownership。 |
+| #221 | `avalonia-node-map-3l6` | Phase 549: whiteboard primitive persistence decision implementation gate | P3 | persistence decision tests、schema/surface choice、migration criteria 和 compatibility coverage | Stacked after PR #220；do not merge before Phase 548。本 slice 选择 separate annotation surface，并在任何 saved whiteboard primitive claim 前保持 GraphDocument schema/version/workspace persistence unchanged。 |
 | TBD | TBD | Phase 550: whiteboard primitive Cookbook screenshot implementation gate | P3 | Cookbook screenshot implementation gate docs/tests、route metadata、shell state 和 non-overlap visual proof | model、renderer 与 persistence decisions 后的 candidate。任何 whiteboard visual parity claim 前必须先补 visual proof。 |
 
 ## 推荐并行 Worktree 计划

src/AsterGraph.Core/Models/GraphWhiteboardPrimitivePersistenceDecision.cs

@@ -0,0 +1,57 @@
+namespace AsterGraph.Core.Models;
+
+/// <summary>
+/// Internal policy gate for future whiteboard primitive persistence.
+/// </summary>
+internal sealed record GraphWhiteboardPrimitivePersistenceDecision(
+    GraphWhiteboardPrimitivePersistenceOwner Owner,
+    GraphWhiteboardPrimitiveGraphDocumentSchemaPolicy GraphDocumentSchemaPolicy,
+    GraphWhiteboardPrimitivePersistenceRequirement RequirementsBeforeGraphDocumentSchemaChange)
+{
+    /// <summary>
+    /// Current Phase 549 decision: whiteboard primitives are not part of the current graph document schema.
+    /// </summary>
+    public static GraphWhiteboardPrimitivePersistenceDecision Current { get; } = new(
+        GraphWhiteboardPrimitivePersistenceOwner.SeparateAnnotationSurface,
+        GraphWhiteboardPrimitiveGraphDocumentSchemaPolicy.ExcludedFromCurrentGraphDocumentSchema,
+        GraphWhiteboardPrimitivePersistenceRequirement.MigrationPolicy
+            | GraphWhiteboardPrimitivePersistenceRequirement.GraphDocumentCompatibilityTests
+            | GraphWhiteboardPrimitivePersistenceRequirement.WorkspacePersistenceBoundaryTests
+            | GraphWhiteboardPrimitivePersistenceRequirement.ClipboardFragmentBoundaryTests
+            | GraphWhiteboardPrimitivePersistenceRequirement.ScreenshotArtifactBoundaryTests);
+
+    /// <summary>
+    /// Whether the active decision stores whiteboard primitives inside GraphDocument payloads.
+    /// </summary>
+    public bool PersistsWhiteboardPrimitivesInGraphDocument
+        => Owner == GraphWhiteboardPrimitivePersistenceOwner.GraphDocumentSchema
+            && GraphDocumentSchemaPolicy == GraphWhiteboardPrimitiveGraphDocumentSchemaPolicy.IncludedInGraphDocumentSchema;
+
+    /// <summary>
+    /// Whether this implementation slice persists whiteboard primitives at all.
+    /// </summary>
+    public bool PersistsWhiteboardPrimitivesInCurrentSlice => false;
+}
+
+internal enum GraphWhiteboardPrimitivePersistenceOwner
+{
+    GraphDocumentSchema,
+    SeparateAnnotationSurface,
+}
+
+internal enum GraphWhiteboardPrimitiveGraphDocumentSchemaPolicy
+{
+    ExcludedFromCurrentGraphDocumentSchema,
+    IncludedInGraphDocumentSchema,
+}
+
+[Flags]
+internal enum GraphWhiteboardPrimitivePersistenceRequirement
+{
+    None = 0,
+    MigrationPolicy = 1 << 0,
+    GraphDocumentCompatibilityTests = 1 << 1,
+    WorkspacePersistenceBoundaryTests = 1 << 2,
+    ClipboardFragmentBoundaryTests = 1 << 3,
+    ScreenshotArtifactBoundaryTests = 1 << 4,
+}