Establish typed Workshop settings as a stable core API before 1.0

[Teakowa]

Goal

Make typed Custom Game settings a first-class, stable part of the workshop-rs public semantic API and use that work as the main pre-1.0 API-hardening track.

workshop-rs should expose Workshop concepts in a form that is natural for raw Workshop tooling and reusable by independent source-language implementations such as opy-rs, deltin-rs, and future consumers without copying settings schemas, locale mappings, validation, or emission behavior.

Context

The current repository already has strong raw Workshop, catalog, locale, hero/slot, settings, corpus, and conformance evidence. The current settings implementation also already knows important value kinds and carries settings facts across exact path tables, generated locale data, hero-setting data, validation, parser/emitter behavior, and source-preserving Settings nodes.

The next step is not to invent a generic configuration framework. It is to consolidate those Workshop facts into a canonical typed semantic model and ergonomic multi-consumer API that follows Workshop terminology and source structure closely.

For hero settings, the public semantic contract is effective applicability to a hero / logical ability target. Catalog authoring may use common definitions, explicit exclusions, and hero-specific additions to avoid duplication, but consumers should not need to know or depend on that internal organization.

Canonical setting identity should describe the setting concept rather than localized/display ability names where possible. Hero/ability specificity normally comes from SettingTarget using canonical hero + logical slot + optional variant semantics.

Numeric and percent settings should carry evidence-backed Workshop effective min/max ranges where available. Where Workshop clamps an authored out-of-range value, the model must distinguish authored value from effective clamped value without silently rewriting source. UI-only increment/step metadata is not part of the canonical contract without independent semantic evidence.

The existing Settings / SettingsNode tree remains the source-preserving carrier. Typed settings are a canonical semantic/query/edit layer over that carrier, not a replacement that requires whole-file regeneration.

Source-language/project carriers are deliberately outside this owner contract. .lobby, legacy OSTW/DeltinScript customGameSettings.json, OPY settings syntax, and future source-language-specific configuration formats remain owned by their source-language implementations; those consumers lower into the canonical typed settings API provided here. workshop-rs#33 was closed as not planned after this ownership review.

Execution issues

Typed settings foundation

• Define the canonical typed settings schema and hero applicability model #109 — Define canonical typed settings semantic facts/query model: identity, Workshop scope, semantic target, value domain, effective applicability, locale/provenance, and evidenced numeric bounds/clamping.
• Build the canonical typed Workshop settings catalog #110 — Build the canonical typed Workshop settings catalog. Depends on Define the canonical typed settings schema and hero applicability model #109. Common/exclusion/addition organization is a catalog-authoring concern, not a required public API.
• Expose typed settings query, validation, and source-preserving edit APIs #111 — Expose typed settings query, validation, semantic-value, and source-preserving edit APIs. Depends on Define the canonical typed settings schema and hero applicability model #109/Build the canonical typed Workshop settings catalog #110.

Source contract before API freeze

• Define the canonical Workshop comment and source-preservation contract #32 — Resolve the remaining Workshop comment/source-preservation contract separately; do not fold it into settings semantics.

1.0 candidate

• Harden the Workshop-facing Rust API for the 1.0 candidate #112 — Harden the Workshop-facing Rust API for the 1.0 candidate. Depends on Define the canonical Workshop comment and source-preservation contract #32/Expose typed settings query, validation, and source-preserving edit APIs #111 and downstream dogfood through separately owned consumer work.

#10/#21 remain evidence/seasonal-validation work and are not implementation dependencies for ordinary typed settings unless a real ambiguity requires live-client evidence.

Roadmap order

