[OPY baseline] Implement semantic compatibility manifest and systematic builtin/member/signature coverage

[Teakowa]

Parent: #106
Depends on: #104, #105

Goal

Implement the Wright-owned OPY semantic compatibility manifest specified by #106 and use it to replace corpus-accidental builtin/member/enum resolution with a systematic, reference-validated semantic baseline.

This is the keystone implementation task from the #106 rebaseline. The manifest is compile-time language-compatibility metadata for the native OPY frontend; it is not the runtime/content registry deferred in #96.

Context

#106 established that Wright's parse surface is broader than its semantic/compile surface. Generic actions/values may parse and lower but fail only at Workshop emission, receiver/member coverage is manually limited, signatures/arity are not represented systematically, and KNOWN_ENUMS duplicates a separate subset of enum knowledge.

The accepted planning specification is docs/opy/compat-manifest-spec.md, backed by the pinned OverPy 9.7.10 reference documented in docs/compatibility/upstream-references.md and the category inventory in docs/opy/compatibility-baseline.md.

Concrete evidence includes chaseOverTime, isGameInProgress, getPlayersInRadius, setInvisibility, setStatusEffect, getThrottle, worldVector, receiver/member calls from #104, and the enum work from #105. These are evidence for semantic categories, not requests for symbol-specific special cases.

Scope

• Define and implement the smallest stable manifest schema needed by the native OPY frontend for:
  • builtin actions and values;
  • member actions and values;
  • receiver categories;
  • ordered parameter signatures and arity;
  • parameter enum domains;
  • enum domains and members;
  • source aliases that do not require advanced call-context semantics.
• Replace/absorb KNOWN_ENUMS and other duplicated OPY semantic lookup tables where the manifest becomes authoritative.
• Resolve builtin/member/action/value identity before Workshop emission so unsupported names and invalid contexts fail through the semantic/frontend diagnostic path rather than surfacing accidentally as emitter catalog misses.
• Link semantic entries to the existing Workshop emission catalog by canonical identity without duplicating localization/output spelling data.
• Add a deterministic validation/build path for the manifest.
• Use Wright-authored semantic data validated by systematic probes against the pinned reference. Do not mechanically convert or import OverPy implementation/data files into Wright core.
• Add generated/table-driven reference tests for uniform metadata plus focused real/corpus fixtures proving end-to-end composition.
• Cover the evidence-backed generic/member/signature gaps identified by Establish a proactive OPY compatibility baseline from the pinned upstream language surface #106 as part of category-level coverage, not one-off parser branches.
• Enforce action/value/member context where the reference semantics are clear. In particular, do not preserve a Wright-only acceptance merely because the parser can represent it; cases such as a value member used as a statement must follow the declared OPY compatibility contract.
• Preserve source provenance and deterministic structured diagnostics.
• Refresh the OPY support matrix and compatibility baseline to reflect the implemented boundary.

Non-goals

• Named/keyword argument binding or contextual ChaseReeval semantics; tracked separately after this manifest foundation.
• Context-sensitive parsing of ambiguous raw Workshop enum spellings; tracked separately.
• Implementing every legacy alias or historical OverPy quirk.
• Mechanical GPL data conversion.
• Runtime-downloadable catalogs, user overlays, content-version negotiation, or any other [v0.2 workshop-rs] Define Workshop catalog, locale, extension, and version boundaries #96 runtime registry work.
• OSTW implementation.
• Byte-identical compiler output where observable semantics and declared round-trip contracts already hold.

Acceptance criteria

