Spectra: ooxml-edit-algebra-implementation — Phase 2 runtime of #99 by kiki830621 · Pull Request #109 · PsychQuant/macdoc

kiki830621 · 2026-05-31T12:01:03Z

Summary

Creates Spectra change ooxml-edit-algebra-implementation — the Phase 2 runtime that the foundation change #99 decision-pinned. Adds 5 artifacts to openspec/changes/ooxml-edit-algebra-implementation/:

proposal.md — scope: Edit protocol + OOXMLEdit/WordEdit enums + WordDocument.apply public API
design.md — 6 Decisions (see below)
tasks.md — 10 task groups with §1+§2+§3.1+§3.2+§4.1+§6.1 marked COMPLETE; §3.3+§4.2+§6.2 marked UNBLOCKED + SHIPPED
specs/ooxml-edit-algebra-runtime/spec.md — 8 ADDED Requirements with SHALL/MUST, Scenarios, SBE Examples
.openspec.yaml — change metadata

Docs-only PR. Implementation code ships in separate ooxml-swift PRs (linked below).

Design Decisions (in design.md)

Edit↔Operation mapping table — the central design artifact pinning how each OOXMLEdit case lowers to one or more Operation enum cases
WordEdit↔OOXMLEdit mapping per foundation ADR-003 — three WordEdit cases (applyBold, applyLink, applyInsertParagraph) each lower to a list of OOXMLEdit
WordDocument owns OperationLog (Option A) — rejected Option D (separate EditableDocument wrapper) after user feedback that bifurcating the type surface obscures "same parser, same Word understanding"
EditError shape — 5 cases (pathNotFound, preserveViolation, unsupportedOperation, notImplemented, operationLogFailure)
swift-testing @test(arguments:) for property tests
(Errata to Decision 3) End-to-end Edit-apply tests deferred behind OpLog Phase 2c — OperationReducer currently handles only setText/setParagraphStyle/markers; tree-mutating Operations throw malformedOp. Filed PsychQuant/ooxml-swift#71. STATUS UPDATE: critical-path Phase 2c cases shipped via ooxml-swift PR #72 — e2e tests for insertParagraph/insertParagraphBefore/setBold/removeParagraph now functional on synthesized single-part documents.

Implementation status (across linked PRs)

