Complete the user-facing forward OverPy language support contract

[Teakowa]

Parent: #1
Related: #314, #319, #333
Canonical locale dependency: wrightkit/workshop-rs#237
Historical rationale: ADR-0002

Goal

Make opy-rs language support a user-facing OverPy support contract, remove parallel shadow support databases, and close the pinned forward OverPy core language surface for the declared forward compiler scope.

Context

docs/language-support.md is read by OverPy users to answer practical questions such as whether dictionaries, macros, member functions, translations, settings, compiler directives, or specific control-flow forms are supported.

The current support system mixes that user-facing purpose with maintainer-oriented audit machinery. Human-readable Markdown, feature-contracts.json, pinned-overpy-audit.json, and conformance-manifest.json duplicate overlapping support state and can drift from code and from one another.

Compatibility checks must remain independent of the native implementation and grounded in pinned upstream behavior, representative projects, ordinary tests, and canonical Workshop contracts. That does not require a machine-readable shadow support database.

Bastion has already served as a real-project convergence gate through #319. Remaining forward-language closure should now be driven by owner tests, pinned reference comparisons, the broader structural work in #366, and other representative projects rather than reopening Bastion-specific fixes.

Scope

• Redesign docs/language-support.md as the canonical human-readable support index for OverPy users.
• Organize the support surface using OverPy concepts and source spellings rather than compiler/audit terminology.
• Use a small user-facing status vocabulary:
  • ✅ Supported
  • 🚧 Partial
  • ❌ Unsupported
• Cover the forward OverPy core surface explicitly, including:
  • syntax and expressions;
  • variables and assignments;
  • rules and annotations;
  • control flow;
  • arrays, dictionaries, and lambdas;
  • functions and member functions;
  • enums and constants;
  • project composition / multiple files;
  • preprocessing and macros;
  • JavaScript macros;
  • strings and translations;
  • custom-game settings;
  • Workshop output-language compatibility;
  • compiler directives and hooks;
  • OPY -> Workshop compilation.
• Keep Workshop -> OPY reconstruction as a separately stated capability; it does not gate forward-language completion.
• Remove feature-contracts.json, pinned-overpy-audit.json, conformance-manifest.json, and tooling/checks whose sole purpose is maintaining those duplicate support databases.
• Preserve the behavior through tests, differential probes, source-attributed fixtures/projects, and pinned upstream comparisons rather than duplicating test state as support-state JSON.
• Reconcile support claims against current code, tests, pinned upstream behavior, and representative workflows; do not preserve stale Markdown claims merely to keep the documentation green.
• Identify forward-language rows that remain 🚧 Partial and resolve them through focused owner-local implementation work.
• Treat pinned upstream core behavior as presumptively in scope unless an explicit product/compatibility decision marks a capability unsupported.
• Keep Bastion convergence already established by Converge Bastion compilation structurally on pinned OverPy #319 protected while resolving remaining forward-core gaps through their owning tests and compatibility work.

Non-goals

• Replacing executable tests or differential verification with documentation.
• Treating Markdown alone as proof that implementation is correct.
• Reproducing upstream internal architecture or data structures.
• Introducing a new machine-readable support database under another name.
• Requiring Workshop -> OPY reconstruction to be complete before forward OPY -> Workshop validation.
• Folding Bastion-specific compiler residuals into generic language-support implementation when they are genuinely project-level convergence issues.
• Duplicating canonical Workshop semantics owned by workshop-rs.

Acceptance criteria

• docs/language-support.md gives an OverPy user a direct, readable answer for every major language/compiler feature area without requiring knowledge of HIR, WIR, registry leaves, audit branches, coverage states, or internal manifests.
• Detailed support pages use real OverPy syntax/names and explain limitations in user terms.
• Public support status uses only Supported, Partial, and Unsupported.
• The JSON shadow support databases and their maintenance-only validation paths are removed.
• Remaining support claims are consistent with current executable evidence and code reality.
• Every pinned forward OverPy core feature is either ✅ Supported or explicitly ❌ Unsupported by an approved scope decision; no unresolved 🚧 Partial forward-core rows remain.
• The completion check uses independent tests or pinned reference/workflow validation appropriate to the capability.
• Bastion Use Bastion as a real-project compiler convergence gate #314/Converge Bastion compilation structurally on pinned OverPy #319 are completed real-project/compiler-convergence validation and are not the primary mechanism for filling ordinary language-surface gaps.

