Harden the Workshop-facing Rust API for the 1.0 candidate

[Teakowa]

Parent: #108
Depends on: #32, #111

Goal

Perform one deliberate pre-1.0 breaking API hardening pass after the typed settings and remaining source-preservation contracts are stable, then establish an intentional Workshop-facing Rust API suitable for long-lived multi-consumer use.

Context

workshop-rs is becoming the canonical Rust implementation of the Overwatch Workshop language and reviewed static semantics. Its public API should therefore be natural for raw Workshop tooling and independent source-language implementations, not an accidental exposure of repository/test/storage internals.

The crate currently exposes a broad module surface and public WIR/settings records that evolved rapidly during the 0.1.x convergence phase. That was appropriate before the semantic surface stabilized. Before 1.0, the project should intentionally decide which APIs are durable Workshop concepts, which catalog identities deserve ergonomic typed constants, how naturally extensible enums/records evolve under semver, and which evidence/storage/generator surfaces are not general consumer contracts.

Source-language-specific project/config carriers are not part of this freeze. workshop-rs#33 was closed as not planned after confirming that .lobby and legacy customGameSettings.json are DEL/OSTW integration formats rather than canonical Workshop formats. Consumers own those parsers and lower into the public settings contract from #111.

This is API hardening, not a general refactor.

Scope

• Audit the crate-level public module/item surface and classify each exposed API as durable Workshop/core API, explicit secondary/evidence API, or implementation/repository support detail.
• Keep Workshop concepts ergonomic and public where consumers genuinely need them: parser, canonical catalog identities, WIR, settings, source/provenance, validation, emission, locale conversion, Workshop-owned target analysis, and gameplay/settings query contracts.
• Review accidental public exposure such as storage/generator/test-support machinery and make it private or explicitly secondary where no real consumer contract justifies stability.
• Review WIR/settings/error structs and enums for semver evolution. Add forward-compatible evolution boundaries only where Workshop capabilities are naturally expected to grow; do not hide stable Workshop semantics merely for encapsulation.
• Provide ergonomic typed/generated constants for stable Workshop-defined identities where this materially improves consumers, while keeping user-authored identities dynamic.
• Reconcile constructors/accessors with real consumer needs so normal code does not depend unnecessarily on internal storage layout or localized string literals.
• Review structured error/category/span access for stable machine consumption.
• Document the distinction between workshop-rs static semantic validity and live-client/runtime acceptance.
• Dogfood the candidate API against wright, opy-rs, and deltin-rs through separately owned consumer integration work; any required consumer syntax/project/carrier changes remain in those repositories.
• After the candidate surface is proven, add a semver/public-API compatibility gate appropriate for post-1.0 maintenance.

Non-goals

• Parser/emitter rewrites because files are large.
• Generic manager/service/context/visitor layers.
• DRY refactors without repeated consumer evidence.
• Moving OPY/DEL/Wright semantics or project/config carriers into workshop-rs.
• Freezing catalog content so future Overwatch heroes/actions/settings require a major version.
• Guaranteeing that statically valid Workshop runs successfully in any particular live client build.
• Treating source-language consumer implementation as part of this repository.

Acceptance criteria

• Every public module/item category has an intentional documented stability role rather than being public by extraction/history accident.
• The normal API reads like Workshop concepts rather than compiler-framework abstractions.
• WIR/settings/error evolution rules allow expected additive Workshop evolution without unnecessary major-version churn while preserving explicit breaking-change semantics.
• Stable Workshop-defined identities have ergonomic typed access where useful; consumers do not need canonical string literals for ordinary common operations.
• User-authored identifiers and source data remain appropriately dynamic.
• wright, opy-rs, and deltin-rs can consume a released/candidate API without local Workshop catalog/settings/emitter duplication or compatibility workarounds; source-language-specific carrier parsing remains consumer-owned.
• Public docs state what 1.0 guarantees and explicitly separate static Workshop semantics from live-client/runtime evidence.
• A public API compatibility/semver gate is established only after the candidate surface is accepted.
• No unrelated architecture cleanup is required to close this issue.