@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/docs/plans/operations/wave-8-railway-staging.md

@@ -1,153 +0,0 @@
-# Wave 8 Railway Staging Runbook
-
-This runbook is the operator-facing early-access note for the harness baseline and validator pilot wave.
-
-Status note:
-
-- the early-access run captured useful historical artifacts, but it is not the current closure line
-- Wave 8 now requires a fresh private-mode deploy plus proof recapture before the harness and validator promotions can stand again
-
-## Scope
-
-- Railway staging deploy for `react-word-editor`
-- private-network validation path to `openxml-validator`
-- artifact capture for harness and validator status
-- operator proof through `/fixtures`, `/editor/[sessionId]`, and `/runs/[runId]`
-
-## Scope Guard
-
-Wave 8 only proves staging deployability, validator connectivity, and durable artifact capture for the non-production operator harness.
-
-Not yet sufficient for the next wave:
-
-- UI screenshots without stored validation artifacts
-- deploy health without a real validator roundtrip
-
-## Railway Environment Naming Delta
-
-The Wave 8 proof ran against the Railway `early-access` environment, not `staging`.
-Service names in this environment differ from the names used in the original plan:
-
-| Role             | Planned name         | Actual Railway name                      |
-|------------------|----------------------|------------------------------------------|
-| Harness service  | `react-word-editor`  | `docx-react-component`                   |
-| Validator service| `openxml-validator`  | `openxml-validator`                      |
-| Project          | _(unspecified)_      | `Fabric`                                 |
-| Environment      | `staging`            | `early-access`                           |
-
-Public base URLs for the early-access environment:
-
-- Harness: `https://docx-react-component-early-access.up.railway.app`
-- Validator: `https://openxml-validator-early-access.up.railway.app`
-
-Operators must use these names when using `railway service` commands or referencing
-deployment IDs from `railway deployment list`.
-
-## Required Harness Routes
-
-- `GET /api/health`
-- `POST /api/uploads`
-- `POST /api/exports`
-- `POST /api/validate`
-- `GET /api/runs/[runId]`
-
-The live review-save-validate proof must come from the mounted runtime path, not the `/demo`
-prototype route.
-
-## Required Railway Variables
-
-The following environment variables must be set in the Railway service settings before deploy.
-None of these values are baked into the Docker image at build time.
-
-| Variable                      | Required | Expected value (early-access)                    |
-|-------------------------------|----------|--------------------------------------------------|
-| `PORT`                        | yes      | `3000`                                           |
-| `OPENXML_VALIDATOR_BASE_URL`  | yes      | `http://openxml-validator.railway.internal:8080` |
-| `HARNESS_STORAGE_DIR`         | yes      | `/data/react-word-editor-harness` (volume mount) |
-
-`OPENXML_VALIDATOR_BASE_URL` must use the private Railway internal hostname, not the public
-domain. The browser must never call the private validator host directly.
-
-## Storage And Networking Notes
-
-- `HARNESS_STORAGE_DIR` should point at a Railway volume mount
-- `OPENXML_VALIDATOR_BASE_URL` should point at the private validator service, typically
-  `http://openxml-validator.railway.internal:8080`
-- the browser must never call the private validator host directly
-- retention checks must record stored upload, export, and validation artifact counts before
-  the wave is treated as closed
-
-## Restart Expectations
-
-The harness (`docx-react-component`) is configured with:
-
-- `restartPolicyType: ON_FAILURE`
-- `restartPolicyMaxRetries: 10`
-- `healthcheckPath: /`
-- `healthcheckTimeout: 60s`
-
-The validator (`openxml-validator`) does not yet have an explicit `railway.json`. Railway
-uses default restart behavior. Operators should treat unexpected restarts or redeploy
-attempts as expected during early-access and verify live health rather than relying on
-deployment status alone.
-
-## Retention Checks
-
-Wave 8 retention assumptions captured via `GET /api/health`:
-
-- upload cap: `20 MiB` per file
-- export artifact limit: `100` stored exports
-- validation run limit: `200` stored validation snapshots
-- fixture and scenario source records are repo-backed and never copied to the volume
-
-Before treating the wave as closed, operators must confirm:
-
-1. The `HARNESS_STORAGE_DIR` volume is mounted and `GET /api/health` reports `mode: configured-volume-path`
-2. Upload, export, and validation artifact counts are within limits
-3. A full review-save-validate run completes and stores all three artifact types durably
-
-The Wave 8 retention check evidence is at `.tmp/wave-8-railway-pilot/artifact-retention-check.json`.
-
-## Validator Status Drift Rule
-
-Railway CLI deployment status for `openxml-validator` can lag or drift from observed live behavior
-after restarts or redeploy attempts.
-
-Operators should treat the service as healthy for Wave 8 proof only when all three surfaces agree:
-
-- the current public `/health` endpoint responds successfully
-- the harness `GET /api/health` validator bridge reports `status: ok`
-- a current harness-backed validation request succeeds
-
-If the latest `railway deployment list` entry shows `FAILED` but those three live checks stay
-green, treat the live health and validation artifacts as authoritative and record the CLI drift in
-the proof note instead of declaring the validator down.
-
-### Wave 8 Drift Evidence
-
-During Wave 8 proof, the validator showed status drift on both pre-restart and post-restart checks:
-
-- Pre-restart deployment `07fd278f` showed `FAILED` while `/health` returned `ok`
-- Post-restart deployment `c42c4ce4` also showed `FAILED` while live traffic remained healthy
-
-This is recorded in:
-
-- `.tmp/wave-8-railway-pilot/validator-status-before-restart.json`
-- `.tmp/wave-8-railway-pilot/validator-status-after-restart.json`
-
-The mounted harness proof (`mounted-review-proof.json`) used the live validator traffic as
-authoritative and is not invalidated by the CLI status drift.
-
-## openxml-validator Build Context
-
-The `services/openxml-validator/Dockerfile` uses COPY paths relative to the repository root:
-
-```
-COPY services/openxml-validator/OpenXmlValidator.Api.csproj ./
-COPY services/openxml-validator/. ./
-```
-
-Railway must be configured to build this service with the repository root as the Docker build
-context, not `services/openxml-validator/` as the context. Without a `railway.json` for the
-validator service, this requires manual Railway project configuration or an explicit Dockerfile
-path setting in the Railway service UI pointing to the repo-root build context.

