Reach Workshop-independent OPY frontend completeness and expose tooling APIs

[Teakowa]

Parent: #1

Goal

Close the remaining Workshop-independent compatibility gaps and expose a stable enough frontend API for Wright and other consumers to parse, check, inspect, and reason about OPY source before end-to-end compilation is connected.

Current baseline

The standalone frontend/tooling/runtime foundation, documentation rebaseline, and strengthened compatibility evidence are merged on main. The canonical Workshop core gate in wrightkit/workshop-rs#2 is also complete.

The remaining frontend-readiness work is now split into three executable tracks:

• Complete the remaining Workshop-independent OPY syntax surface #28 — Complete the remaining Workshop-independent OPY syntax surface
• Complete OPY directive and preprocessing semantics before Workshop integration #29 — Complete OPY directive and preprocessing semantics before Workshop integration
• Reconcile OPY semantic coverage with the workshop-rs catalog boundary #30 — Reconcile OPY semantic coverage with the workshop-rs catalog boundary

The current support matrix still contains eight planned rows, but #30 must first separate genuine OPY semantic overlay work from canonical Workshop catalog/member/domain coverage. Do not treat the current row count as eight independent implementation requirements.

Workshop-owned validation, catalog population, emission, post-compile-hook execution against final Workshop text, settings/catalog validation, and locale behavior remain integration work under #8.

Scope

• Complete the remaining pure OPY syntax and source-language directive/preprocessing behavior with corpus/oracle evidence.
• Keep OPY-owned semantic metadata limited to language/API behavior that cannot be derived from canonical Workshop contracts.
• Reclassify mixed builtin/member/enum rows so authoritative Workshop catalog breadth is not represented as unfinished Workshop-independent work.
• Stabilize structured diagnostics across parse, preprocessing, macro expansion, runtime, and semantic-resolution stages.
• Preserve library APIs for parsing, resolved semantic queries, symbol/reference lookup, source provenance, compatibility/support metadata, and validated source tooling.
• Validate representative real-world and minimized-regression corpus cases end to end through the OPY semantic model.
• Document known limitations and explicitly separate integration-dependent gaps from unsupported frontend behavior.

Non-goals

• Wright-specific lint rules, agent orchestration, or UI behavior.
• Full-file source regeneration/pretty-printing as the default editing model.
• Workshop emission, canonical catalog ownership, locale data, or decompilation.
• Copying Workshop data into opy-rs merely to increase compatibility counts.
• Declaring full compiler compatibility before Integrate OPY lowering and end-to-end compatibility with workshop-rs #8 integration evidence exists.

Acceptance criteria

• Complete the remaining Workshop-independent OPY syntax surface #28, Complete OPY directive and preprocessing semantics before Workshop integration #29, and Reconcile OPY semantic coverage with the workshop-rs catalog boundary #30 are complete with evidence-backed tests and support-matrix updates.
• No genuine Workshop-independent matrix entry remains planned without an explicit evidence-backed decision and rationale.
• Canonical Workshop builtin/member/enum/settings/content validation is clearly assigned to Integrate OPY lowering and end-to-end compatibility with workshop-rs #8/workshop-rs, not duplicated here.
• Consumers can parse/check/inspect the declared OPY source surface through documented APIs without invoking Workshop emission.
• Diagnostics remain structured and source-attributed; cross-file symbols/references and macro-expanded provenance remain queryable.
• Representative corpus projects reach a resolved OPY semantic program or an externally evidenced expected diagnostic/gap classification.
• The frontend-to-Workshop integration boundary is concrete enough that Integrate OPY lowering and end-to-end compatibility with workshop-rs #8 can begin without redesigning the parser or semantic model.

Dependencies

• Establish the OverPy feature inventory and compatibility corpus #2 through Implement JavaScript macro and hook runtime compatibility #6 — completed foundation work.
• Rebaseline documentation after the standalone frontend foundation #15/Simplify human-facing OverPy compatibility documentation #22/Rebase OPY compatibility tests on real-project regressions and Workshop conformance evidence #25 — completed documentation/evidence follow-up work.
• wrightkit/workshop-rs#2 — completed; no longer an external blocker.

Planning notes

#7 is now the final pre-integration gate. Once #28–#30 satisfy the acceptance criteria, close #7 and refine #8 into the smallest executable integration changes. wrightkit/workshop-rs#10 strengthens future conformance/census evidence but is not a blocker for establishing the basic OPY→Workshop integration boundary.

[Teakowa]

Progress: PR #12 (feat/tooling) — library APIs (check/inspect, semantic queries, symbol/reference lookup, provenance, support metadata), opy-cli (check/inspect/support/version), diagnostics contract (13 stable codes), multi-file tests. PR #13 (feat/frontend-completeness) — differential parity suite (26/26 fixtures, report at target/opy-differential-report.json), JS macro + post-compile hook frontend integration with runtime execution. Remaining gaps are classified: 7 documented reference-accept gaps (inventory-classified), lowering-dependent items (Workshop emission wiring), and planned matrix rows (full builtin/enum/receiver surfaces, advanced directives, translations, optimization).