Ownership

• OverPy language surface, support contract, and forward compiler behavior: opy-rs.
• Canonical Workshop actions, values, enums, settings, validation, representation, and emission: workshop-rs.
• Wright consumes proven owner capability and must not compensate for missing OPY semantics.

[Teakowa]

PR #327 has landed the user-facing support contract. The remaining forward-language work is now decomposed by root capability:

• Complete core collection mutation and control-flow semantics #328 — collection mutation and control-flow semantics
• Complete the pinned OverPy callable and member-function surface #329 — callable and member-function surface
• Complete OverPy enum, constant, texture, string-entity, and contextual-domain coverage #330 — enum, constant, and contextual-domain coverage
• Complete OverPy translations and custom-game settings support #331 — translations and custom-game settings
• Complete source-visible compiler directives and optimizer behavior #332 — source-visible compiler directives and optimizer behavior

Suggested execution order:

1. Complete core collection mutation and control-flow semantics #328 and Complete OverPy enum, constant, texture, string-entity, and contextual-domain coverage #330 establish remaining core source/control/domain semantics.
2. Complete the pinned OverPy callable and member-function surface #329 and Complete OverPy translations and custom-game settings support #331 complete callable/project-facing language behavior; these may proceed in parallel where owner boundaries do not overlap.
3. Complete source-visible compiler directives and optimizer behavior #332 follows the stable semantic/lowering surface so optimizer and replacement convergence is measured against completed behavior.
4. Re-read docs/language-support.md against executable evidence and close Complete the user-facing forward OverPy language support contract #326 only when no pinned forward-core row remains Partial.
5. Resume Bastion convergence through Use Bastion as a real-project compiler convergence gate #314/Converge Bastion compilation structurally on pinned OverPy #319.

Workshop -> OPY reconstruction remains separate under #254. Compile-metadata parity is not a forward-language completion gate unless a concrete source-visible compatibility dependency is demonstrated.

[Teakowa]

Follow-up owner audit after PR #327 found one additional cross-repository prerequisite and several public-surface omissions:

• workshop-rs#237 now tracks the canonical Workshop locale set required by pinned OverPy 9.7.10.
• Support the full pinned OverPy Workshop output locale set #333 tracks downstream OPY compiler/CLI integration for those output locales.
• Complete the pinned OverPy callable and member-function surface #329 now explicitly includes the pinned built-in macro library, not only ordinary/catalog-backed callables.
• Complete OverPy enum, constant, texture, string-entity, and contextual-domain coverage #330 now includes OverPy-owned constants/textures and named string entities.
• Complete OverPy translations and custom-game settings support #331 now includes the documented external settings "..." / settings.opy.json form.
• Complete source-visible compiler directives and optimizer behavior #332 now explicitly covers the full directive families and keeps OPY replacement/optimizer policy in opy-rs.
• Complete core collection mutation and control-flow semantics #328 now makes clear that mutable dictionaries are not a missing target: pinned OverPy dictionaries are lookup/compile-time constructs rather than standalone mutable objects.

The previously demonstrated Workshop owner gaps around Remove From Array By Value and related canonical operations are already closed in workshop-rs; they are not current blockers for #328. Remaining del / continue / goto work should therefore stay in OPY lowering unless new canonical-boundary evidence proves otherwise.

[Teakowa]

Follow-up from the merged v0.1.50 audit (#348) is now tracked in #350.

A subsequent pinned-reference re-check showed that the temporary workshop-rs#248 issue was based on a false owner-gap interpretation: OverPy 9.7.10 does not support backward named goto; named gotos are resolved only to forward Skip distances, while RULE_START maps to Loop. workshop-rs#248 has therefore been closed as not planned.

Keep #326 open until #350 reconciles the remaining source/check residuals and support rows against fresh differential results.