package/docs/plans/operations/wave-9-manual-certification.md

@@ -1,73 +0,0 @@
-# Wave 9 Manual Certification Notes
-
-This runbook records the operator expectations for the internal pilot-live editor loop and the
-manual certification capture surface at `/certification`.
-
-## Purpose
-
-The certification surface exists to keep Word desktop and Word web observations attached to exact
-harness evidence instead of ad-hoc chat notes.
-
-Each stored note must point at one of:
-
-- a concrete validation run id
-- a concrete export artifact id
-
-The page keeps the two review surfaces separate:
-
-- `Word Desktop`
-- `Word Web`
-
-It also keeps `not yet reviewed` distinct from `reviewed and passed`.
-
-## Required pilot checks
-
-- run selected release-gate fixtures through the Railway harness
-- run both representative scenarios `S01` and `S02` through the same harness flow
-- capture validator output for exported artifacts
-- record Word reopen observations against concrete run ids or export ids
-
-## Operator workflow
-
-1. Launch or review a stored harness session under `/editor/[sessionId]`.
-2. Export the document when needed and persist the artifact.
-3. Capture validator output for the relevant export through the harness.
-4. Open `/certification`.
-5. Choose either the exact validation run card or the exact export artifact card.
-6. Record one note per review surface with:
-   - operator name or initials
-   - observed timestamp
-   - surface (`Word Desktop` or `Word Web`)
-   - outcome (`Reviewed And Passed`, `Issues Found`, or `Not Yet Reviewed`)
-   - concise evidence summary
-   - optional follow-up notes
-
-## Evidence rules
-
-- Prefer run-linked notes when the observation depends on a stored validator snapshot.
-- Use export-linked notes when the observation is about a specific saved package reopen.
-- Do not write a certification note without a concrete target id.
-- Do not treat validator-clean as Word reopen proof by itself.
-- If a surface has not been checked, leave it pending or explicitly set `Not Yet Reviewed`.
-
-## Stored fields
-
-Each certification record stores:
-
-- certification id
-- target type and target id
-- related run id, export id, session id, and source id when resolvable
-- file name and source label
-- operator
-- surface
-- outcome
-- evidence summary
-- optional notes
-- observed timestamp
-- validator snapshot counts when the target is a validation run
-
-## Trust boundaries
-
-- harness validation remains machine evidence, not Word reopen proof
-- manual certification is operator evidence and must stay linked to the exact artifact it describes
-- use the stored ids in `.tmp/wave-9-pilot/` proof bundles so pilot claims can be traced back to the harness

