[M13 investigation] Establish OSTW reference, corpus, licensing, and semantic support baseline

[Teakowa]

Parent: #90
Depends on: #106

Goal

Perform the evidence-gathering phase required before Wright decomposes or implements OSTW support: establish the upstream OSTW reference boundary, licensing/provenance constraints, viable oracle/reference machinery, a representative real-world corpus, and a bounded semantic support inventory.

This is a read-only investigation/planning task. It must not implement an OSTW parser, type system, emitter, or language service.

Context

#90 intentionally forbids detailed OSTW implementation decomposition until Architect/QA have inspected the actual upstream implementation and PM has approved corpus evidence. #106 now provides the reusable upstream-reference documentation and compatibility-baseline methodology used for OverPy.

Wright's product direction remains tooling-first: an OSTW frontend is enabling infrastructure for check, diagnostics, lint, analyze, inspect, source editing, agents, CI, and Workshop-centered interoperability.

Scope

• Identify the current upstream OSTW project/repository and the implementation components relevant to language semantics, compiler behavior, Workshop emission, decompilation/source reconstruction, and language services.
• Review licensing and provenance constraints for studying upstream source and using it as a compatibility/reference oracle.
• Propose a pinned reference identity/version policy and record durable project-level facts in docs/compatibility/upstream-references.md.
• Determine practical reference/oracle execution options for repeatable tests without making upstream .NET/runtime components a supported production dependency.
• Inventory the OSTW language surface by semantic category using the same distinction established by Establish a proactive OPY compatibility baseline from the pinned upstream language surface #106:
  • syntax/parse;
  • semantic/type/name resolution;
  • compile/emission semantics;
  • tooling/language-service semantics;
  • decompile/source-reconstruction behavior where relevant;
  • known reference limitations/quirks.
• Acquire or identify a representative real-world OSTW corpus with provenance and enough diversity to define an initial support boundary.
• Classify candidate categories as baseline-supported/planned, evidence-prioritized, legacy/quirk demand-driven, or reference-limited/inconclusive as appropriate.
• Identify which semantic services/data can reuse Wright's existing Workshop/WIR/session/tooling contracts and which genuinely require OSTW-specific frontend semantics.
• Evaluate Workshop -> OSTW and OSTW -> Workshop evidence requirements separately; do not assume symmetry implies direct OPY <-> OSTW work.
• Produce a PM-ready proposed decomposition grouped by semantic responsibility, not implementation convenience.

Non-goals

• Implementing any OSTW frontend/compiler/language-service code.
• Creating parser/type-system/emitter implementation issues before this investigation is accepted.
• Requiring byte-identical OSTW compiler output.
• Reproducing upstream internal architecture for its own sake.
• Wright-only OSTW syntax/extensions.
• Direct OPY <-> OSTW conversion design.
• Perfect recovery of original comments, formatting, macros, or lost abstractions from Workshop.

Deliverables

• Durable OSTW entry in docs/compatibility/upstream-references.md with repository identity, license, proposed pin/reference policy, oracle role, and limitations.
• OSTW semantic/reference inventory and initial support classification.
• Corpus inventory/acquisition plan with provenance and selection rationale.
• Reference/oracle feasibility report.
• Explicit architecture reuse/boundary findings for compiler/session/WIR/tooling/source-provenance services.
• Proposed bounded M13 implementation categories and dependency order, pending PM approval.

Acceptance criteria

• The upstream implementation and language-service/compiler boundaries have been inspected from actual source/repository evidence.
• Licensing/provenance and reference execution constraints are documented before implementation planning.
• A concrete initial corpus exists or has a reproducible acquisition plan sufficient for PM to approve the first support boundary.
• The investigation distinguishes observable semantic compatibility from output/internal implementation identity.
• Proposed implementation categories are driven by corpus/tooling value and semantic ownership, not by a desire to clone the upstream compiler.
• No OSTW implementation code or premature parser/type-system/emitter decomposition is introduced.
• PM has enough evidence to reassess [M13] Source-language interoperability and OSTW compatibility #90 and decide the first implementation milestone.

Relationships

• First execution step under [M13] Source-language interoperability and OSTW compatibility #90 after the Establish a proactive OPY compatibility baseline from the pinned upstream language surface #106 baseline methodology became available.
• Reuses the centralized reference/provenance approach from Establish a proactive OPY compatibility baseline from the pinned upstream language surface #106/[OPY baseline] Implement semantic compatibility manifest and systematic builtin/member/signature coverage #109.
• May run in parallel with OPY baseline implementation because it is investigation-only and does not depend on unfinished OPY feature parity.

[Teakowa]

Architect/QA investigation complete — OSTW reference, corpus, licensing, and semantic support baseline

Read-only investigation executed per this issue. No OSTW parser/type-system/emitter/language-service code was written and no implementation issues were created. Durable records were committed in 918e20a.

Upstream identity (verified 2026-08-15)

