Expose typed settings query, validation, and source-preserving edit APIs

[Teakowa]

Parent: #108
Depends on: #109, #110

Goal

Expose the canonical typed settings definitions/catalog as an ergonomic Rust API for inspection, validation, semantic queries, and source-preserving edits while keeping Settings / SettingsNode as the raw carrier.

Context

#109 defines what a Workshop setting is; #110 provides the canonical reviewed data. This issue decides how Rust consumers use those facts without depending on localized strings, private path tables, or catalog-authoring internals such as common/exclusion inheritance.

The public API should therefore separate:

• the raw/source-preserving settings carrier;
• canonical SettingDefinition / value-domain / scope / target facts;
• ergonomic typed query/edit operations over actual settings occurrences.

Scope

• Expose typed lookup/schema queries for canonical setting definitions, Workshop scope, semantic targets/applicability, value domains, locale presentation metadata, and provenance.
• Expose typed read/write operations over Settings using canonical setting concepts rather than localized display names.
• Support hero and logical ability-slot targets through canonical hero/slot/variant semantics where applicable.
• Return/query effective applicability; do not require consumers to understand whether the catalog used common definitions, exclusions, additions, or explicit per-target entries internally.
• Reject non-applicable hero/slot settings explicitly rather than silently emitting unsupported fields.
• Reject wrong value kinds and invalid enum/list members with structured diagnostics and credible source/provenance where available.
• For numeric/percent settings with evidenced Workshop min/max clamp semantics, preserve the authored value while allowing semantic queries/diagnostics to expose the effective clamped value. Do not automatically rewrite source or classify an otherwise accepted clampable value as a type/syntax error.
• Keep localized names and aliases in parser/emitter resolution; normal Rust consumers should not need concrete localized Workshop labels or ability display names.
• Preserve unknown/evidence-insufficient raw settings and unrelated source structure when they are not being edited.
• Keep source editing patch-oriented where source provenance is available; do not make full-file regeneration the default edit model.
• Provide representative API documentation for lobby/gamemode settings, a normal hero/ability setting, an exceptional applicability case, and an evidenced numeric clamp case.
• Keep the API usable both for direct raw Workshop tooling and for source-language lowerers/reconstructors.

Non-goals

• A generic mutable object/schema framework.
• Exposing common/exclusion/addition catalog inheritance as a required public API.
• Type-level hero applicability encoded through Rust generics.
• Replacing the raw settings carrier with generated hero structs.
• UI-only step/slider metadata.
• Wright CLI/LSP/agent implementation.
• OPY/DEL source editing or source-language carrier parsing in this repository.
• Guaranteeing live Overwatch runtime acceptance beyond the reviewed Workshop semantic contract.

Acceptance criteria

• Consumers can discover a setting's canonical identity, Workshop scope, semantic target/applicability, value domain, localized presentation metadata, and provenance without reading generated data files.
• Common typed operations use Rust value types that prevent ordinary bool/number/percent/enum/list confusion before emission.
• Hero/slot applicability and exceptional cases are validated canonically with structured failure rather than guessed behavior or exposed catalog inheritance.
• Numeric/percent queries can distinguish authored value, supported effective range, and effective clamped value where Define the canonical typed settings schema and hero applicability model #109/Build the canonical typed Workshop settings catalog #110 provide evidence, while preserving source text until an explicit edit is requested.
• Normal consumer code does not need raw localized setting names, concrete ability display names, or private table paths for ordinary operations.
• Existing raw Settings parsing, provenance, unknown preservation, locale conversion, and deterministic emission remain intact.
• Typed edits preserve unrelated source/settings structure rather than requiring whole-file regeneration.
• Public examples demonstrate an API shape that is natural for an unrelated Rust source-language implementation to consume.
• Existing WrightKit consumers can migrate without introducing local Workshop settings schemas, locale maps, or numeric-bound logic.