Define the scoped Workshop Program to OPY reconstruction contract

[Teakowa]

Parent: #1
Supersedes: #53

Goal

Define the durable contract for reconstructing useful OverPy source from the canonical public workshop-rs::Program model.

The target is semantic equivalence and useful source structure, with explicit information-loss boundaries. Reconstruction must not promise recovery of source information that canonical Workshop semantics do not contain.

Context

Workshop semantics are owned by workshop-rs; mapping canonical Workshop meaning into valid/useful OverPy source is owned by opy-rs. The public canonical Program boundary is therefore the source-language-neutral input for scoped reconstruction.

Scope

• Define which canonical Program concepts can be represented directly as valid OverPy source and which require reconstruction choices.
• Define semantic-equivalence criteria for reconstructed output using canonical Workshop meaning rather than emitted-text identity.
• Define how optional source mapping, comments/trivia, or other authored-source metadata may improve reconstruction without making that metadata mandatory for ordinary canonical programs.
• Identify information that cannot be recovered reliably, including original formatting, unavailable comments, macro/preprocessor structure, source abstractions, local naming, helper structure, and other erased source-level intent.
• Define the boundary between deterministic reconstruction and explicit heuristic choices where multiple OverPy forms are semantically equivalent.
• Define round-trip tests appropriate to the contract, including Program -> OPY -> Program semantic equivalence for supported cases.
• Identify genuinely missing source-language-neutral Workshop capability in workshop-rs; do not introduce an OPY-local Workshop semantic model or parser fallback.
• Record the accepted reconstruction contract in durable owner documentation/ADR before implementation is decomposed.

Non-goals

• Implementing reconstruction in this issue.
• Reconstructing the original OverPy source literally.
• An arbitrary raw .ws text decompiler that bypasses canonical workshop-rs parsing/semantics.
• Exact formatting, comment, macro, helper-name, optimizer-shape, or compiler-output recovery.
• Whole-file regeneration as a source-edit strategy for existing OverPy files.
• Moving Workshop semantics, catalog facts, validation, or emission ownership into opy-rs.

Acceptance criteria

• A reviewed owner contract defines the supported canonical Program -> OPY reconstruction surface and explicit information-loss boundaries.
• Supported reconstruction targets valid OverPy whose lowering is semantically equivalent to the input canonical Workshop program under the reviewed comparison contract.
• Deterministic mappings and heuristic reconstruction choices are distinguished explicitly, including refusal behavior where useful reconstruction is not justified.
• Optional authored-source metadata is an enhancement rather than a prerequisite for canonical semantic reconstruction.
• Round-trip test requirements are defined without requiring text or formatting identity.
• Missing canonical Workshop capability is assigned to workshop-rs rather than approximated locally.
• Implementation work is decomposed only after the reconstruction contract is reviewed and accepted.

Ownership

• Workshop-to-OverPy reconstruction policy and generated OverPy structure: opy-rs.
• Canonical Workshop Program, semantics, validation, catalog/settings/localization facts, parsing, and emission: workshop-rs.