@beyondwork/docx-react-component 1.0.0 → 1.0.1

package/docs/plans/waves/specs/wave-1-component-boundaries.md

@@ -1,322 +0,0 @@
-# Wave 1 - Component Boundaries Spec
-
-**Agent:** A1 (Architecture Design Packet)
-**Date:** 2026-03-25
-**Status:** frozen for Wave 2 implementation
-
-This spec freezes ownership, import directions, contract seams, and proof handoff for the Wave 1 promoted components.
-
-## 1. Component Map
-
-```text
-src/
-  api/           public contract types only
-  model/         canonical-document-model
-  core/          canonical-document-model, command-and-transaction-runtime
-  review/        comments-and-anchor-mapping, tracked-changes-and-review-actions
-  io/            docx-import-and-normalization, docx-export-and-serialization
-  preservation/  unsupported-ooxml-preservation
-  validation/    compatibility-and-word-validation
-  runtime/       command-and-transaction-runtime
-  ui/            react-editor-ui
-```
-
-## 2. Ownership Table
-
-| Component | Source owner | Wave 1 role | Repo-land wave | Baseline-proof wave |
-| --- | --- | --- | --- | --- |
-| canonical-document-model | `src/model`, `src/core` type wrappers, `src/api` public type exports | A1 design -> A2 contract and impl | Wave 2 | Wave 3 |
-| command-and-transaction-runtime | `src/core`, `src/runtime` | A1 design -> A2 contract and impl | Wave 2 | Wave 3 |
-| comments-and-anchor-mapping | `src/review` | A1 cross-boundary design -> A4 contract and impl | Wave 4 | Wave 5 |
-| tracked-changes-and-review-actions | `src/review` | A1 cross-boundary design -> A4 contract and impl | Wave 5 | Wave 6 |
-| docx-import-and-normalization | `src/io` reader or normalizer or canonicalizer | A1 design -> A3 contract and impl | Wave 2 | Wave 3 |
-| docx-export-and-serialization | `src/io` serializer or package writer | A1 design -> A3 contract and impl | Wave 2 | Wave 3 |
-| unsupported-ooxml-preservation | `src/preservation` | A1 design -> A3 contract and impl | Wave 6 | Wave 7 |
-| compatibility-and-word-validation | `src/validation` | A1 design -> A3 contract and impl | Wave 3 | Wave 4 |
-| react-editor-ui | `src/ui` | A1 design -> A4 contract and impl | Wave 2 | Wave 3 |
-
-## 3. Import Direction Rules
-
-Allowed high-level dependency directions:
-
-```text
-src/api            <- nothing in src/
-src/model          <- src/api
-src/core           <- src/model, src/api
-src/review         <- src/model, src/core
-src/preservation   <- src/model, src/core
-src/validation     <- src/model, src/core, src/api
-src/io             <- src/model, src/core, src/preservation, src/validation
-src/runtime        <- src/model, src/core, src/review, src/io, src/preservation, src/validation, src/api
-src/ui             <- src/runtime, src/api, src/core view adapters only
-```
-
-Forbidden directions:
-
-- `src/api` must not import from any `src/*` runtime module.
-- `src/model` must not import from `src/core`, `src/review`, `src/io`, `src/preservation`, `src/validation`, `src/runtime`, or `src/ui`.
-- `src/ui` must not import from `src/io`, `src/preservation`, or `src/validation`.
-- `src/ui` must not mutate review or preservation state directly.
-- `src/io` must not import from `src/runtime` or `src/ui`.
-- `src/review` and `src/preservation` must not import from `src/runtime` or `src/ui`.
-
-## 4. Canonical Envelope Boundary
-
-`src/model` owns the canonical document envelope and the scalar types needed to serialize it.
-
-Frozen top-level keys:
-
-- `schemaVersion`
-- `docId`
-- `createdAt`
-- `updatedAt`
-- `metadata`
-- `styles`
-- `numbering`
-- `media`
-- `content`
-- `review`
-- `preservation`
-- `diagnostics`
-
-Frozen domain rule:
-
-- `content`, `review`, and `preservation` are the mutable editing domains.
-- `styles`, `numbering`, `media`, `metadata`, and `diagnostics` are still schema-owned first-class data and must not be recreated as ad hoc runtime-only caches.
-
-Serialization rule:
-
-- Canonical state must remain JSON-serializable and deterministic.
-- Use plain object or array shapes for persisted stores rather than runtime-only `Map` containers.
-
-## 5. Runtime And UI Boundary
-
-`src/runtime` owns the live editing session. `src/ui` is a projection and command-dispatch layer only.
-
-Frozen runtime responsibilities:
-
-- load from `.docx` bytes or `PersistedEditorSnapshot`
-- expose an external-store subscription pair plus a render snapshot getter for React rendering
-- own command dispatch, transaction commit, undo, redo, and remapping
-- emit warnings, events, and compatibility data
-- provide `getPersistedSnapshot()` separately from the render snapshot and provide `.docx` export
-
-Frozen UI responsibilities:
-
-- subscribe to runtime state
-- render toolbar, editor surface, comments or review panels, compatibility surfaces, and status surfaces
-- translate gestures into runtime commands
-- expose the host ref surface through thin runtime wrappers
-
-Frozen prohibitions:
-
-- React must not own editable canonical truth.
-- React must not call IO or preservation modules directly.
-- Runtime must not render UI or depend on React.
-
-## 6. Position, Range, And Anchor Contract
-
-Frozen shared types:
-
-```ts
-type Position = number;
-
-interface DocRange {
-  from: Position;
-  to: Position;
-}
-
-interface BoundaryAssoc {
-  start: -1 | 1;
-  end: -1 | 1;
-}
-```
-
-Frozen size rules:
-
-- text node size = Unicode code point count
-- atomic inline leaf size = `1`
-- atomic block leaf size = `1`
-- container size = `2 + sum(childSizes)`
-- the document root token is not counted; position `0` is before the first child of the editable story
-- the shared position space applies to the editable main story plus atomic placeholders inside it, not to out-of-band preserved stories or package parts
-
-Frozen anchor states:
-
-```ts
-type RangeAnchor = {
-  kind: "range";
-  range: DocRange;
-  assoc: BoundaryAssoc;
-};
-
-type NodeAnchor = {
-  kind: "node";
-  at: Position;
-  assoc: -1 | 1;
-};
-
-type DetachedAnchor = {
-  kind: "detached";
-  lastKnownRange: DocRange;
-  reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity";
-};
-```
-
-Frozen remap rule:
-
-- After every committed transaction, the runtime remaps selection, review anchors, and preservation bindings before subscribers are notified.
-- Invalid anchors become `detached`; they are not silently removed.
-
-## 7. Review Boundary
-
-`src/review` owns comments, revisions, and remap helpers, but it does not own position arithmetic or command dispatch.
-
-Frozen review-store shape:
-
-```ts
-type ReviewStore = {
-  comments: Record<string, CommentThread>;
-  revisions: Record<string, RevisionRecord>;
-};
-```
-
-Frozen v1 authoring scope:
-
-- editable single-paragraph comment ranges and threads
-- tracked insertions
-- tracked deletions
-- accept or reject for the above
-
-Frozen preserve-only review scope:
-
-- multi-paragraph editable comment ranges
-- tracked moves
-- tracked formatting changes
-- structural table or list revisions beyond the supported authoring envelope
-
-## 8. Preservation Boundary
-
-`src/preservation` owns the opaque fragment registry and preserved package-part manifest.
-
-Frozen opaque placeholder contract:
-
-```ts
-type OpaqueInlineNode = {
-  type: "opaque_inline";
-  fragmentId: string;
-  warningId: string;
-};
-
-type OpaqueBlockNode = {
-  type: "opaque_block";
-  fragmentId: string;
-  warningId: string;
-};
-
-type OpaqueFragmentRecord = {
-  fragmentId: string;
-  payloadKind: "xml-subtree" | "package-part";
-  payloadKey: string;
-  featureClass: "preserve-only";
-  lastKnownRange: DocRange;
-  packagePartName?: string;
-  relationshipId?: string;
-};
-```
-
-Frozen preservation rule:
-
-- opaque placeholders are atomic leaf nodes in the canonical content tree
-- the actual XML or bytes live in preservation records, not inline in canonical content
-- the preserved package-part manifest records content type and relationship metadata keyed by `fragmentId` or package part name
-- partial edits inside opaque regions are forbidden
-- whole-node deletion requires an explicit destructive path and warning
-
-## 9. Compatibility Boundary
-
-`src/validation` owns feature classification and compatibility reporting.
-
-Frozen taxonomy:
-
-- `supported-roundtrip`
-- `preserve-only`
-- `unsupported-fatal`
-
-Frozen report minimums:
-
-```ts
-type CompatibilityReport = {
-  reportVersion: number;
-  featureEntries: FeatureEntry[];
-  warnings: EditorWarning[];
-  errors: EditorError[];
-  blockExport: boolean;
-};
-```
-
-Where:
-
-- `featureEntries` carry stable ids for classified features or regions
-- `warnings` and `errors` are host-visible projections
-- `blockExport` is the single export gate summary bit
-
-## 10. IO Boundary
-
-`src/io` owns the package-first pipeline and is the only subsystem that translates between `.docx` and canonical state.
-
-Frozen internal modules:
-
-- `opc-reader`
-- `normalizer`
-- `canonicalizer`
-- `serializer`
-- `opc-writer`
-
-Frozen public boundary toward runtime:
-
-- import accepts `.docx` bytes and returns canonical state plus compatibility data
-- export accepts canonical state plus preservation data and returns `.docx` bytes
-
-Frozen prohibitions:
-
-- no HTML intermediary contract
-- no direct React participation in import or export
-- no runtime-to-UI back edge
-
-## 11. Proof Surface Assignments By Wave
-
-| Component | Wave | Proof surface | Owner |
-| --- | --- | --- | --- |
-| canonical-document-model | Wave 2 | repo-land schema and serialization tests, position arithmetic tests, deterministic snapshot checks | A2 |
-| command-and-transaction-runtime | Wave 2 | repo-land command-dispatch tests, transaction remap tests, and runtime subscription tests | A2 |
-| react-editor-ui | Wave 2 | repo-land shell load or focus or ready smoke over the runtime external-store boundary | A4 |
-| canonical-document-model | Wave 3 | F01-F02 canonical snapshot stability and position remap checks through real text edits | A2 |
-| command-and-transaction-runtime | Wave 3 | F01-F02 undo or redo, remap, and selection consistency through committed transactions | A2 |
-| docx-import-and-normalization | Wave 3 | F01-F02 import fixtures for text, headings, whitespace, tabs, and hard breaks | A3 |
-| docx-export-and-serialization | Wave 3 | F01-F02 export or round-trip fixtures plus package integrity checks | A3 |
-| compatibility-and-word-validation | Wave 3 | repo-land compatibility-report skeleton tests and validator-contract smoke on F01-F02 | A3 |
-| react-editor-ui | Wave 3 | runtime-driven editing smoke tests and imperative-ref smoke tests on F01-F02 | A4 |
-| docx-import-and-normalization | Wave 4 | F03-F04/F07-F08 live supported lists, numbering, inline images, and hyperlinks plus preserve-only truth on F05-F06 tables | A3 |
-| compatibility-and-word-validation | Wave 4 | structural compatibility suite, feature-class assertions, and export-risk gating for F03-F08 | A3 |
-| comments-and-anchor-mapping | Wave 5 | F09-F10 comment fixtures and anchor-remap tests | A4 |
-| tracked-changes-and-review-actions | Wave 6 | F11-F14 revision fixtures and accept or reject tests | A4 |
-| unsupported-ooxml-preservation | Wave 7 | F15-F21 preservation fixtures, opaque-fragment survival tests, malformed-doc export-block checks | A3 |
-
-## 12. Service Boundary
-
-| Service | Role | Frozen boundary |
-| --- | --- | --- |
-| `services/react-word-editor` | Internal Railway harness | Hosts `WordReviewEditor`; does not bypass the runtime by importing editor internals directly for mutation flows. |
-| `services/openxml-validator` | Internal validator service | Accepts `.docx` bytes and returns structured diagnostics; never becomes the primary transformation engine and never ships in the browser bundle. |
-
-## 13. Change Control
-
-The following changes require a new explicit Wave decision before implementation agents act on them:
-
-- the global position model or size rules
-- the mutable-domain split of `content`, `review`, and `preservation`
-- the runtime or UI boundary that keeps React as a subscriber only
-- the three-class compatibility taxonomy
-- the opaque placeholder node kinds
-- the later-wave proof ownership table

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

