Expose OPY compilation and close the end-to-end compatibility gate

[Teakowa]

Parent: #8
Depends on: #35, #36, #37, #52

Goal

Turn the completed integration pipeline into a supported library/CLI compilation surface and use end-to-end corpus evidence to define the first real OPY→Workshop compatibility baseline.

Context

The standalone CLI foundation is already modernized under #43, but opy-cli still has no compile command. Once HIR→WIR lowering and Workshop-dependent backend behavior are integrated, compilation should become a first-class opy-rs capability rather than an internal test path.

This issue is the authoritative owner for the compilation-cutover plan's entire Parent B. Do not create separate B-1/B-2/B-3 issues unless implementation evidence later requires an independently reviewable contract boundary.

Scope

• Define and document a versioned opy-rs compile result/diagnostics contract suitable for CLI, CI, embedding, and agents, with an explicit schema/version field and stable failure classification.
• Expose a library compile API that runs OPY frontend resolution, HIR→WIR lowering, canonical validation, localized Workshop emission, and post-compile-hook processing as one explicit pipeline.
• Add compile to the existing structured opy-cli command/presentation model from Modernize the standalone CLI foundation and CI presentation #43; preserve deterministic stdout/stderr and existing exit-code conventions unless a separately justified contract change is required.
• Support text output and machine-readable output without coupling the public compiler API to Wright orchestration or adopting Wright-owned schemas.
• Report compiler identity together with consumed workshop-rs implementation/catalog identity where machine-readable output requires reproducibility.
• Run the compatibility corpus through the native compiler and compare against pinned OverPy evidence using observable semantic/normalized contracts rather than exact emitted text.
• Add CLI-level oracle/regression coverage for successful compilation, partial/unsupported surfaces, structured diagnostics, IO/usage failures, and exit-code behavior.
• Promote support-matrix entries from lowering-dependent/frontend states only when end-to-end evidence justifies the change; keep known gaps explicit and machine-readable.
• Close the aggregate compilation/workshop-lowering, compilation/end-to-end, and optimization/emission-form evidence contracts based on the actual canonical workshop-rs emitter behavior rather than a second OPY emitter.
• Update README/human compatibility documentation to describe actual compiler support without embedding roadmap/TODO state.
• Reassess remaining compiler gaps after evidence is collected and split only concrete follow-up issues.

Non-goals

• Wright-specific UX, lint, agent orchestration, or CI presentation.
• Reusing or modifying Wright-owned result/schema contracts merely for symmetry.
• A separate OPY formatting/emitter backend; Workshop text emission remains owned by workshop-rs.
• Claiming full OverPy compatibility from parser/frontend coverage alone.
• Byte-identical Workshop output, upstream optimizer identity, or temporary-variable identity.
• Starting Workshop→OPY implementation; [design] Re-evaluate Workshop → OPY reconstruction scope after workshop-rs rebaseline #53 is the design spike and remains separate.

Acceptance criteria

• [integration] Rebaseline opy-compiler on current workshop-rs release #52, Lower the declared OPY semantic surface into canonical Workshop WIR #36, and Integrate Workshop-dependent settings, locale, directive, and hook behavior #37 are complete and the public compiler is validated against the rebaselined Workshop dependency.
• A documented versioned compile diagnostics/result contract exists in opy-rs and is exercised by machine-output tests.
• A documented library API and opy-cli compile command compile supported .opy input to valid Workshop text using the canonical workshop-rs emitter.
• Compilation failure modes are structured, source-attributed where possible, and stable enough for tooling/CI consumption.
• CLI text/machine output and exit-code behavior have black-box regression coverage.
• The compatibility corpus produces a machine-readable end-to-end report with no hidden/inconclusive success cases.
• Human and machine-readable compatibility status agree on the declared compiler support boundary.
• At least the declared baseline corpus is end-to-end supported or every remaining failure is independently evidenced and tracked as a concrete gap.
• Integrate OPY lowering and end-to-end compatibility with workshop-rs #8 can close based on implementation/tests/integration evidence rather than issue state alone.