@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/docs/plans/waves/specs/wave-1-runtime-contracts.md

@@ -1,509 +0,0 @@
-# Wave 1 - Runtime And Host Contract Lock
-
-**Agent:** A2 (Runtime And Host Contract Lock)
-**Date:** 2026-03-25
-**Status:** frozen for Wave 2 implementation
-
-This spec freezes the runtime and host-facing contract for the shipped `WordReviewEditor` component.
-
-It is downstream of:
-
-- `docs/plans/waves/design/wave-1-a1.md`
-- `docs/plans/waves/specs/wave-1-component-boundaries.md`
-
-## 1. Contract Goals
-
-Wave 1 freezes four boundaries:
-
-- `DocumentRuntime` is the only mutation authority for a mounted editor session.
-- React consumes a render snapshot through an external-store subscription boundary and never owns editable document truth.
-- Hosts persist and resume through `PersistedEditorSnapshot`, not through render snapshots or DOM reads.
-- The public component name is `WordReviewEditor`; residual `WordEditor` naming is not part of the shipped surface.
-
-## 2. Session Model
-
-One mounted `WordReviewEditor` owns one `DocumentRuntime` instance.
-
-Frozen load sources:
-
-- `initialDocx`
-- `initialSnapshot`
-- datastore `load(...)` fallback when neither initial source prop is provided
-
-Frozen reload model:
-
-- the component is uncontrolled by default
-- an optional replace-on-change path is allowed for host-driven document replacement
-- replace-on-change is a full runtime teardown and reload when the host revision token changes
-- replace-on-change is not keystroke-by-keystroke controlled editing
-
-Frozen host reload props:
-
-```ts
-type ExternalDocumentSource =
-  | {
-      kind: "docx";
-      bytes: Uint8Array | ArrayBuffer;
-      sourceLabel?: string;
-    }
-  | {
-      kind: "snapshot";
-      snapshot: PersistedEditorSnapshot;
-      sourceLabel?: string;
-    };
-
-interface WordReviewEditorProps {
-  externalDocumentRevision?: string;
-  externalDocSource?: ExternalDocumentSource;
-}
-```
-
-Reload rule:
-
-- if `externalDocumentRevision` changes and `externalDocSource` is present, the runtime disposes the current working session and loads the new source
-- if `externalDocumentRevision` does not change, the host must not expect prop changes to mutate the active in-memory session
-
-## 3. Runtime Boundary
-
-The runtime contract is frozen around an external-store pair plus command dispatch.
-
-```ts
-type Unsubscribe = () => void;
-
-interface DocumentRuntime {
-  subscribe(listener: () => void): Unsubscribe;
-  getRenderSnapshot(): RuntimeRenderSnapshot;
-  dispatch(command: EditorCommand): void;
-
-  undo(): void;
-  redo(): void;
-
-  focus(): void;
-  blur(): void;
-
-  addComment(params: AddCommentParams): string;
-  openComment(commentId: string): void;
-  resolveComment(commentId: string): void;
-
-  acceptChange(changeId: string): void;
-  rejectChange(changeId: string): void;
-  acceptAllChanges(): void;
-  rejectAllChanges(): void;
-
-  getPersistedSnapshot(): PersistedEditorSnapshot;
-  getCompatibilityReport(): CompatibilityReport;
-  getWarnings(): EditorWarning[];
-  exportDocx(options?: ExportDocxOptions): Promise<ExportResult>;
-}
-```
-
-Frozen runtime rules:
-
-- every mutating entry point routes through `command -> transaction -> mapping -> remap -> commit -> notify`
-- `subscribe(...)` listeners fire only after remap and atomic commit complete
-- `getRenderSnapshot()` returns a pure projection for rendering and command enablement
-- `getPersistedSnapshot()` returns the host persistence artifact and is separate from the render projection
-- the runtime owns warnings, errors, compatibility data, and event emission
-
-## 4. Render Snapshot Boundary
-
-React renders from `RuntimeRenderSnapshot`, not from `PersistedEditorSnapshot`.
-
-```ts
-interface RuntimeRenderSnapshot {
-  documentId: string;
-  sessionId: string;
-  sourceLabel?: string;
-
-  revisionToken: string;
-  isReady: boolean;
-  isDirty: boolean;
-  readOnly: boolean;
-
-  selection: SelectionSnapshot;
-  documentStats: DocumentStats;
-  comments: CommentSidebarSnapshot;
-  trackedChanges: TrackedChangesSnapshot;
-
-  compatibility: CompatibilityPanelSnapshot;
-  warnings: EditorWarning[];
-  fatalError?: EditorError;
-
-  commandState: CommandStateSnapshot;
-}
-```
-
-Frozen render-snapshot rules:
-
-- render snapshots are ephemeral runtime projections and are not persistence artifacts
-- render snapshots may be denormalized for UI convenience
-- render snapshots must remain derivable from runtime-owned state
-- render snapshots must not become a second editable source of truth
-- review surfaces that highlight or focus one thread must read the active thread id from `RuntimeRenderSnapshot.comments.activeCommentId`, not infer it from DOM state
-
-## 5. Persisted Snapshot Boundary
-
-`PersistedEditorSnapshot` is the only frozen host-facing resume artifact.
-
-```ts
-interface PersistedEditorSnapshot {
-  snapshotVersion: "persisted-editor-snapshot/1";
-  schemaVersion: "cds/1.0.0";
-
-  documentId: string;
-  docId: string;
-
-  createdAt: string;
-  updatedAt: string;
-  savedAt: string;
-  editorBuild: string;
-
-  canonicalDocument: CanonicalDocument;
-  compatibility: CompatibilityReport;
-  warningLog: EditorWarning[];
-}
-```
-
-Frozen persisted-snapshot rules:
-
-- `canonicalDocument` is the serialized canonical envelope with the exact Wave 1 top-level keys
-- loading a `PersistedEditorSnapshot` resumes from canonical state and does not re-run OOXML import
-- `savedAt` is the save checkpoint timestamp, separate from document lifecycle timestamps
-- compatibility data in the snapshot is the last runtime-generated view at save time
-- render-only UI state such as sidebar open state is not part of the persistence contract
-
-## 6. Range And Selection Projection
-
-All host-visible ranges are runtime-derived projections over the shared position model.
-
-```ts
-type EditorAnchorProjection =
-  | {
-      kind: "range";
-      from: number;
-      to: number;
-      assoc: {
-        start: -1 | 1;
-        end: -1 | 1;
-      };
-    }
-  | {
-      kind: "node";
-      at: number;
-      assoc: -1 | 1;
-    }
-  | {
-      kind: "detached";
-      lastKnownRange: {
-        from: number;
-        to: number;
-      };
-      reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity";
-    };
-
-interface SelectionSnapshot {
-  anchor: number;
-  head: number;
-  isCollapsed: boolean;
-  activeRange: EditorAnchorProjection;
-}
-```
-
-Frozen range rules:
-
-- positions are integers in the shared canonical main-story coordinate space
-- hosts do not receive DOM-path, node-key, or HTML offset references
-- detached anchors remain inspectable and warning-linkable after invalidation
-
-## 7. Warning Envelope
-
-Warnings are host-visible, non-fatal runtime diagnostics.
-
-```ts
-type EditorWarningCode =
-  | "unsupported_ooxml_preserved"
-  | "unsupported_ooxml_locked"
-  | "import_normalized"
-  | "export_roundtrip_risk"
-  | "comment_anchor_detached"
-  | "revision_anchor_detached"
-  | "large_document_degraded"
-  | "font_substitution"
-  | "image_missing";
-
-interface EditorWarning {
-  warningId: string;
-  code: EditorWarningCode;
-  severity: "info" | "warning";
-  message: string;
-  source:
-    | "import"
-    | "runtime"
-    | "review"
-    | "preservation"
-    | "validation"
-    | "export";
-  affectedAnchor?: EditorAnchorProjection;
-  featureEntryId?: string;
-  details?: Record<string, unknown>;
-}
-```
-
-Frozen warning rules:
-
-- warnings are structured and stable enough for host logging, UI linking, and snapshot persistence
-- warnings may point to detached anchors when a prior range can no longer be attached
-- warnings do not imply export failure on their own
-
-## 8. Error Envelope
-
-Errors are structured failures. Some are fatal to the editing session.
-
-```ts
-type EditorErrorCode =
-  | "import_failed"
-  | "export_failed"
-  | "package_corrupt"
-  | "validation_failed"
-  | "datastore_failed"
-  | "internal_invariant";
-
-interface EditorError {
-  errorId: string;
-  code: EditorErrorCode;
-  message: string;
-  isFatal: boolean;
-  source:
-    | "import"
-    | "runtime"
-    | "validation"
-    | "datastore"
-    | "export";
-  details?: Record<string, unknown>;
-}
-```
-
-Frozen error rules:
-
-- fatal errors may place the editor into a non-editable error state
-- non-fatal errors surface through callbacks and status surfaces without discarding the active session
-- error envelopes remain host-visible and serializable
-
-## 9. Compatibility Report Envelope
-
-The public compatibility contract stays separate from render snapshots and separate from raw warning lists.
-
-```ts
-type CompatibilityFeatureClass =
-  | "supported-roundtrip"
-  | "preserve-only"
-  | "unsupported-fatal";
-
-interface CompatibilityFeatureEntry {
-  featureEntryId: string;
-  featureKey: string;
-  featureClass: CompatibilityFeatureClass;
-  message: string;
-  affectedAnchor?: EditorAnchorProjection;
-  details?: Record<string, unknown>;
-}
-
-interface CompatibilityReport {
-  reportVersion: "compatibility-report/1";
-  generatedAt: string;
-  blockExport: boolean;
-  featureEntries: CompatibilityFeatureEntry[];
-  warnings: EditorWarning[];
-  errors: EditorError[];
-}
-```
-
-Frozen compatibility rules:
-
-- `blockExport` is the single export gate bit
-- feature classes are exactly `supported-roundtrip`, `preserve-only`, and `unsupported-fatal`
-- the report is available from both the runtime and `PersistedEditorSnapshot`
-
-## 10. Event Model
-
-The host event stream is a discriminated union with stable envelopes.
-
-```ts
-type WordReviewEditorEvent =
-  | {
-      type: "ready";
-      documentId: string;
-      sessionId: string;
-      source: "docx" | "snapshot" | "datastore" | "canonical";
-      stats: DocumentStats;
-      compatibility: CompatibilityReport;
-    }
-  | {
-      type: "dirty_changed";
-      documentId: string;
-      isDirty: boolean;
-    }
-  | {
-      type: "selection_changed";
-      documentId: string;
-      selection: SelectionSnapshot;
-    }
-  | {
-      type: "comment_added";
-      documentId: string;
-      commentId: string;
-      anchor: EditorAnchorProjection;
-    }
-  | {
-      type: "comment_resolved";
-      documentId: string;
-      commentId: string;
-    }
-  | {
-      type: "change_accepted";
-      documentId: string;
-      changeId: string;
-    }
-  | {
-      type: "change_rejected";
-      documentId: string;
-      changeId: string;
-    }
-  | {
-      type: "warning_added";
-      documentId: string;
-      warning: EditorWarning;
-    }
-  | {
-      type: "warning_cleared";
-      documentId: string;
-      warningId: string;
-      code: EditorWarningCode;
-    }
-  | {
-      type: "error";
-      documentId: string;
-      error: EditorError;
-    }
-  | {
-      type: "autosave_state";
-      documentId: string;
-      state: AutosaveState;
-    }
-  | {
-      type: "snapshot_saved";
-      documentId: string;
-      snapshot: PersistedEditorSnapshot;
-      isAutosave: boolean;
-    }
-  | {
-      type: "export_completed";
-      documentId: string;
-      result: ExportResult;
-    };
-```
-
-Frozen event rules:
-
-- every event is emitted after the relevant runtime commit or completion boundary
-- warning and error callbacks may mirror these envelopes, but the discriminated union remains the single canonical event stream
-- the host must not infer document truth by replaying events instead of using snapshots and runtime exports
-
-## 11. Public Ref Boundary
-
-The host imperative ref remains a thin runtime wrapper.
-
-```ts
-interface WordReviewEditorRef {
-  focus(): void;
-  blur(): void;
-
-  undo(): void;
-  redo(): void;
-
-  addComment(params: AddCommentParams): string;
-  openComment(commentId: string): void;
-  resolveComment(commentId: string): void;
-
-  acceptChange(changeId: string): void;
-  rejectChange(changeId: string): void;
-  acceptAllChanges(): void;
-  rejectAllChanges(): void;
-
-  exportDocx(options?: ExportDocxOptions): Promise<ExportResult>;
-  getSnapshot(): PersistedEditorSnapshot;
-  getCompatibilityReport(): CompatibilityReport;
-  getWarnings(): EditorWarning[];
-}
-```
-
-Frozen ref rules:
-
-- the ref does not expose DOM nodes
-- the ref does not expose mutable canonical state objects
-- `getSnapshot()` is the public name even though the runtime method is `getPersistedSnapshot()`
-
-## 12. Public Props Boundary
-
-```ts
-interface WordReviewEditorProps {
-  documentId: string;
-  currentUser: EditorUser;
-
-  initialDocx?: Uint8Array | ArrayBuffer;
-  initialSnapshot?: PersistedEditorSnapshot;
-  initialSourceLabel?: string;
-
-  externalDocumentRevision?: string;
-  externalDocSource?: ExternalDocumentSource;
-
-  readOnly?: boolean;
-  reviewMode?: "editing" | "review";
-  markupDisplay?: "clean" | "simple" | "all";
-
-  datastore?: EditorDatastoreAdapter;
-  autosave?: AutosaveConfig;
-
-  onEvent?: (event: WordReviewEditorEvent) => void;
-  onWarning?: (warning: EditorWarning) => void;
-  onError?: (error: EditorError) => void;
-}
-```
-
-Frozen prop rules:
-
-- first load accepts exactly one of `initialDocx` or `initialSnapshot` when an explicit initial source is provided
-- `documentId` is the host-level identity key and is distinct from canonical `docId`
-- `reviewMode` and `markupDisplay` are UI-runtime controls, not alternate persistence formats
-
-## 13. Datastore Boundary
-
-```ts
-interface EditorDatastoreAdapter {
-  load(params: { documentId: string }): Promise<LoadResult>;
-  saveSnapshot(params: SaveSnapshotParams): Promise<SaveSnapshotResult>;
-  saveExport(params: SaveExportParams): Promise<SaveExportResult>;
-  logEvent?(event: EditorTelemetryEvent): void;
-}
-
-interface LoadResult {
-  source?:
-    | { kind: "docx"; bytes: Uint8Array; sourceLabel?: string }
-    | { kind: "snapshot"; snapshot: PersistedEditorSnapshot; sourceLabel?: string };
-}
-```
-
-Frozen datastore rules:
-
-- datastore save and load operate on the persisted snapshot or final `.docx` artifact
-- datastore integrations do not bypass the runtime mutation pipeline
-
-## 14. Change Control Notes
-
-The following are frozen by this spec and require a new wave decision to change:
-
-- the dual snapshot boundary of render snapshot versus persisted snapshot
-- the `warning_added`, `warning_cleared`, `error`, and `snapshot_saved` event envelopes
-- the runtime-derived `EditorAnchorProjection` contract
-- the replace-on-change prop pair `externalDocumentRevision` and `externalDocSource`
-- the persisted snapshot keys `snapshotVersion`, `schemaVersion`, `documentId`, `docId`, `createdAt`, `updatedAt`, `savedAt`, `editorBuild`, `canonicalDocument`, `compatibility`, and `warningLog`