• A versioned Wright-owned OPY semantic manifest exists and is the authoritative native-frontend source for the declared builtin/member/signature/enum baseline.
• The manifest is deterministic, validated, and reference-probed against the pinned OverPy 9.7.10 identity.
• KNOWN_ENUMS and equivalent duplicated semantic tables are removed or reduced to clearly justified non-overlapping data.
• Generic evidence-backed calls such as chaseOverTime(...) and isGameInProgress() resolve and compile when their reference-supported signatures are satisfied.
• Evidence-backed receiver/member calls and enum-gated members resolve through shared metadata rather than symbol-specific parser/emitter exceptions.
• Invalid arity, wrong action/value position, invalid receiver category, and invalid enum-domain arguments fail deterministically with source-located semantic diagnostics.
• Unknown action/value/member errors no longer depend on reaching the Workshop emitter merely to discover missing OPY semantic metadata.
• Existing supported OPY corpus/differential behavior remains green; new systematic reference tests cover the expanded baseline.
• The implementation does not reopen or implement [v0.2 workshop-rs] Define Workshop catalog, locale, extension, and version boundaries #96.

Relationships

• Implements C1 from Establish a proactive OPY compatibility baseline from the pinned upstream language surface #106.
• Enables the contextual enum-resolution and call-argument-semantics follow-ups.
• Reuses Fix real-world OPY receiver/member call compatibility (eventPlayer.setMoveSpeed and peers) #104/Add corpus-backed OPY builtin enum coverage for ChaseTimeReeval.NONE and nearby real-world gaps #105 as regression evidence rather than extending those closed issues.

[Teakowa]

