Build an independent OverPy-compatible frontend before 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

workshop-rs owns canonical raw Workshop semantics, WIR, catalog, validation, settings/locale data, and emission. opy-rs owns the OverPy source language, OPY-specific semantic overlay, compiler integration, and standalone OPY tooling.

The dependency/data-flow boundary is now:

OPY source -> opy-frontend -> OPY HIR -> integration/compiler layer -> workshop-rs WIR -> Workshop text

The standalone frontend remains Workshop-independent for check/inspect/source-tooling use cases.

Current status

The Workshop-independent phase is complete. #7 closed after #28/#29/#30 landed, and the merged support matrix now has planned: 0 with remaining compiler behavior explicitly classified as lowering-dependent.

The active phase is #8: OPY→Workshop compiler integration against the released workshop-rs 0.1.1 public contracts.

Execution history

Completed frontend/evidence foundation:

• Establish the OverPy feature inventory and compatibility corpus #2 — Establish the OverPy feature inventory and compatibility corpus
• Bootstrap the OPY source frontend and syntax model #3 — Bootstrap the OPY source frontend and syntax model
• Implement OPY semantic resolution and language model #4 — Implement OPY semantic resolution and language model
• Implement OPY preprocessing, directives, and macro expansion #5 — Implement OPY preprocessing, directives, and macro expansion
• Implement JavaScript macro and hook runtime compatibility #6 — Implement JavaScript macro and hook runtime compatibility
• Reach Workshop-independent OPY frontend completeness and expose tooling APIs #7 — Reach Workshop-independent OPY frontend completeness and expose tooling APIs
• Rebaseline documentation after the standalone frontend foundation #15 — Rebaseline documentation after the standalone frontend foundation
• Simplify human-facing OverPy compatibility documentation #22 — Simplify human-facing OverPy compatibility documentation
• Rebase OPY compatibility tests on real-project regressions and Workshop conformance evidence #25 — Rebase OPY compatibility tests on real-project regressions and Workshop conformance evidence
• 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

Active compiler integration:

• Integrate OPY lowering and end-to-end compatibility with workshop-rs #8 — Integrate OPY lowering and end-to-end compatibility with workshop-rs
  • Establish the versioned OPY-to-Workshop integration boundary #35 — Establish the versioned OPY-to-Workshop integration boundary
  • Lower the declared OPY semantic surface into canonical Workshop WIR #36 — Lower the declared OPY semantic surface into canonical Workshop WIR
  • Integrate Workshop-dependent settings, locale, directive, and hook behavior #37 — Integrate Workshop-dependent settings, locale, directive, and hook behavior
  • Expose OPY compilation and close the end-to-end compatibility gate #38 — Expose OPY compilation and close the end-to-end compatibility gate

Scope

• Maintain evidence-backed compatibility against pinned OverPy behavior and representative real projects.
• Keep OPY syntax, preprocessing, macros, semantic resolution, diagnostics, runtime behavior, source provenance, and tooling APIs independently usable before Workshop emission.
• Keep OPY-specific signature/alias/context metadata in opy-rs while resolving canonical Workshop catalog/member/domain/settings/locale behavior through workshop-rs.
• Lower OPY semantics directly into canonical workshop-rs WIR through a dedicated integration/compiler layer rather than another temporary Workshop IR.
• Expose standalone compilation only when implementation and end-to-end corpus evidence justify it.

Non-goals

• Duplicating canonical Workshop actions, values, events, heroes, maps, settings, locale tables, WIR, or emitter logic.
• Adding workshop-rs directly to opy-frontend.
• Reproducing OverPy internal architecture, optimizer implementation, generated text, temporary-variable allocation, or formatting where observable semantics do not require it.
• Starting Workshop -> OPY reconstruction before compiler integration produces evidence for a concrete design.

Acceptance criteria

• The OPY language/tooling surface remains independently useful and evidence-backed.
• No authoritative Workshop data or semantic ownership is duplicated in opy-rs.
• OPY semantic identities connect to workshop-rs public contracts without parser/frontend redesign.
• Supported OPY programs compile through canonical WIR and Workshop emission with structured diagnostics and preserved provenance.
• End-to-end compiler compatibility is claimed only with corpus/differential evidence.

Dependencies

• wrightkit/workshop-rs#2 — completed.
• workshop-rs 0.1.1 — current compiler-integration baseline.
• wrightkit/workshop-rs#10 provides follow-on shared conformance/census evidence but does not block baseline integration.

Planning notes

Keep near-term integration issues executable and evidence-driven. Do not create per-symbol issues for catalog-scale surfaces or implement upstream internals solely to improve nominal compatibility counts.

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