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.

Current status

The independent source-language implementation and first OPY→Workshop compiler baseline are established.

Completed integration baseline:

• Establish the versioned OPY-to-Workshop integration boundary #35 — versioned OPY→Workshop integration boundary
• Lower the declared OPY semantic surface into canonical Workshop WIR #36 — declared semantic lowering into canonical WIR
• Integrate Workshop-dependent settings, locale, directive, and hook behavior #37 — Workshop-dependent settings/locale/directive/hook behavior
• Expose OPY compilation and close the end-to-end compatibility gate #38 — versioned public compile API/CLI and end-to-end compatibility baseline
• [integration] Rebaseline opy-compiler on current workshop-rs release #52 — released Workshop dependency rebaseline
• Integrate OPY lowering and end-to-end compatibility with workshop-rs #8 — first canonical OPY→Workshop integration baseline

The released opy-rs / opy-compiler v0.1.5 contract is consumed by Wright's source-language ownership cutover in wright#228.

Active compatibility frontier

The next work is no longer the old #42 → #36 → #37 → #38 chain. Concrete residual gaps discovered by executable compiler evidence are now split by ownership:

• Close residual OPY frontend and project-corpus compiler gaps #88 — OPY frontend and full-project corpus gaps
• Restore canonical WIR equivalence for residual compiler lowering cases #89 — OPY lowering cases where a canonical WIR contract already exists or must be attributed precisely
• wrightkit/workshop-rs#123 — canonical WIR carriers for cases not representable losslessly by the current Workshop contract
• wrightkit/workshop-rs#124 — canonical enum-domain disambiguation needed for direct semantic-WIR oracle comparison

Use the owner sequence for each gap:

owning contract/tests -> released consumable contract -> opy-rs integration -> corpus/real-workflow verification

Do not add text-reparse fallbacks or duplicate Workshop semantics in opy-rs to hide owner gaps.

Separate/non-gating work

• [design] Re-evaluate Workshop → OPY reconstruction scope after workshop-rs rebaseline #53 — scoped Workshop→OPY reconstruction design lane.
• Track OverPy null-initializer default semantics #58/Add bounded OverPy increment and decrement assignment support #59/Define bounded multidimensional indexed-assignment lowering #60/Support player-variable range-for binders #65 — bounded compatibility follow-ups; keep off the critical path unless representative real-project evidence proves otherwise.
• Support/documentation work must follow executable evidence and must not replace compiler or real-project verification.

Durable data flow

OPY source -> parse/preprocess -> semantic resolution/HIR -> opy-compiler -> workshop-rs WIR -> Workshop text

Ownership

• opy-rs owns OverPy syntax, preprocessing/macros, semantic resolution, HIR, diagnostics/provenance, tooling APIs, compiler behavior, and scoped reconstruction.
• workshop-rs owns canonical Workshop semantics, catalog, WIR, settings/localization, validation, emission, and Workshop semantic carriers.
• Wright is a consumer/integration layer and must not compensate for missing OPY or Workshop semantics.

Acceptance criteria

• The OPY language/tooling implementation remains independently useful and evidence-backed.
• Supported OPY programs compile through canonical WIR and Workshop emission with structured diagnostics and preserved provenance.
• Compatibility advances are grounded in representative real-world/corpus evidence; known gaps remain explicit.
• No authoritative Workshop ownership is duplicated in opy-rs.
• Reconstruction, if pursued, uses a separately reviewed semantic-equivalence/useful-source contract rather than promising literal recovery.

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