[Architecture] Rebaseline Wright as a tooling-first semantic platform

[Teakowa]

Goal

Rebaseline Wright's durable architecture and product contract around the current product decision: Wright is tooling-first, while owning compiler-grade semantic frontends where independence is required by the tooling.

This issue corrects current documentation drift and defines the boundary that post-M11 roadmap work must use.

Context

The current repository has outgrown the original bootstrap scope.

ARCHITECTURE.md currently contains contradictory contracts: its project-boundary text still describes OverPy as the external .opy frontend until a later native milestone, its frontend section describes wright-opy as the v1 native frontend, while its v1 non-goals still list a native Rust .opy parser. ADR-0001 reflects the earlier bootstrap decision and is now historical rather than an adequate current product boundary.

The implemented repository now includes a native .opy semantic frontend, native Workshop parsing/emission, WIR/HIR, semantic analysis, tool APIs, language services, LSP, and compatibility machinery. M11 also demonstrated the risk of treating every reference-output difference as product-critical compatibility work.

Architecture decisions to record

1. Product priority: tooling first

Wright's primary product surface is semantic tooling:

• check / diagnostics;
• lint and static analysis;
• inspection/query;
• safe source edits/refactoring;
• agent tooling and embedding APIs;
• Workshop cost/stability reasoning.

Compilation and conversion are required infrastructure and user capabilities, but compiler parity work must not consume the roadmap by default when it does not block real compilation, analysis, source tooling, or a declared semantic contract.

2. Semantic frontend ownership

Wright owns independent semantic frontends where required for standalone compilation, source-aware analysis, agent source editing, CI, WASM/embedding, and long-term ecosystem independence.

Current/future ownership:

• vanilla Workshop: Wright-owned canonical model, parser, emitter, target semantics;
• OPY: Wright-owned compatible semantic frontend;
• OSTW: future first-class compatible semantic frontend, introduced only through an evidence-backed milestone.

Upstream compilers/language services remain compatibility oracles, behavior references, and test inputs. They are not production runtime dependencies for supported standalone workflows.

3. Compatibility targets observable semantics

The compatibility contract is semantic compatibility, not compiler-output identity.

Byte-identical output, identical temporary-variable allocation, identical optimizer output, or identical formatting are not goals unless a difference affects:

• observable Workshop/game behavior;
• valid Workshop syntax or native Workshop round-trip behavior;
• source/tooling contracts;
• an explicitly documented compatibility surface.

N-level normalized-output evidence remains useful for finding regressions, but it is supporting evidence rather than the ultimate product objective. Reference-output differences that are presentation-only must not automatically create implementation work.

4. Legacy/reference quirks

Default compatibility should preserve corpus-evidenced observable upstream behavior where real projects may depend on it. A future strict/fixed mode may diagnose or correct known quirks, but this issue does not require implementing such a mode.

Keep language semantics, compatibility semantics, and legacy quirks conceptually distinguishable.

5. Do not fork source languages

Wright may independently track new Workshop content (heroes, actions, values, enums, settings, maps, localization/catalog data) and may expose controlled/user-defined catalog or post-compile extension mechanisms where justified.

Wright must not invent Wright-only OPY/OSTW syntax or language features as a shortcut. Language-level evolution belongs upstream or behind an explicit experimental proposal that does not silently redefine compatibility.

6. Conversion matrix

Workshop is the interoperability hub.

Required long-term capabilities:

• OPY -> Workshop;
• OSTW -> Workshop;
• Workshop -> OPY;
• Workshop -> OSTW;
• Workshop -> Workshop.

Direct OPY <-> OSTW source conversion is optional and must not drive the core architecture prematurely.

7. Source-edit model

Agent/refactoring tooling should primarily use semantic, validated source edits against the original source. Full AST/IR regeneration with formatting/comment preservation is not the default mutation model.

8. Support claims are corpus-defined

"Supported" means the declared corpus/surface is parseable, semantically understood, compilable where compilation is claimed, and analyzable through the declared tooling contracts.

It does not guarantee successful execution in every live Overwatch runtime. Runtime-sensitive claims require separate evidence.

Scope

• Write a superseding architecture ADR rather than rewriting ADR-0001 history.
• Reconcile ARCHITECTURE.md with the decisions above.
• Update COMPATIBILITY.md / ADR-0002 where wording gives normalized-output parity inappropriate product priority.
• Update README.md product positioning from compiler-first wording to tooling-first semantic-platform wording while preserving factual current capabilities.
• Reconcile docs/v1-matrix.md with the post-M11 settings reality and the semantic-vs-output compatibility distinction.
• Audit active roadmap issues for assumptions invalidated by this rebaseline.
• Preserve historical milestone/issue text where it is useful history; do not rewrite completed work merely to make history look consistent with the new decision.

Non-goals

• Implementing OSTW support.
• Implementing Workshop -> OPY/OSTW conversion.
• Implementing a lint plugin host.
• Removing the existing native .opy frontend, language services, or LSP.
• Reworking HIR/WIR without a concrete contract gap.
• Closing M11 from issue state alone.

Deliverables

• Superseding ADR for the current project/product boundary.
• Updated ARCHITECTURE.md.
• Compatibility-contract wording aligned with semantic compatibility.
• Updated README/v1 status docs where they are stale.
• A concise roadmap-impact note identifying which historical assumptions are superseded and which implemented components remain valid.

Acceptance criteria

• No authoritative document simultaneously says native .opy parsing is both a v1 frontend and a v1 non-goal.
• Wright is explicitly described as tooling-first; compiler-grade semantic frontends are justified as enabling infrastructure and standalone capability, not as a language-rewrite goal.
• Compatibility documentation states that observable semantics outrank reference text identity.
• Upstream OverPy/OSTW implementations are references/oracles, not required production dependencies for supported standalone workflows.
• Workshop is documented as the canonical interoperability/target boundary.
• Required Workshop <-> OPY/OSTW conversion directions and optional direct OPY <-> OSTW conversion are recorded without prematurely designing their implementation.
• Source-oriented semantic edits are the default agent/refactoring mutation model.
• Corpus-defined support and live-runtime non-guarantee are explicit.
• Active post-M11 roadmap issues reference this rebaseline where it changes prioritization.

Planning notes

This is a contract correction, not a broad refactor. Prefer the smallest documentation/ADR changes that make the existing implementation and future roadmap internally consistent. Do not introduce implementation work merely to satisfy symmetry.