Task group	Status	Code ships in
§1 Edit protocol + EditError + enum scaffold	✅ DONE	ooxml-swift `idd/105-edit-algebra-runtime`
§2 Document.apply public API	✅ DONE	ooxml-swift `idd/105-edit-algebra-runtime`
§3.1+§3.2 insertParagraph emission	✅ DONE	ooxml-swift `idd/105-edit-algebra-runtime`
§3.3 insertParagraph e2e	✅ DONE (synthesized)	ooxml-swift `idd/105-edit-algebra-runtime` (depends on ooxml-swift#72)
§4.1 setBold emission	✅ DONE	ooxml-swift `idd/105-edit-algebra-runtime`
§4.2 setBold e2e	✅ DONE (synthesized)	ooxml-swift `idd/105-edit-algebra-runtime`
§6.1 removeParagraph emission	✅ DONE	ooxml-swift `idd/105-edit-algebra-runtime`
§6.2 removeParagraph e2e	✅ DONE (synthesized)	ooxml-swift `idd/105-edit-algebra-runtime`
§5 insertHyperlink	⏸ PENDING (composite-design checkpoint)	—
§7 WordEdit lower()	⏸ TODO	—
§8 property tests	⏸ TODO	—
§9 naturality tests	⏸ TODO	—
§10 verification + CD diagrams	⏸ TODO	—
Multi-part scoping fix (WordDocument+Apply.swift)	⏸ TODO (blocks real-.docx fixture tests)	—

40+ tests across 4 EditAlgebra test files (EditProtocol, DocumentApply, InsertParagraph, SetBold, RemoveParagraph, InsertParagraphE2E) + 17 Phase 2c reducer tests. 1034 tests pass on the merged ooxml-swift branch.

Architectural milestone

The full chain Edit → lower → operations → log → materialize → new WordDocument now mutates xmlTrees end-to-end on synthesized documents. The macdoc#99 ADRs are empirically validated, not just decision-pinned.

Linked work

PsychQuant/ooxml-swift#71 — OpLog Phase 2c blocker (issue)
PsychQuant/ooxml-swift#72 — Phase 2c reducer critical-path cases (PR, ready to merge)
ooxml-swift branch idd/105-edit-algebra-runtime — Edit algebra emission + e2e tests (depends on 建立 CLI 指令規範檔（cli-spec.yaml）作為所有指令的 single source of truth #72 being merged; PR opens after 建立 CLI 指令規範檔（cli-spec.yaml）作為所有指令的 single source of truth #72 lands so Spectra: ooxml-edit-algebra-implementation (Phase 2 — Edit type runtime + property tests, per ooxml-edit-isomorphism-foundation) #105 branch can rebase cleanly)

Test plan

All Spectra artifacts created with correct YAML frontmatter + cross-references
design.md Decision 6 errata documents the OpLog Phase 2c discovery
tasks.md status accurately reflects completed/pending/blocked work
spec.md ADDED Requirements use SHALL/MUST with Scenarios + SBE Examples
Spectra spectra validate ooxml-edit-algebra-implementation passes (will run before merging)

Refs #105
Refs #99

@test

Phase 2 of ooxml-edit-isomorphism-foundation (#99): ship the Swift runtime that the foundation's ADRs pinned. Splits into: - proposal.md — scope: Edit protocol + OOXMLEdit/WordEdit enums + WordDocument.apply public API. - design.md — 6 Decisions: 1. Edit↔Operation mapping table (the central design artifact) 2. WordEdit↔OOXMLEdit mapping (per foundation ADR-003) 3. WordDocument owns OperationLog (Option A; rejected EditableDocument wrapper after user pushback re: type-surface bifurcation) 4. EditError shape (5 cases) 5. swift-testing @test(arguments:) for property tests 6. (NEW errata) End-to-end Edit-apply tests deferred behind OpLog Phase 2c — OperationReducer currently handles only setText/ setParagraphStyle/markers; all tree-mutating Operations throw malformedOp. File ooxml-swift issue for Phase 2c reducer cases before unblocking §3.3 / §8 / §9. - tasks.md — 10 task groups; §1+§2+§3.1+§3.2 marked done. - specs/ooxml-edit-algebra-runtime/spec.md — 8 ADDED Requirements with SHALL/MUST, Scenarios, SBE Examples. Tracks PsychQuant/ooxml-swift work on branch idd/105-edit-algebra-runtime: - §1 scaffold (Edit protocol + EditError + 5 OOXMLEdit cases + 3 WordEdit cases) — 9 tests, committed earlier in session - §2 Document.apply pipeline wiring + operationLog field — 9 tests, committed earlier in session - §3.1+§3.2 insertParagraph emission — 7 tests, this commit 25 ooxml-swift EditAlgebra tests green. Build clean. Refs #105

§3.3 / §8 / §9 e2e tests blocked on OperationReducer Phase 2c (tree-mutating Operation cases throw malformedOp). Issue filed against ooxml-swift with full scope + per-case priority order. Refs #105

§3.1/§3.2/§4.1/§6.1 emission tests shipped on ooxml-swift branch idd/105-edit-algebra-runtime. §3.3/§4.2/§6.2 e2e blocked on ooxml-swift#71 (OpLog Phase 2c reducer). §5 insertHyperlink pending — composite atomic design has open questions requiring user input (see #105 issue thread / next msg). Refs #105

ooxml-swift#71 Phase 2c reducer cases (insertParagraphAfter, insertParagraphBefore, removeParagraph, setRunFormat(bold MVP)) landed on ooxml-swift branch idd/71-oplog-phase-2c-reducer (merged into idd/105-edit-algebra-runtime for local e2e testing). 7 InsertParagraphE2ETests.swift tests prove the full chain (WordDocument.apply → lower → operations → log → materialize) mutates xmlTrees end-to-end on synthesized single-part documents. Real-.docx NTPU fixture variants deferred until per-op part scoping fix lands in WordDocument+Apply.swift — currently iterates ALL parts → Reducer throws elementNotFound on parts not containing the target. Documented as follow-up. §5 insertHyperlink still pending composite-atomic design checkpoint. Refs #105 Refs PsychQuant/ooxml-swift#71

Fixes raised by review of PR #109: C1 (tasks.md status accuracy) - §1.1–1.4, §2.1, §2.4, §2.5 marked [x] (shipped); §1+§2 headers note COMPLETE - §2.2 + §2.3 stay [ ] but annotated PHASED (Phase 2c follow-up); explained - §4, §6 already correctly marked H1 (spec.md Document → WordDocument) - Renamed throughout spec.md (the actual ooxml-swift type is WordDocument; foundation #99 used the conceptual name 'Document' which we now reconcile) - spec.md item title 'Document.apply Public Method' → 'WordDocument.apply Public Method' - Sources/.../Models/Document.swift file path retained (that's where the WordDocument type IS declared); apply() lives in EditAlgebra/WordDocument+Apply.swift H2 + M1 (PHASED items in spec.md normative SHALL list) - spec.md item #4 (pathNotFound early validation) marked '(PHASED — Phase 2c follow-up)' with explicit fallback (Reducer's elementNotFound wraps via operationLogFailure) - spec.md item #5 (preserveViolation defensive c14n) same phasing - Added 'Phased acceptance note' at end of Requirement explaining which SHALLs are required for initial acceptance vs phased M2 (proposal.md ASSUMPTION cross-ref) - Added REVISED ASSUMPTION block under the original ASSUMPTION, pointing to design.md Decision 6 errata + linking ooxml-swift#71 + PR #72 - Notes that insertHyperlink's composite mapping still depends on insertNode + updateAttribute reducer cases not yet in PR #72 L2 (design.md Decision 6 — link PR #72) - Added 'Critical-path subset SHIPPED via PR #72' paragraph with 4-of-14 case enumeration + 7 e2e test reference L4 (tasks.md §5 PENDING annotation) - §5 header annotated 'PENDING composite-design checkpoint' with the 5 open design questions inline N1 (proposal.md wrong file paths) - 'gains apply(_:) public method' in Models/Document.swift → 'gains operationLog field; apply ships in NEW file EditAlgebra/WordDocument+Apply.swift' - Affected code list adds WordDocument+Apply.swift entry N3 (design.md inline TODO) - 'TODO: verify if log starts empty or seeded' replaced with reference to DocumentApplyTests.testOperationLogStartsEmpty (already proven) Spectra validate still passes green. Refs #105

39/42 tasks complete; remaining 3 are PHASED items intentionally not shipped: - §2.2 EditError.pathNotFound early validation (PHASED — Reducer-wrap via operationLogFailure documented in spec.md as eventual contract) - §2.3 EditError.preserveViolation defensive c14n check (PHASED — same) - §5.2 Upfront atomicity pre-validation (DEFERRED — Reducer-layer atomicity via deterministic rId allocation works correctly without pre-validation; pre-validation would be a UX improvement) Spec ooxml-edit-algebra-runtime moved to openspec/specs/ (8 Requirements with SHALL/MUST + Scenarios + SBE Examples). Implementation shipped across 8 PRs over the macdoc#105 lifecycle: - macdoc PR #109 — Spectra docs (proposal+design+tasks+spec+yaml) - macdoc PR #111 — CD diagrams (8 total: 5 OOXMLEdit + 3 WordEdit) - ooxml-swift PR #72 — Phase 2c reducer critical-path (4 cases) - ooxml-swift PR #74 — multi-part scoping + opID-determinism - ooxml-swift PR #75 — FullyFaithfulFunctorTests (property-based) - ooxml-swift PR #76 — WordEdit.lower() per-case - ooxml-swift PR #77 — NaturalityTests (composition functor) - ooxml-swift PR #78 — Performance benchmark + single-part fast path - ooxml-swift PR #79 — Typed-views resync (opt-in) - ooxml-swift PR #80 — §5 insertHyperlink + wrapWithHyperlink emission - ooxml-swift PR #81 — Phase 2c hyperlink reducer (slice 1) - ooxml-swift PR #82 — Phase 2c wrapWithHyperlink reducer (slice 2) Refs #105 Refs #110 Refs PsychQuant/ooxml-swift#71

kiki830621 added 4 commits May 31, 2026 18:16

docs(spectra/#105): link OpLog Phase 2c blocker — ooxml-swift#71

03f2c05

§3.3 / §8 / §9 e2e tests blocked on OperationReducer Phase 2c (tree-mutating Operation cases throw malformedOp). Issue filed against ooxml-swift with full scope + per-case priority order. Refs #105

kiki830621 mentioned this pull request May 31, 2026

Spectra: ooxml-edit-algebra-implementation (Phase 2 — Edit type runtime + property tests, per ooxml-edit-isomorphism-foundation) #105

Closed

kiki830621 merged commit 6022f5c into main May 31, 2026
1 check passed

kiki830621 deleted the idd/105-ooxml-edit-algebra-implementation branch May 31, 2026 12:11

kiki830621 mentioned this pull request Sep 1, 2026

bug: insert_image_from_path append 模式不寫 <w:drawing> — 圖片靜默遺失，三個驗證管道都測不到 #175

Closed

Navigation Menu

Repository navigation

Spectra: ooxml-edit-algebra-implementation — Phase 2 runtime of #99 - #109

Spectra: ooxml-edit-algebra-implementation — Phase 2 runtime of #99#109
kiki830621 merged 5 commits into
mainfrom
idd/105-ooxml-edit-algebra-implementation

kiki830621 commented May 31, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

kiki830621 commented May 31, 2026

Summary

Design Decisions (in design.md)

Implementation status (across linked PRs)

Architectural milestone

Linked work

Test plan

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant