Build an independent OverPy-compatible engine with canonical Workshop integration

[Teakowa]

Goal

Build opy-rs into an independent OverPy-compatible engine that owns OverPy language semantics and compiler behavior while integrating with canonical Workshop semantics from workshop-rs.

Context

opy-rs owns 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/program representation, settings/localization, validation, and emission. 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 canonical Program/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 independently of final Workshop text emission.
• Lower supported OPY semantics through canonical workshop-rs contracts.
• Advance compatibility from pinned upstream/oracle evidence, minimized regressions, representative real projects, and compiler-output differential comparison.
• Treat systematic compiler-output drift as a compatibility residual unless it is explicitly classified as necessary or non-contractual.
• Keep source-language and Workshop capability gaps 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, representation, or emission logic in opy-rs.
• Adding WrightKit-only OverPy syntax or semantics.
• Reproducing upstream internal architecture, helper implementation, or IR solely for fidelity.
• Requiring byte/text-identical output for incidental whitespace or formatting differences that do not change Workshop structure, element cost, accepted syntax, diagnostics/provenance, or downstream behavior.
• Hiding owner gaps behind text-reparse fallbacks, fixture-specific workarounds, or Wright-side semantic compensation.
• Treating manually maintained status text, issue checklists, or support matrices as proof of 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 Workshop representation and emission with structured diagnostics and preserved provenance.
• Representative compiler-output diffs converge toward upstream action/value identities, control-flow structure, string/value construction, and optimization/element-cost shape; unexplained systematic divergence remains explicit.
• Compatibility claims are grounded in representative corpus and 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.

Ownership

• OverPy language semantics and compiler behavior: opy-rs.
• Canonical Workshop semantics and representation: workshop-rs.
• Product integration/tooling consumption: wright.

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

[Teakowa]

Current execution focus — 2026-09-10

Near-term WrightKit development is concentrated on opy-rs and wright; deltin-rs feature development is paused.

For opy-rs, the active capability lane is forward real-project/tooling readiness:

• advance Converge residual OPY compiler and canonical-WIR gaps #157 only for residuals demonstrated to belong to OPY compiler/lowering or canonical-WIR convergence after the completed source frontiers;
• prioritize owner fixes exposed by Wright's canonical Bastion / Overwatch-AI-PVE workflows;
• keep source diagnostics/provenance and semantic APIs usable by Wright check, lint, analyze, and upcoming semantic-query/edit workflows;
• publish consumable provider releases so Wright can verify owner fixes through the real product boundary.

Reconstruction (#53), compatibility-harness retirement, broad cleanup, and unrelated release/CI work should not preempt demonstrated OPY capability gaps or the Wright real-project/tooling path.