• Repo: ItsDeltin/Overwatch-Script-To-Workshop (OSTW, a.k.a. Deltin's Script To Workshop). Compiler is C#/.NET 8 (Deltinteger), one executable containing compiler + decompiler + emulator + full stdio LSP server.
• master HEAD 817c1db4 (2026-08-08), active (≈28 commits / 2 months). Stable tags v3.4.0 (2026-05-18) and earlier; latest is a rolling prerelease rebuilt on every push — never a pin. Program.VERSION still reads v3.4.0 at master.
• License is the key constraint: the compiler and wiki have no license file (none in git history; GitHub API null) — treated as unlicensed/all-rights-reserved for source copying. Only the VS Code extension subdir is MIT. Elements.json/LobbySettings.json/Maps.json are game-derived via the in-repo DataTool (Blizzard-IP-adjacent; not importable into Wright's catalog).
• Proposed pin: stable tag v3.4.0, content-pinned per ADR-0007 (version-exact, changed only on demonstrated need).

Compiler/language-service/emission/decompilation facts

• Frontend: hand-written recursive-descent parser + custom lexer (incremental), operator-stack expressions, Vanilla Workshop superset with variable/subroutine linking.
• Semantics: C#-like — classes (heap, ≤999 instances, inheritance, virtual/override), structs (in/ref), enums + pattern matching, generics, lambdas, macros (compile-time), subroutines, chasing variables, 11 rule events, ds.toml project settings, 13 output locales.
• Emission: Workshop elements with an optimizer (default on) and both output syntaxes (Set Global Variable(...) vs Global.x = ... via c_style_workshop_output).
• Language service: full LSP (completion, hover, definition, references, rename, code lens, semantic tokens, …) plus custom workshopCode/elementCount notifications.
• Reconstruction: TextToElement + ElementToCode decompile Workshop text to OSTW (rules/actions/conditions, lobby-settings import).
• Upstream tests use its own emulator (EmulateTick) as the behavioral oracle; Wait is unimplemented, so the E-level subset must be documented.

Oracle feasibility (verified by running the linux-x64 build)

• --ping works. The default CLI compile is interactive/clipboard-bound (blocks on Enter, needs xclip) — not a headless oracle.
• The stdio language server (--langserver) is the viable headless path: didOpen → publishDiagnostics + workshopCode/elementCount, honoring ds.toml. WASM interop exists but the browser-wasm build is not shipped in release assets. Release binaries are x64-only; on arm64 hosts use a linux/amd64 container (verified) or the .NET 8 runtime.

Corpus (provenance-checked)

• pharingWell/MOBAwatch (BSD-2-Clause, 69 .ostw/.del files, ds.toml, active format) — primary candidate.
• GrandeurHammers/protect-ban (MIT, small, ds.toml) — secondary candidate.
• ItsDeltin/Lava (official examples) — no license → excluded until resolved.
• Acquisition reuses scripts/acquire-corpus.py + corpus-manifest.json (immutable commits, per-file SHA-256).

Reuse vs OSTW-specific

• Reuse: wright-driver session/SourceKind, HIR/WIR lowering, Workshop catalog/parser/emitter/round-trip, analyzer + language services/LSP, compatibility harness, corpus tooling.
• OSTW-specific: lexer/parser/CST + Vanilla superset (new wright-ostw crate), class/struct/enum/generic/lambda/ds.toml semantics, a Wright-owned OSTW emitter for reconstruction, and the LSP-stdio oracle driver (reference infrastructure only).

Proposed bounded M13 decomposition (pending PM approval; not created as issues)

A: reference & corpus baseline (pin v3.4.0, --langserver oracle runner, acquire MOBAwatch + protect-ban, S-level record) → B: OSTW frontend core (categories 1–7 to HIR + structured diagnostics) → C: OSTW → Workshop emission (N-level normalized) → D: Workshop → OSTW reconstruction (declared surface + quality criteria) → E: tooling/language services. Classes/generics/lambdas and multi-locale are evidence-prioritized; direct OPY↔OSTW, debugger protocol, optimizer parity, and E-level timing are explicitly deferred. First milestone proposal: A+B+C scoped to the two corpus projects.

Durable records

• docs/compatibility/upstream-references.md — OSTW reference entry (identity, pin, license, oracle role, limitations).
• docs/ostw/compatibility-baseline.md — full inventory, corpus plan, oracle feasibility, reuse/boundary findings, decomposition.

PM: this satisfies the acceptance criteria for #113; #90 can now be reassessed for the first implementation milestone.

[Teakowa]

PM acceptance — investigation complete

Accepted at 918e20a.

The investigation satisfies #113's gate: it establishes a durable OSTW upstream/reference record, identifies the licensing boundary, demonstrates a viable headless --langserver oracle path, selects redistributable corpus candidates with an acquisition plan, separates reusable Wright services from OSTW-specific frontend semantics, and proposes a bounded M13 sequence without creating parser/type-system/emitter implementation work prematurely.

PM decisions:

• use stable v3.4.0 as the proposed content-pinned reference baseline; never use rolling latest;
• treat the upstream compiler/wiki as unlicensed for source-copying purposes; Wright may study observable behavior/reference execution but must not import/copy upstream implementation or game-derived data into core;
• approve MOBAwatch (BSD-2-Clause) and protect-ban (MIT) as the initial corpus candidates, subject to immutable acquisition/provenance records;
• approve the stdio LSP path as the reference/oracle mechanism for S/D/N evidence;
• do not yet create OSTW parser/type-system/emitter implementation issues. First land the oracle runner + acquired corpus + observed support inventory, then PM reassesses the actual construct distribution.

Next M13 step is therefore a bounded reference/corpus baseline implementation issue, after which #90 will be decomposed from measured corpus evidence.