[M13 reverse] Reconstruct the declared Workshop surface as valid OPY source

[Teakowa]

Parent: #90
Depends on: #119

Goal

Implement Wright-owned Workshop -> OPY source reconstruction for a declared, evidence-backed Workshop/WIR surface, producing canonical useful OPY that recompiles to semantically equivalent Workshop.

Context

Current raw Workshop inputs parse directly into validated Wright WIR. M13 forward work is complete: native OPY and OSTW frontends converge on the same Workshop semantics/WIR, and #119 proves the OSTW -> Workshop path.

Reverse reconstruction must therefore start from canonical Workshop/WIR semantics. It must not attempt to recover lost comments, formatting, macros, temporary-variable intent, or original high-level abstractions.

Scope

• Add an OPY-owned reconstruction/emission API that consumes validated Wright WIR.
• Emit deterministic canonical OPY for the subset that the native wright-opy frontend can represent and recompile correctly.
• Cover the core structured Workshop surface evidenced by current Workshop fixtures: variable declarations/indices, subroutines, rules/events/conditions, scalar/array/vector/enum values, variable access, calls/actions, assignment/modify actions, if, while, and representable for-loop forms.
• Resolve Workshop actions/values/enums through existing canonical Workshop catalog plus OPY manifest/source bindings; do not introduce a second content/signature table.
• Prefer simple low-level valid OPY over speculative recovery of functions/macros/source abstractions.
• Define explicit unsupported diagnostics for WIR constructs whose current OPY frontend/source syntax cannot represent semantically.
• Validate reconstruction with the full loop:
  Workshop -> WIR -> OPY source -> native OPY frontend -> WIR -> Workshop, comparing observable/normalized semantics rather than source-text identity.
• Add deterministic fixtures and a machine-readable support boundary for reconstruction coverage.

Non-goals

• Recovering original OPY formatting/comments/includes/macros/function structure.
• Using OverPy as a production runtime dependency.
• Whole-source regeneration for agent edits; this is raw Workshop interoperability output only.
• Expanding OPY syntax or inventing Wright-only OPY.
• Workshop -> OSTW; tracked separately.
• Adding the shared CLI conversion command; final integration is a separate M13 step after both reconstructors exist.

Acceptance criteria

• A library consumer can reconstruct valid canonical OPY from every WIR construct declared supported by this issue.
• Reconstructed OPY is accepted by Wright's native OPY frontend without upstream runtime support.
• Recompiling reconstructed OPY produces Workshop semantically equivalent to the original under Wright's declared normalization/round-trip contract.
• Unsupported constructs fail deterministically and explicitly instead of emitting misleading source.
• Canonical Workshop/OPY metadata remains single-owned by the existing catalog/manifest contracts.
• Current OPY/Workshop/OSTW and CI compatibility gates remain green.

Relationships

• Reverse-interoperability child of [M13] Source-language interoperability and OSTW compatibility #90 after [M13] Compile the accepted OSTW corpus slice to Workshop with reference differential validation #119 forward compilation acceptance.
• May proceed in parallel with Workshop -> OSTW reconstruction.
• Enables final shared conversion/CLI integration and M13 acceptance.

[Teakowa]

Acceptance evidence — M13 reverse: Workshop → OPY reconstruction (#124)

Commit: 5334577293b75ce53f5c0797ed0631d3630f5c9b (feat(opy): reconstruct Workshop IR as deterministic OPY (#124)) — pushed to main.

CI: GitHub Actions run — green, all jobs success: rust-quality (stable + 1.85.0), v1-gates, compatibility-oracle, ostw-reference, ostw-compile-differential, adapter, compatibility-differential, dist-validation (windows/ubuntu/macos).

What shipped

wright_opy::reconstruct (library API in crates/wright-opy/src/reconstruct.rs) consumes validated WIR and emits deterministic, byte-stable canonical OPY that the native wright-opy frontend accepts and that re-lowers to a WIR structurally equivalent under wright_workshop::roundtrip::equivalent. Identities resolve only through the OPY manifest + Workshop catalog; no CLI, no invented OPY syntax, no OverPy runtime dependency, no compatibility//adapter/ changes.

Reconstruction report (target/wright-reconstruction-report.json, also written by the test suite):

fixture	round-trip (equivalent)	native frontend accepts	Workshop re-emit
variables-declarations	✅	✅	✅
subroutine-control-flow	✅	✅	✅
player-events	✅	✅	✅
values-enums	✅	✅	✅
actions-surface	✅	✅	✅

Each fixture runs the full loop Workshop → WIR → reconstructed OPY → native frontend → HIR → WIR → Workshop in-repo (no OverPy/Node), with one reconstructed OPY per fixture under target/wright-reconstruction/. Determinism is asserted by re-running reconstruction on the same WIR (byte-identical).

Support boundary (crates/wright-opy/tests/fixtures/reconstruct/boundary.json): 41 supported constructs (36 fixture-covered + 5 OPY-derived unit-covered: debug/print/arrays/vectors/format) and 26 explicitly rejected constructs, each with a deterministic structured diagnostic naming the construct — per-player loop, disabled rules, arbitrary-player targets, negative/non-finite literals, unrepresentable call names/enums, Remove From Array, non-canonical rule layout, and more. A consistency test fails on any coverage drift between the boundary and the fixtures/rejection cases.

Gates: cargo fmt --all -- --check, cargo clippy --workspace --all-targets --all-features -- -D warnings, cargo test --workspace --all-targets --all-features (all green), cargo test -p wright-ostw --test differential (green), python3 -m unittest discover -s compatibility/tests (18/18 green), and the pinned OverPy oracle compatibility/run_oracle.py (all PASS).

Docs: reconstruction surface documented in docs/opy/support-matrix.md.