@@ -1,323 +0,0 @@
-# Wave 1 OOXML, Preservation, And Fixture Contracts
-
-**Agent:** A3  
-**Date:** 2026-03-25  
-**Status:** ready-for-implementation
-
-## Purpose
-
-This packet freezes the Wave 1 contract for:
-
-- `docx-import-and-normalization`
-- `docx-export-and-serialization`
-- `unsupported-ooxml-preservation`
-- `compatibility-and-word-validation`
-
-It converts the repo-wide compatibility promises into implementation-facing rules that later waves must satisfy with fixture-backed proof.
-
-## Governing inputs
-
-This contract is downstream of:
-
-- [README.md](/home/coder/docx-react-component/README.md)
-- [docs/reference/repository-guidance.md](/home/coder/docx-react-component/docs/reference/repository-guidance.md)
-- [docs/plans/waves/design/wave-1-a1.md](/home/coder/docx-react-component/docs/plans/waves/design/wave-1-a1.md)
-- [docs/reference/ooxml-compliance.md](/home/coder/docx-react-component/docs/reference/ooxml-compliance.md)
-- [test/fixtures/docx/README.md](/home/coder/docx-react-component/test/fixtures/docx/README.md)
-
-If a later doc conflicts with A1 decisions D7-D12, this packet inherits A1.
-
-## Non-negotiable contract
-
-- `.docx` is treated as an OPC package, not as `word/document.xml` alone.
-- Import and export stay package-first and unidirectional.
-- Supported editing is only for features that satisfy `supported-roundtrip`.
-- Unsupported but preservable content is preserved, never silently discarded.
-- Opaque preserved content is represented as atomic placeholders in canonical content.
-- The Microsoft Open XML SDK is validation-only and never the runtime transformation engine.
-- Word reopen behavior is the final compatibility standard. SDK validation is necessary but insufficient.
-
-## Feature classes
-
-Wave 1 freezes exactly three feature classes:
-
-- `supported-roundtrip`
-- `preserve-only`
-- `unsupported-fatal`
-
-`supported-import-only` and `supported-export-only` are not valid v1 classes. If a feature cannot safely survive import, supported editing, export, and Word reopen, it must be classified as `preserve-only` or `unsupported-fatal`.
-
-## Package-preservation model
-
-### Owned package surfaces
-
-The editor may regenerate only parts and relationships it explicitly owns for the active supported feature set, including where applicable:
-
-- `word/document.xml`
-- editor-owned supporting parts such as comments, numbering, styles, and media relationships when the editor materially changes those surfaces
-- package metadata entries that must be updated to keep the package valid after owned changes
-
-### Preserved package surfaces
-
-The editor must preserve and reattach unchanged package data for any non-owned or not-yet-canonicalized surface, including:
-
-- unknown parts
-- unknown relationships
-- unknown content types
-- headers and footers
-- footnotes and endnotes
-- fields
-- SDTs
-- custom XML wrappers and custom XML parts
-- `mc:AlternateContent`
-- ignorable namespaces and unknown markup extensions
-- embedded objects and unsupported drawings
-
-### Opaque fragment contract
-
-Unsupported inline or block content that remains preservable must become:
-
-- an `opaque_inline` or `opaque_block` placeholder in canonical content
-- a preservation record keyed by `fragmentId`
-- a warning-bearing binding to the last known canonical range
-
-The preservation record must retain enough original material to reattach the feature on export, such as:
-
-- original XML subtree
-- original package bytes
-- source part path and relationship context
-- feature classification
-- `lastKnownRange`
-
-Wave 1 freezes the rule that opaque placeholders are atomic. Later waves may not partially edit, split, or normalize inside them.
-
-## Import contract
-
-Import must follow:
-
-`.docx bytes -> OPC reader -> OOXML normalizer -> canonicalizer -> runtime load`
-
-### Import obligations
-
-- Read the package graph, including content types and relationships, before canonicalization decisions.
-- Normalize supported OOXML into canonical content, review, and preservation surfaces without routing through HTML.
-- Preserve unsupported but intact OOXML as package-level records or opaque fragments.
-- Emit stable diagnostics for every preserve-only and unsupported-fatal condition.
-- Fail safely on malformed packages that the editor cannot preserve or reason about safely.
-
-### Import outcomes by class
-
-For `supported-roundtrip`, import must:
-
-- parse the feature semantically
-- materialize it into canonical state
-- preserve enough source metadata to serialize back safely
-
-For `preserve-only`, import must:
-
-- retain the source XML or bytes
-- bind the preserved unit to either package manifest state or an atomic placeholder
-- mark the feature locked for direct editing
-- emit any warning needed to explain downstream risk
-
-For `unsupported-fatal`, import must:
-
-- emit an error with export-block semantics
-- prevent the runtime from presenting the document as normally editable
-- avoid repair guesses that could hide corruption
-
-## Export contract
-
-Export must follow:
-
-`canonical state -> serializer -> OPC writer -> .docx bytes`
-
-### Export obligations
-
-- Serialize only from canonical state plus preservation records.
-- Regenerate only editor-owned parts.
-- Reattach preserved parts, relationships, markup-compatibility structures, and opaque fragments.
-- Maintain package integrity for `[Content_Types].xml`, relationship graphs, and referenced part targets.
-- Surface export-block conditions before producing a document that would violate the compatibility contract.
-
-### Export outcomes by class
-
-For `supported-roundtrip`, export must:
-
-- serialize the feature back as valid OOXML
-- keep relationships and identifiers coherent
-- support Word reopen without repair prompts for the proven fixture set
-
-For `preserve-only`, export must:
-
-- re-emit preserved material without semantically rewriting it
-- keep the feature locked or outside editable scope in the runtime
-- warn before destructive actions that would delete or invalidate the preserved unit
-
-For `unsupported-fatal`, export must:
-
-- block export rather than emit a guessed or flattened representation
-- return actionable diagnostics
-
-## Preserve, lock, warn, block, fail matrix
-
-Wave 1 freezes the editor response model below.
-
-| Condition | Required behavior |
-| --- | --- |
-| Feature is `supported-roundtrip` and inside proven editing scope | Import semantically, allow editing, serialize natively, validate through fixture proof. |
-| Feature is `preserve-only` and does not intersect edits | Preserve and reattach without user-visible mutation of the preserved payload. |
-| Feature is `preserve-only` and is represented in the canonical story | Lock direct editing inside the feature; expose it only as an atomic placeholder. |
-| User action would delete a preserve-only opaque unit | Warn explicitly and require destructive confirmation; never treat as a silent delete. |
-| User action would require semantic rewriting of preserve-only content | Block the action or keep the document read-only for that region. |
-| Package or OOXML is malformed but still diagnosable | Fail safely with diagnostics and export blocked. |
-| Package or OOXML prevents trustworthy preservation | Fail import into read-only diagnostics mode or reject load; do not continue as editable. |
-
-## Compatibility and validation contract
-
-`CompatibilityReport` is a repo-owned TypeScript surface, not an SDK mirror. Wave 1 freezes the following obligations:
-
-- stable feature entries for supported and preserve-only findings
-- warnings for detachments, destructive-risk edits, and preserve-only constraints
-- errors for malformed packages, invalid relationships, and export blockers
-- `blockExport` as the authoritative export gate
-
-Validation layers remain:
-
-1. repo-owned structural and semantic checks in TypeScript
-2. Open XML SDK validation in CI and internal services
-3. manual Word reopen certification for representative fixtures
-
-The SDK may validate the package, parts, or elements, but it does not decide runtime transformations and does not ship in the browser bundle.
-
-## Feature-class baseline for v1
-
-### `supported-roundtrip`
-
-- paragraphs, runs, and text containers
-- significant whitespace, tabs, and hard line breaks
-- paragraph styles and heading style references
-- nested lists and restart numbering
-- inline images
-- hyperlinks
-- single-paragraph comments and threads within supported authoring scope
-- tracked insertions and deletions with accept or reject flows
-
-### `preserve-only`
-
-- body-level tables and merged-cell tables on the current live runtime path
-- multi-paragraph comment ranges
-- tracked moves
-- formatting revisions
-- structural table or list revisions
-- sections and section properties
-- headers and footers
-- footnotes and endnotes
-- fields
-- SDTs
-- custom XML wrappers and custom XML parts
-- `altChunk`
-- embedded objects
-- floating or unsupported drawings
-- `mc:AlternateContent`
-- unknown OOXML in document parts
-- unknown package parts and relationships
-
-### `unsupported-fatal`
-
-- malformed XML the importer cannot preserve safely
-- broken package graphs that prevent trustworthy reattachment
-- other package states the editor cannot validate or preserve without guesswork
-
-## Fixture proof program
-
-Wave 1 freezes F01-F21 as the minimum compatibility corpus.
-
-| Fixture | Primary contract target | Feature class focus | Proof-bearing wave(s) |
-| --- | --- | --- | --- |
-| F01 | Basic contract skeleton | `supported-roundtrip` text and whitespace baseline | Wave 3, Wave 10 |
-| F02 | Headings and styles contract | `supported-roundtrip` styles and headings baseline | Wave 3, Wave 10 |
-| F03 | Legal outline numbering | `supported-roundtrip` nested numbering | Wave 5, Wave 10 |
-| F04 | Restart numbering schedules | `supported-roundtrip` numbering restart and overrides | Wave 5, Wave 10 |
-| F05 | Table-heavy agreement | `preserve-only` table/package survival until first-class tables land | Wave 10, Wave 12 if promoted |
-| F06 | Merged-cells signature table | `preserve-only` merged-cell/package survival until first-class tables land | Wave 10, Wave 12 if promoted |
-| F07 | Inline images exhibit | `supported-roundtrip` media relationships | Wave 5, Wave 10 |
-| F08 | Hyperlinks exhibit list | `supported-roundtrip` hyperlinks and rel integrity | Wave 3, Wave 10 |
-| F09 | Comments anchored single paragraph | `supported-roundtrip` comment anchors | Wave 5, Wave 10 |
-| F10 | Threaded comments and resolve | `supported-roundtrip` comment threads and resolution metadata | Wave 5, Wave 10 |
-| F11 | Redlines basic | `supported-roundtrip` tracked insertions and deletions | Wave 6, Wave 10 |
-| F12 | Redlines paragraph joins/splits | `supported-roundtrip` revision boundary behavior | Wave 6, Wave 10 |
-| F13 | Comments on deleted text | supported behavior plus review-edge diagnostics | Wave 6, Wave 10 |
-| F14 | Revisions in tables and lists | `preserve-only` structural revisions | Wave 6, Wave 10 |
-| F15 | Sections + headers/footers | `preserve-only` out-of-band story survival | Wave 7, Wave 10 |
-| F16 | Footnotes and endnotes | `preserve-only` notes survival | Wave 7, Wave 10 |
-| F17 | Fields and TOC | `preserve-only` fields survival | Wave 7, Wave 10 |
-| F18 | Content controls template | `preserve-only` SDT survival and locking | Wave 7, Wave 10 |
-| F19 | Custom XML doc assembly | `preserve-only` custom XML survival and blocking rules | Wave 7, Wave 10 |
-| F20 | Unknown OOXML and AlternateContent | `preserve-only` opaque OOXML and markup compatibility preservation | Wave 7, Wave 10 |
-| F21 | Malformed/broken docx | `unsupported-fatal` fail-safe import and export blocking | Wave 7, Wave 10 |
-
-## Later-wave obligations frozen by this packet
-
-### Wave 3
-
-- Prove F01-F02 through fixture-backed import or export checks.
-- Land the first `CompatibilityReport` contract implementation.
-- Demonstrate package validation handoff to the validator service without pulling the SDK into runtime code.
-
-### Wave 4
-
-- Land the live shell and compatibility substrate without overclaiming structural baseline proof.
-
-### Wave 5
-
-- Prove F03-F04, F07-F10, and keep F05-F06 explicit as preserve-only table/package fixtures.
-- Show structural compatibility checks for supported-roundtrip list, image, hyperlink, and supported comment surfaces without overclaiming first-class table support.
-
-### Deferred Wave 12
-
-- Promote tables only after package-backed `import -> runtime edit -> export -> reload` proof exists on `F05` and `F06`.
-- Require mounted editor interaction proof, compatibility taxonomy proof, and linked Word reopen notes before tables re-enter `supported-roundtrip`.
-
-### Wave 6
-
-- Prove F11-F14.
-- Confirm that supported revision flows and preserve-only structural revisions do not drift across taxonomy boundaries.
-
-### Wave 7
-
-- Prove F15-F21.
-- Include survival checks for preserve-only package parts and explicit export blocking for malformed packages.
-
-### Wave 8
-
-- Prove the internal harness upload and validation path without widening the frozen F01-F21 taxonomy.
-
-### Wave 9
-
-- Prove selected end-to-end fixture and scenario runs on Railway against the same OOXML taxonomy and validator rules.
-
-### Wave 10
-
-- Re-run the full F01-F21 regression and Word certification bundle as the authoritative v1 closure proof.
-
-## Interface impacts
-
-| Surface | Owner | Exact impact |
-| --- | --- | --- |
-| `src/io/*` | A3 | Keep import and export package-first with no HTML intermediary and no UI dependency. |
-| `src/preservation/store.ts` | A3 | Preserve fragment records with `fragmentId`, source payload, `lastKnownRange`, and feature-class metadata. |
-| `src/validation/compatibility-report.ts` | A3 | Expose stable feature entries, warnings, errors, and `blockExport`. |
-| `docs/reference/ooxml-compliance.md` | A3 | Reflect the 3-class taxonomy and validation-only SDK policy. |
-| `test/fixtures/docx/README.md` | A3 | Freeze fixture IDs F01-F21, their class focus, and proof-bearing waves. |
-
-## Proof expectations for this wave
-
-Wave 1 only freezes the contract. It does not claim runtime implementation of import, export, preservation, or validation logic.
-
-Durable proof for A3 in Wave 1 is:
-
-- landed owned docs
-- exact fixture-to-wave proof mapping
-- exact preserve/lock/warn/block/fail rules
-- explicit SDK policy and package-first boundaries