Real-consumer evidence from the agent-lab pre-V1 migration (#69–#75) — pinned v0.1.0

The Workshop Agent tools migration exercised the released v0.1.0 binary against the real corpus (Bastion, plants-vs-zombies, D.Mon probes). These are the concrete, minimized gaps that currently force the documented explicit OverPy compatibility fallback; all are within the #106/#109 compatibility categories:

1. #!extension / #!mainFile preprocessing directives → unsupported-directive
   • repro: #!extension buffStatusEffects (plants-vs-zombies src/main.opy); #!mainFile "../main.opy" (Bastion include chain).
2. @Hero / @Team <args> / @Slot rule directives → parse-error "unsupported directive '@Hero'" (D.Mon p1-identity.opy). OverPy accepts these; the D.Mon fresh-hero capability cases are blocked on them.
3. Numeric enum members Team.1 / Hero.1 → parse-error "expected a member name after '.' (repro: while getNumberOfPlayers(Team.1) < 12:). Extremely common in real OPY.
4. createWorkshopSettingHero(...) builtin misparses as a settings block → settings-placement "settings block must be the first construct in the file" (D.Mon p2e-settings.opy). The minimized form with the declared variable reports unsupported-member instead — either way the builtin is outside the surface.
5. for i in range(...) loops → unknown-identifier 'i' (repro: for i in range(0, 10): ...). The docs/support matrix lists for loops as supported; the released binary rejects every form tested (range(n), range(a,b), list iteration). Misleading diagnostic — reads like a genuine undeclared identifier.

No Agent-side semantic workaround was embedded for any of these: the adapter declares the boundary explicitly (see tools/lib/wright/backend.js DECLARED_UNSUPPORTED_SURFACE) and falls back to OverPy only with a visible marker; unknown-identifier is never a fallback trigger. A release that includes the compatibility-manifest work would let the tools retire the corresponding fallback entries.

[Teakowa]

Implementation evidence — #109 semantic compatibility manifest

Implemented and verified on main @ commit 9b12b93a10f18815f2e3dd150470900ee974f2ae (not pushed).

What was implemented

Manifest (crates/wright-opy/src/manifest/, schema v1 per docs/opy/compat-manifest-spec.md):

• data/manifest.json — the authoritative builtin table: 39 generic action/value + member action/value entries (receiver categories Player/Variable/String, ordered params with enum domains and defaults, catalogId linkage to the Workshop emission catalog, per-entry oracle probe evidence), 12 enum domains (reference-validated member lists), 3 non-contextual aliases (stopChasingVariable, getCurrentHero, hasStatusEffect), pinned OverPy 9.7.10 reference identity.
• mod.rs — deterministic load/validate (duplicate ids, undeclared domains, undeclared enum-default members, missing evidence, alias target checks) + canonicalize; embedded probes record; Manifest::builtin() via OnceLock.
• probes/ — 30 Wright-authored probes + probes.json (source hash, expected oracle status, emission hash, diagnostic category) + validate.py (S/D-level oracle validation), wired into compatibility/tests/test_manifest_probes.py.

Frontend wiring (crates/wright-opy/src/lower.rs): builtin identity, action/value position, arity, receiver category, and enum-domain checks resolve during semantic lowering; KNOWN_ENUMS removed. Enum-domain defaults fill at lowering (chaseOverTime(g, 10, 3) → DESTINATION_AND_DURATION; getPlayersInRadius(p, 10) → Team.ALL, LosCheck.OFF) matching the oracle emission. Aliases rewrite HIR names to canonical targets. range is for-iterable-only. Members the pinned reference rejects (e.g. Color.CYAN, DynamicEffect.SPARKLES) are no longer accepted.

New stable diagnostics (stage frontend, source-located): unknown-action, unknown-value, unknown-member, invalid-arity, invalid-receiver, enum-domain-mismatch, action-in-value-position, value-in-action-position, invalid-call-context, invalid-iterable.

Emission catalog (crates/wright-workshop/src/catalog/data/catalog.json): oracle-transcribed en-US spellings for chaseOverTime, isGameInProgress, getPlayersInRadius, worldVector, getThrottle, setInvisibility, setStatusEffect and the Invis/Transform/Status/LosCheck domains (provenance note updated).

Language services: completion and semantic-token classification now read the manifest (duplicated BUILTIN_NAMES/RECEIVER_MEMBERS tables removed).

Regression coverage vs #106 evidence

#106 evidence	Status
chaseOverTime(A, 0, 30, ChaseTimeReeval.NONE) generic action gap	resolves + compiles; synthetic/chase-condition-agentlab now compiles natively to the oracle's exact emission; probe chase-over-time
isGameInProgress() generic value gap	resolves + compiles; probe is-game-in-progress
getPlayersInRadius(...).setStatusEffect(eventPlayer, 30) arity	rejected at resolution with invalid-arity (probe invalid-arity-member)
Enum-gated members (setInvisibility(Invis.ALL), getThrottle(), worldVector(...) Transform arg)	resolve + compile byte-identical to the oracle; probe enum-gated-members
Receiver methods (#104)	manifest entries with receiver categories; probe receiver-calls
Value member as statement (B.isAlive())	now rejected (value-in-action-position), matching the oracle (supersedes the earlier intentional-divergence note)
Diagnostic provenance limitation	unknown/misplaced builtins now fail at semantic resolution, not emission

Verification (all green)

• cargo test --workspace --all-targets --all-features — 46 test binaries, 0 failures; MSRV 1.85.0 -p wright-opy also green; cargo clippy --workspace --all-targets --all-features -D warnings clean; cargo fmt --check clean.
• cargo test -p wright-opy --test differential — corpus HIR parity preserved.
• python3 -m unittest discover -s compatibility/tests — OK (incl. new probe-validation test); python3 compatibility/run_oracle.py — 24/24 fixtures unchanged; python3 crates/wright-opy/src/manifest/probes/validate.py — all 30 probes match the pinned oracle; python3 scripts/run-scenarios.py — 7/7.
• End-to-end: wright compile of the agentlab fixture emits the oracle's exact normalized text (Is Game In Progress == True, Chase Global Variable Over Time(...), ...) and round-trips through the Workshop frontend.

Known limits (documented)

• Enum domains/members beyond the declared baseline stay baseline-planned; emission coverage stays corpus-scoped (manifest-valid members can still hit catalog misses).
• Alias targets (stopChasing, getHero, hasStatus) and contextual ChaseReeval ([OPY baseline] Implement named/keyword argument binding and contextual call semantics #110) remain out; Team.1/Team.2 spellings are a grammar-level gap.
• Variable references emit as Global.<name> (native canonical spelling) vs the reference's bare spelling — N-level presentation, semantically equivalent, round-trip valid.