Build an independent OverPy-compatible engine with canonical Workshop integration

[Teakowa]

Goal

Build opy-rs into an independent, corpus-backed implementation of OverPy source-language semantics and connect it to canonical Workshop semantics without duplicating Workshop ownership.

Context

opy-rs is the owning implementation for OverPy syntax, preprocessing/macros, semantic resolution, HIR, diagnostics/provenance, source-language tooling, compiler behavior, and scoped Workshop -> OPY reconstruction.

workshop-rs owns canonical Workshop semantics, catalog, WIR, settings/localization, validation, emission, and Workshop semantic carriers. Wright consumes these owner capabilities and must not fill missing OPY or Workshop semantics in the integration layer.

The durable forward data flow is:

OPY source -> parse/preprocess -> semantic resolution/HIR -> OPY lowering -> workshop-rs WIR -> validation/emission

Scope

• Parse and preprocess supported OverPy source with recoverable diagnostics and source provenance.
• Resolve declarations, expressions, receivers/members, builtins, enums/constants, macros, directives, settings, and other declared language semantics into a tooling-usable semantic model.
• Expose semantic APIs suitable for check, diagnostics, inspect, lint, validated source tooling, CI, and agent workflows independent of final Workshop text emission.
• Lower supported OPY semantics through canonical workshop-rs WIR and emission contracts.
• Advance compatibility from pinned upstream/oracle evidence, minimized regressions, and representative real projects rather than compiler-output shape.
• Keep source-language and Workshop capability gaps explicitly attributable to their owning repository.
• Treat Workshop -> OPY reconstruction as a separately reviewed semantic-equivalence/useful-source capability with explicit information-loss boundaries.

Non-goals

• Duplicating canonical Workshop actions, values, events, enums, settings, localization, validation, WIR, or emission logic in opy-rs.
• Adding WrightKit-only OverPy syntax or language semantics.
• Reproducing upstream implementation architecture, helper names, optimizer structure, temporary-variable allocation, formatting, or byte/text-identical Workshop output unless observable semantics require it.
• Hiding owner gaps behind text-reparse fallbacks, fixture-specific workarounds, or Wright-side semantic compensation.
• Treating a manually maintained issue checklist or support matrix as proof of real-project compatibility.

Acceptance criteria

• The declared OPY language/tooling surface is independently usable and backed by provenance-aware executable evidence.
• Supported OPY source can be parsed, semantically resolved, inspected, and diagnosed without depending on an upstream runtime.
• Supported OPY programs lower through canonical WIR and Workshop emission with structured diagnostics and preserved provenance.
• Compatibility claims are grounded in representative corpus/real-project evidence; unsupported or inconclusive gaps remain explicit.
• No authoritative Workshop semantics are duplicated in opy-rs.
• Cross-repository gaps follow the owner sequence: owning contract/tests -> consumable contract/release -> opy-rs integration -> corpus/real-workflow verification.
• Reconstruction, where supported, follows an explicit semantic-equivalence/useful-source contract rather than promising literal recovery.

Planning

The active source-language completion program is #88, organized by category rather than individual corpus residuals. It has a product constraint of at most 10 non-release implementation PRs across its five capability workstreams.

Workshop -> OPY reconstruction (#53) and compatibility-harness retirement planning (#117) remain separate later lanes and should not preempt #88 while source-language compatibility is incomplete.

Current execution state, ordering inside a capability block, release versions, and corpus frontiers should be derived from GitHub and executable evidence rather than copied into this parent issue.

[Teakowa]

Status — Workshop-independent roadmap advanced

Draft PRs (all CI green on their head SHAs):

• PR feat(compatibility): OverPy feature inventory and corpus (#2) #10 (feat/evidence-base) → Establish the OverPy feature inventory and compatibility corpus #2: pinned OverPy 9.7.10 @ 889d974, tiered baseline, machine-readable support matrix, 26-fixture provenance corpus, oracle harness (26/26 snapshots PASS).
• PR feat(frontend): standalone OPY frontend extraction #9 (feat/frontend-bootstrap) → Bootstrap the OPY source frontend and syntax model #3/Implement OPY semantic resolution and language model #4/Implement OPY preprocessing, directives, and macro expansion #5: standalone opy-frontend crate (lexer/CST/parser/diag/preprocess/settings/manifest/lower + Opy HIR), zero wright/workshop-rs deps; trivia-retention policy documented.
• PR feat(runtime): JavaScript macro and hook runtime (#6) #11 (feat/js-macro-runtime) → Implement JavaScript macro and hook runtime compatibility #6: QuickJS-NG macro/hook runtime with upstream ABI, resource limits, 33 fixtures; CI OOM defect fixed.
• PR feat(tooling): OPY check/inspect CLI and library APIs (#7) #12 (feat/tooling) → Reach Workshop-independent OPY frontend completeness and expose tooling APIs #7 part A: check/inspect tooling API, semantic queries, support-metadata accessor, opy-cli (check/inspect/support/version), diagnostics contract.
• PR feat(completeness): differential parity suite and JS macro integration (#7) #13 (feat/frontend-completeness) → Reach Workshop-independent OPY frontend completeness and expose tooling APIs #7 part B: differential suite over all 26 corpus fixtures (14 resolve, 12 expected-diagnostic, 7 documented reference gaps), script/postCompileHook frontend integration with runtime execution, support matrix advanced (frontend-supported 14, semantic-supported 5).

Remaining work is classified, none unclassified:

• lowering-dependent (all Integrate OPY lowering and end-to-end compatibility with workshop-rs #8-linked): Workshop emission/lowering, settings/locale emission, post-compile hook wiring to emitted content, decompilation.
• Documented reference gaps (issue Reach Workshop-independent OPY frontend completeness and expose tooling APIs #7 evidence): santa do-loops, cronch ++, crosshair b-strings, broken-weapons float ranges, client-to-server chained ternary, inputhud multiline parens, parabola Team.2 — inventory-classified, no blocker.
• Planned matrix rows: full builtin/enum/receiver surfaces beyond the manifest-declared evidence, advanced directives (#!mainFile etc.), translations, optimization controls — evidence-prioritized.

#8 remains blocked on workshop-rs public contracts as designed.

[Teakowa]

Merge-blocker fix batch complete (QA READY)

All five PRs reviewed by QA (independent verification, fresh checkouts, full gates): #9/#10/#12/#13 READY, #11 merged by maintainer. No unresolved blockers in ownership, semantics, licensing/provenance, or branch history.

Final stacking: main ← #9 (frontend) · main ← #10 (evidence) · feat/stack-base (bc1d9e8) ← #12 (tooling) · feat/stack-base ← #13 (completeness). Merge order: #9 → #10 → #12 → #13 (if #12 lands first, rebase #13 onto the new base — QA noted the standard stacked-PR sequencing).