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

#158 / PR #159 established the current offline conformance baseline. Historical #88 implementation work remains useful provenance, but its completion state and old compile-status expectations are not the current compatibility proof.

Current convergence order follows the source-to-target pipeline:

1. Converge parser and source-form conformance exposed by #158 #160 — lexical/parser/source-form conformance.
2. Converge preprocessing and project-composition conformance exposed by #158 #161 — preprocessing, directives, macros, and project composition.
3. Converge semantic resolution and catalog-backed source conformance exposed by #158 #162 — semantic resolution, builtins, members, enums, aliases, and binders.
4. Converge residual OPY compiler and canonical-WIR gaps #157 — residual compiler/canonical-WIR convergence after the source-language stages are cleanly classified.

Each workstream consumes the durable #158 oracle/conformance expectations and must not redefine them around implementation fixes. Newly exposed cases should remain grouped by root capability rather than fixture-by-fixture work.

Workshop -> OPY reconstruction (#53) and compatibility-harness retirement planning (#117) remain later lanes and should not preempt active forward compatibility convergence.

Current execution state, release versions, and corpus frontiers must be derived from GitHub and generated conformance evidence rather than historical completion claims.

[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).