package/docs/plans/platform/README.md

@@ -1,9 +0,0 @@
-# Platform Plans
-
-This directory is reserved for shared OOXML platform planning material.
-
-Current umbrella planning still lives primarily in:
-
-- `docs/plans/master-plan.md`
-- `docs/architecture/platform/shared-openxml-editor-platform.md`
-- `docs/reference/platform/shared-ooxml-platform-guidance.md`

package/docs/plans/reference/legal-checklist-coverage.md

@@ -1,258 +0,0 @@
-# Legal Checklist Coverage
-
-## Purpose
-
-This document maps the legal review checklist items from `docs/reference/legal-checklist.md` to current implementation status and future wave planning. It serves as the authoritative coverage matrix for post-v1 legal-fidelity work.
-
-## Methodology
-
-Each checklist element is evaluated against:
-- **Current implementation status** - what works today
-- **Fidelity layer achieved** - Layer 0 (visual) through Layer 5 (round-trip parity)
-- **Fixture evidence** - which test fixtures prove the capability
-- **Component ownership** - which components handle the feature
-- **Gap analysis** - what remains unimplemented
-- **Future wave assignment** - when gaps will be addressed
-
-## Current Status Summary (Post Wave 18)
-
-### Tier A - Must-have before calling it legal review
-
-| Element | Target Layer | Current Status | Current Layer | Evidence | Wave |
-|---------|--------------|----------------|---------------|-----------|------|
-| Track changes / redlines | 5 | ✅ **SUPPORTED** | 5 | F11, F12, F13 | ✅ Complete |
-| Comments and comment threads | 5 | ✅ **SUPPORTED** | 5 | F09, F10 | ✅ Complete |
-| Paragraphs and character runs | 5 | ✅ **SUPPORTED** | 5 | F01, F02 | ✅ Complete |
-| Headings and numbered clauses | 5 | ✅ **SUPPORTED** | 5 | F02, F03, F04 | ✅ Complete |
-| Lists and nested numbering | 5 | ✅ **SUPPORTED** | 5 | F03, F04 | ✅ Complete |
-| Tables | 5 | 🔒 **PRESERVE_ONLY** | 3 | F05, F06 | 📅 Wave 12 |
-| Versions / snapshots / compare | 5 | ❌ **DEFERRED** | 0 | None | 📅 Wave 13 |
-
-**Tier A Assessment**: ✅ **MEETS LEGAL REVIEW CRITERIA**
-- 6/7 elements fully supported or appropriately preserve-only
-- Tables preserve-only with clear Wave 12 promotion path
-- Version management is planned for Wave 13
-
-### Tier B - Must-have before calling it a serious legal platform
-
-| Element | Target Layer | Current Status | Current Layer | Evidence | Wave |
-|---------|--------------|----------------|---------------|-----------|------|
-| Cross-references | 4-5 | ❌ **DEFERRED** | 1 | None | 📅 Wave 14 |
-| Defined terms | 4 | ❌ **DEFERRED** | 1 | None | 📅 Wave 14 |
-| Bookmarks / anchors | 4 | 🔒 **PRESERVE_ONLY** | 2 | F09, F10 | 📅 Wave 14 |
-| Sections / page setup | 4 | 🔒 **PRESERVE_ONLY** | 3 | F15 | 📅 Wave 15 |
-| Footnotes / endnotes | 4 | 🔒 **PRESERVE_ONLY** | 3 | F16 | 📅 Wave 15 |
-| Headers / footers | 3-4 | 🔒 **PRESERVE_ONLY** | 3 | F15 | 📅 Wave 15 |
-| Images / shapes / text boxes | 2-3 | ⚠️ **PARTIAL** | 3 | F07 | 📅 Wave 15 |
-| Fields / content controls | 4 | 🔒 **PRESERVE_ONLY** | 2 | F17, F18 | 📅 Wave 15 |
-| Metadata / document properties | 4 | ❌ **DEFERRED** | 1 | None | 📅 Wave 14 |
-| Permissions / locks | 4 | ❌ **DEFERRED** | 1 | None | 📅 Wave 15 |
-| Styles | 4-5 | ⚠️ **PARTIAL** | 4 | F02 | 📅 Wave 14 |
-| Signature blocks | 4 | ❌ **DEFERRED** | 1 | None | 📅 Wave 15 |
-
-**Tier B Assessment**: 📅 **POST-V1 PLANNED WORK**
-- All elements have clear wave assignments
-- Foundation exists for most features (preservation/anchoring)
-- Legal semantics (Wave 14) and authoring (Wave 15) will complete this tier
-
-### Tier C - Completeness and interoperability hardening
-
-| Element | Target Layer | Current Status | Current Layer | Evidence | Wave |
-|---------|--------------|----------------|---------------|-----------|------|
-| Hyperlinks | 3 | ✅ **SUPPORTED** | 4 | F08 | ✅ Complete |
-| Revisions to formatting | 4 | ✅ **SUPPORTED** | 4 | F11, F12 | ✅ Complete |
-| Move tracking | 3-4 | ❌ **DEFERRED** | 0 | None | 📅 Wave 15 |
-| Pagination artifacts | 3 | 🔒 **PRESERVE_ONLY** | 3 | F15 | 📅 Wave 16 |
-| TOC / generated indexes | 2-3 | 🔒 **PRESERVE_ONLY** | 2 | F17 | 📅 Wave 16 |
-
-**Tier C Assessment**: ✅ **LARGELY COMPLETE**
-- Core interoperability features working
-- Remaining items are lower priority enhancements
-
-### Tier D - Explicitly de-prioritized
-
-| Element | Target Layer | Current Status | Current Layer | Evidence | Wave |
-|---------|--------------|----------------|---------------|-----------|------|
-| Embedded objects / OLE | 1-2 | 🔒 **PRESERVE_ONLY** | 1 | F20 | ✅ By design |
-| Macros / advanced Word automation | 0-1 | ❌ **BLOCKED** | 0 | None | ✅ By design |
-
-**Tier D Assessment**: ✅ **APPROPRIATE EXCLUSION**
-- Security-appropriate blocking of macros
-- OLE preservation meets interoperability needs
-
-## Detailed Feature Analysis
-
-### Currently Supported (Fleet-Ready)
-
-These features have achieved their target fidelity layers and are proven through fixture validation:
-
-#### Text and Structure (Layer 5)
-- **Paragraphs and character runs**: Stable run segmentation, formatting preservation, anchor-safe editing
-- **Headings and numbered clauses**: Hierarchy preservation, automatic renumbering, stable identity
-- **Lists and nested numbering**: Multi-level lists, restart semantics, redline behavior
-- **Evidence**: F01, F02, F03, F04 provide comprehensive proof
-
-#### Review Workflow (Layer 5)  
-- **Track changes**: Insert/delete tracking, formatting revisions, accept/reject, author attribution
-- **Comments**: Anchored comments, threading, resolution, export preservation
-- **Evidence**: F09, F10, F11, F12, F13 provide comprehensive proof
-
-#### Media and Links (Layer 4-5)
-- **Hyperlinks**: External links, preservation, basic editing
-- **Inline images**: Media part handling, relationship integrity
-- **Evidence**: F07, F08 provide baseline proof
-
-### Preserve-Only (Appropriate for V1)
-
-These features are correctly handled through preservation mechanisms:
-
-#### Complex Structure
-- **Tables**: Package-backed survival, locked display, no semantic corruption
-  - *Gap*: First-class table editing (Wave 12 scope)
-  - *Evidence*: F05, F06 prove preserve-only fidelity
-
-#### Document Infrastructure
-- **Sections**: Section breaks, page setup, header/footer preservation
-- **Notes**: Footnote/endnote content and anchoring
-- **Fields**: Field codes, TOC structures, content controls
-  - *Gap*: Active editing of these elements (Wave 15 scope)
-  - *Evidence*: F15, F16, F17, F18 prove preservation
-
-#### Unknown Content
-- **Custom XML**: Custom parts and wrapper preservation
-- **Unknown OOXML**: AlternateContent, unknown namespaces, forward compatibility
-  - *Evidence*: F19, F20 prove preservation mechanisms
-
-### Explicitly Deferred (Post-V1 Scope)
-
-These features are not implemented but have clear wave assignments:
-
-#### Legal Semantics (Wave 14)
-- **Cross-references**: Structural references, live updates, navigation
-- **Defined terms**: Definition detection, usage linking, consistency checking  
-- **Styles**: Advanced style management, validation, template support
-- **Metadata**: Document properties, workflow context, status tracking
-- **Bookmarks**: Named anchor management, stable cross-references
-
-#### Structured Authoring (Wave 15) 
-- **Permissions**: User roles, section locks, controlled collaboration
-- **Content controls**: Editable fields, validation rules, template binding
-- **Advanced review**: Move tracking, complex permissions, advanced workflows
-- **Signature blocks**: Protected layout, workflow integration
-
-#### Document Shell (Wave 16)
-- **Complete pagination**: Page breaks, keep-together, widow/orphan control
-- **Generated content**: Live TOC, index generation, cross-reference updates
-- **Export fidelity**: Print preview, PDF generation, full document shell
-
-## Wave Planning Integration
-
-### Wave 12: First-Class Tables
-**Target**: Layer 5 table editing
-- Stable table identity and cell addressing
-- Table-aware selection and editing  
-- Redlines and comments in table context
-- Merged cell editing support
-
-**Prerequisites**: Current preserve-only foundation (F05, F06)
-
-### Wave 13: Versions and Compare
-**Target**: Layer 5 version management  
-- Document snapshots and version history
-- Side-by-side comparison views
-- Merge conflict resolution
-- Signing workflow integration
-
-**Prerequisites**: Stable document model and review system
-
-### Wave 14: Legal Semantics
-**Target**: Layer 4 legal-aware features
-- Cross-reference system with live updates
-- Defined terms detection and linking
-- Advanced style management
-- Document metadata and properties
-
-**Prerequisites**: Stable authoring foundation
-
-### Wave 15: Structured Authoring  
-**Target**: Layer 4 controlled collaboration
-- User permissions and section locks
-- Content control editing
-- Advanced review workflows
-- Signature block management
-
-**Prerequisites**: Legal semantics foundation
-
-### Wave 16: Document Shell Completeness
-**Target**: Layer 3-4 complete document lifecycle
-- Full pagination control
-- Generated content management  
-- Complete export fidelity
-- Integration proof across all waves
-
-**Prerequisites**: All previous post-v1 waves
-
-## Quality Gates
-
-### Fleet-Ready Criteria (Met)
-✅ All Tier A elements supported or preserve-only with clear promotion path  
-✅ Critical review workflows (comments, track changes) at Layer 5  
-✅ Word round-trip compatibility proven  
-✅ Preserve-only boundaries clearly defined and documented  
-
-### Legal Platform Criteria (Post-V1)
-📅 All Tier B elements at target layers (Waves 14-15)  
-📅 Cross-reference system with live updates  
-📅 Legal semantics for terms, styles, metadata  
-📅 Controlled collaboration with permissions  
-
-### Completeness Criteria (Wave 16)
-📅 All post-v1 waves integrated  
-📅 Full document lifecycle supported  
-📅 Export fidelity across all use cases  
-📅 Legal-grade validation and workflows  
-
-## Risk Assessment
-
-### Low Risk (Current State)
-- **Supported features** have strong fixture proof and Word compatibility
-- **Preserve-only features** maintain round-trip fidelity without semantic corruption
-- **Explicit gaps** are clearly documented and planned
-
-### Medium Risk (Future Waves)
-- **Table editing integration** (Wave 12) requires careful coordination with review system
-- **Compare system** (Wave 13) needs robust conflict resolution
-- **Legal semantics** (Wave 14) must maintain Word compatibility
-
-### Mitigation Strategies
-- Maintain fixture-based regression testing
-- Preserve current supported-roundtrip boundaries during expansion  
-- Validate Word compatibility at each wave milestone
-- Keep preserve-only fallbacks for complex edge cases
-
-## Usage Guidelines
-
-### For Product Planning
-- Use this matrix to set appropriate user expectations
-- Reference specific wave timelines for feature requests
-- Maintain preserve-only boundaries in user documentation
-
-### For Development
-- Do not claim Layer 5 support without fixture proof
-- Maintain Word compatibility as primary gate  
-- Update this document when feature boundaries change
-
-### For QA Validation
-- Use fixture evidence as primary validation criteria
-- Verify preserve-only boundaries prevent data corruption
-- Test Word round-trip for all supported features
-
-## Updates
-
-This document should be updated when:
-- Component maturity levels change significantly
-- New fixture evidence becomes available  
-- Wave scope or timelines are revised
-- Word compatibility requirements change
-
-Last updated: Wave 18 (2026-03-29) - Fleet-ready promotion validation