1. Semantic model first: settle Define the canonical typed settings schema and hero applicability model #109 before catalog/API implementation so identity, scope-vs-target, value-domain, applicability, and clamping semantics are not decided piecemeal in code.
2. Canonical data: Build the canonical typed Workshop settings catalog #110 reconciles current settings tables, hero-setting data, corpus/docs, locale mappings, numeric bounds, and mature reference implementations into one source of truth.
3. Developer API: Expose typed settings query, validation, and source-preserving edit APIs #111 exposes typed inspection/validation/semantic-value/editing over the existing raw carrier and establishes the first consumer-ready contract.
4. Consumer proof: after Expose typed settings query, validation, and source-preserving edit APIs #111 is released, create or update focused integration work in wright, opy-rs, and deltin-rs only where current consumers actually need changes. Source-language-specific settings syntax/carriers stay in those repositories.
5. Source preservation: finish/rebaseline Define the canonical Workshop comment and source-preservation contract #32 independently where comments/source attachment affect the durable WIR/source contract.
6. Freeze candidate: Harden the Workshop-facing Rust API for the 1.0 candidate #112 performs the one bounded pre-1.0 breaking API hardening pass, then establishes the post-freeze semver/API compatibility gate.

Do not start #112 as a broad cleanup while #109-#111 are still changing the settings contract.

Scope

• Treat workshop-rs as the canonical Rust implementation of the Overwatch Workshop language and reviewed static semantics.
• Provide stable, locale-independent setting concepts and explicit value domains.
• Preserve Workshop-native setting scopes/ownership structure rather than inventing a normalized replacement language.
• Model semantic targets separately from source scope, including hero and logical ability-slot targeting where applicable.
• Expose effective applicability without making catalog inheritance/deduplication strategy part of the required consumer contract.
• Reuse canonical hero + logical slot + optional variant semantics rather than deriving canonical identity from localized/display ability names.
• Keep localized Workshop labels as presentation/resolution data.
• Include evidence-backed numeric/percent effective bounds and clamping semantics where Workshop behavior supports them.
• Preserve the existing raw settings carrier, provenance, unknown/unsupported representation, and fail-explicit diagnostics.
• Make the resulting API suitable for raw Workshop tools and source-language lowering/reconstruction consumers.
• Use current raw Workshop corpus, documented Workshop surface, mature OverPy/OSTW behavior, and existing repository data as evidence; upstream implementations are references, not architecture owners.

Non-goals

• A generic schema/configuration framework unrelated to Workshop.
• Rust type-level programming that encodes every hero or applicability rule in generic parameters.
• Making common/exclusion/addition catalog authoring a mandatory public semantic abstraction.
• Assuming every hero or every logical slot has identical settings.
• Generating one giant bespoke Rust settings struct per hero.
• Encoding localized/display ability names into canonical setting identity when generic ability concepts + targets are sufficient.
• UI-only step/slider metadata without semantic evidence.
• Parsing or owning OPY/DEL/OSTW project/config carriers in workshop-rs.
• OPY/DEL/Wright syntax or product features in this repository.
• Guaranteeing that a statically valid Workshop program is accepted or behaves correctly in every current live Overwatch build.
• Modeling temporary live-service restrictions as static setting schema.
• Broad parser/emitter rewrites or architecture cleanup unrelated to the public contract.

Acceptance criteria

• The typed settings semantic model, catalog, and public Rust API are documented as stable Workshop-facing contracts.
• SettingDefinition consolidates existing path/type/locale/applicability/provenance facts rather than introducing a parallel source of truth.
• Canonical setting identities normally describe setting concepts rather than concrete localized/display ability names.
• Workshop source scope and semantic target remain distinct, intuitive concepts.
• Setting value domains are machine-readable and include evidence-backed numeric/percent effective min/max ranges where known.
• Evidenced clamp behavior preserves authored source value while making effective value queryable/diagnosable.
• Effective hero/ability applicability represents the reviewed surface without consumer-side schema hacks or exposing catalog inheritance details.
• Raw Settings source preservation and provenance remain available alongside typed query/edit semantics.
• Parser/validation/emission and supported locale conversion use the same canonical settings definitions rather than parallel tables.
• Source-language implementations can lower their own settings syntax/carriers into the public typed settings contract without copying Workshop settings data or semantics into their repositories.
• Define the canonical Workshop comment and source-preservation contract #32 has an explicit source/comment-preservation disposition before the 1.0 API surface is frozen.
• The public API is dogfooded through actual WrightKit consumers before it is treated as a 1.0 freeze candidate.
• Remaining pre-1.0 breaking changes are intentional, bounded, and justified by the Workshop-facing public contract rather than general cleanup.