chain: feat(architecture): radical translation OOXML library — Word↔Swift edit-isomorphism

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Summary
+
+<!-- What does this PR change? -->
+
+## Test Plan
+
+<!-- How can the change be verified? -->
+
+## Edit Algebra (only if PR touches packages/ooxml-swift/Sources/OOXMLSwift/EditAlgebra/)
+
+- [ ] PR introduces or modifies an `OOXMLEdit` / `WordEdit` enum case
+- [ ] ASCII-ladder commutative diagram is attached to this PR description below, OR added inline in design.md / spec.md
+- [ ] CD diagram shows: (1) Word UI action or schema-level change, (2) `τ` translation between Word semantics and Swift representation, (3) commutativity claim
+
+(CD discipline rationale: see `ooxml-edit-isomorphism-foundation` design.md § ADR-002 Worked Examples and `docs/edit-algebra-cd-discipline.md`.)
+
+## Related Issues
+
+Refs #

docs/edit-algebra-cd-discipline.md

@@ -0,0 +1,82 @@
+# `EditAlgebra/` — Edit Type Contract
+
+This directory is the runtime home for the **Word↔Swift edit-isomorphism** contract pinned in Spectra change `ooxml-edit-isomorphism-foundation` (see `openspec/changes/ooxml-edit-isomorphism-foundation/`).
+
+## What lives here
+
+When the deferred Phase 2 implementation Spectra change lands, this directory will contain:
+
+- `Edit.swift` — `Edit` protocol declaring `apply(to:) throws -> Document` and `lower() -> [OOXMLEdit]`; plus `EditError` enum
+- `OOXMLEdit.swift` — syntactic-layer enum (cases address OOXML elements by path)
+- `WordEdit.swift` — semantic-layer enum (cases address Word UI verbs)
+
+Currently this directory holds only this README. The Edit type is documented as a normative contract via the Spectra change's spec; runtime files arrive when the implementation Spectra change executes (see "Status" below).
+
+## CD discipline (PR review gate)
+
+**Every PR introducing a new `OOXMLEdit` or `WordEdit` enum case SHALL attach a commutative diagram + commute proof.** This is non-negotiable; reviewers reject PRs without a CD diagram.
+
+### Why CD discipline
+
+Per `ooxml-edit-isomorphism-foundation` design.md § ADR-002, commutative diagrams give us six concrete affordances that pure `Edit` typing alone doesn't:
+
+1. **Verification spec generator** — each Edit case `e` gets a testable obligation `τ(e_word(s)) == e_swift(τ(s))` for all states `s`
+2. **Documentation standard** — PR includes an ASCII ladder (IETF-RFC style) so future maintainers can see the design intent
+3. **Test generator** — property tests `∀s. f₁(s) == f₂(s)` derive directly from the two CD paths
+4. **Incompatibility-surface detector** — when a CD can't be drawn cleanly, the Edit has hidden state or a cross-layer leak that must be addressed before merge
+5. **Compositional reasoning** — `e₁ ∘ e₂`'s CD = paste `e₁`'s + `e₂`'s
+6. **Cross-layer cube** — two-layer algebra maps to a 3D CD; the 6 faces must commute
+
+### How to draw a CD diagram
+
+Use ASCII-art ladder format, modeled on IETF RFCs. Show:
+
+1. The **Word UI action** that the Edit case corresponds to (top row, for `WordEdit`) or the **OOXML schema-level change** (top row, for `OOXMLEdit`)
+2. The **τ translation** (vertical arrow labels) between Word UI semantics and Swift representation
+3. The **commutativity claim** (two paths from input state to output state must reach the same destination)
+
+Example for `OOXMLEdit.setBold`:
+
+```
+                  Word UI action: Cmd-B on selected text
+            ┌─────────────────────────────────────────────┐
+            │                                             │
+   docx_in ─┼──────────────────────────────────────────► docx_out
+            │   "type 'hello' then select + Cmd-B"        │
+            │                                             │
+          τ │                                             │ τ
+            │                                             │
+            ▼                                             ▼
+   swift_in ─────────────────────────────────────────► swift_out
+                  Document.apply(OOXMLEdit.setBold(at: runPath, value: true))
+
+CD obligation:
+  τ(docx_out) == swift_out  (i.e., applying setBold on the Swift side
+  produces the same state τ-equivalent to Word's behavior)
+```
+
+### Worked examples
+
+See `openspec/changes/ooxml-edit-isomorphism-foundation/design.md` § ADR-002 *Worked Examples* for fleshed-out CD diagrams for:
+
+- `OOXMLEdit.insertParagraph(at:content:)` (body-level mutation, straightforward CD)
+- `OOXMLEdit.setBold(at:value:)` (run-level mutation, requires rPr handling)
+- `OOXMLEdit.insertHyperlink(at:href:)` (dual-part mutation requiring relationship-part update — non-trivial CD)
+- `WordEdit.applyBold(range:)` with range-crossing-paragraph case (boundary-ambiguity CD: `lower()` produces multiple OOXMLEdit cases)
+
+## Status
+
+This Edit type contract is currently in **decision-pinning state**: the Spectra change `ooxml-edit-isomorphism-foundation` has shipped its proposal / design.md (9 ADRs) / spec.md (8 Requirements) / tasks.md (35 tasks). Runtime implementation (Edit protocol code, OOXMLEdit / WordEdit enum cases, property tests) is deferred to a Phase 2 follow-up Spectra change that cites this foundation.
+
+Downstream consumers:
+
+- `che-word-mcp` (#162) — MCP tool surface refactor to `WordEdit` (deferred per ADR-009)
+- `word-builder-swift` (#101) — lens-model migration (deferred per ADR-008)
+- macdoc PR #94 / #95 / #96 / #97 / #98 — re-framing to Layer 3 / 4 front-ends (deferred per ADR-009; tracking issues #102 / #103 / #104)
+
+## Related documents
+
+- Spectra change: `openspec/changes/ooxml-edit-isomorphism-foundation/`
+- Capability spec: `openspec/changes/ooxml-edit-isomorphism-foundation/specs/ooxml-edit-algebra/spec.md`
+- Prior-art docs: `docs/lossless-conversion.md`, `docs/structural-editing-paradigm.md`, `docs/functional-correspondence.md`
+- Active runtime change: `openspec/changes/word-aligned-state-sync/` (provides the event-sourced runtime mechanism this contract types over)

docs/lossless-conversion.md

@@ -962,3 +962,9 @@ W ↔ Marker（Tier 3 Bijection）：全部 Word 的完美可逆
 4. **Metadata 無上限** — 任何讓 round-trip break 的遺漏都是 bug，不是「可接受的妥協」
 5. **Streaming 兼容** — 三通道平行輸出，O(1) 記憶體
 6. **使用者選擇** — 有損是刻意的選擇（Tier 1/2），不是設計缺陷
+
+## Related: ooxml-edit-algebra capability
+
+The canonical-identity round-trip contract described in §0 is formalized as a normative Requirement in the `ooxml-edit-algebra` capability spec at `openspec/changes/ooxml-edit-isomorphism-foundation/specs/ooxml-edit-algebra/spec.md`. See `ooxml-edit-isomorphism-foundation` design.md § ADR-001 for the contract rationale and the chosen invariant (canonical-identity over byte-identity over semantic-equivalence).
+
+This document remains the formal-systems reference; the capability spec is the implementation-binding contract.

docs/structural-editing-paradigm.md

@@ -410,3 +410,10 @@ tracked as separate follow-up SDD。這些落地後 loss 預期 drop 到 < 5%，
 屆時可以正式 ship 第 6.1 節「edit 一個字 → document.xml shrinks <1%」strong demo。
 
 到時候第 6.1 節的「edit 一個字 → document.xml shrinks <1%」claim 就可以正式落地。
+
+
+## Related: ooxml-edit-algebra capability
+
+The architectural patterns described here (overlay save, dirty-tracking, Invariants 1+2, 5 preservation classes) are typed and formally contracted in the `ooxml-edit-algebra` capability spec at `openspec/changes/ooxml-edit-isomorphism-foundation/specs/ooxml-edit-algebra/spec.md` (see Spectra change `ooxml-edit-isomorphism-foundation` for the 9 ADRs that pin the contract).
+
+This document remains the implementation-pattern reference; the capability spec is the normative contract.

openspec/changes/ooxml-edit-isomorphism-foundation/.openspec.yaml

@@ -0,0 +1,4 @@
+schema: spec-driven
+created: 2026-05-25
+created_by: che cheng <kiki830621@gmail.com>
+created_with: claude