README.md

workshop-rs Documentation

This directory is the canonical documentation index for workshop-rs. The root README.md is the user-facing overview.

Documentation model

architecture/README.md       current architecture routing
  └─ current domain contracts
language-support.md          current declared support, backed by executable tests
domain/source docs           durable public contracts and fixture attribution
adr/                         point-in-time decisions and rationale
Issues / PRs / releases      mutable execution state
source / tests / data        current implementation reality

An accepted ADR is not current-reality proof. For implementation work, start from architecture/README.md, then inspect the relevant code/tests/data and current Issue contract.

Current architecture

• Architecture routing: current contract index and authority model.
• Workshop core boundaries: repository ownership, dependency direction, canonical WIR, source-language separation, and semantic-code versus declarative-data boundary.
• Workshop source layout: domain entry points, shared implementation boundaries, CLI verification tooling, and test-owned fixtures.
• Public API and compatibility contract: crate-root module exports, root re-exports, retired compatibility paths, and which public types may grow without a breaking change.
• Repository agent guidance: implementation routing, verification, source attribution, and delivery rules.

implementation-role.md is retained only as a compatibility pointer for older links.

Workshop language support

• Language support matrix: current declared Workshop capability surface, with component inventories in language-support/:
  • Program Structure & Variables
  • Events & Event Filters
  • Conditions & Control Flow
  • Operators & Variable Modifications
  • Actions Inventory
  • Values Inventory
  • Enumerated Domains
  • Custom-Game Settings
  • Strings & Localization
  • Tooling & Semantic Capabilities

Support prose is not a substitute for current executable tests.

Domain contracts and fixture attribution

• Source attribution: catalog, locale, gameplay, fixture, code, and pipeline source records.
• Source preservation contract: optional authored source, comment attachment, checked edits, source-mapping shape guard, canonical artifact formats, and mixed-source boundaries.
• Hero gameplay dataset: embedded data model and validation boundaries.
• Gameplay query API: read-only semantic queries and locale-aware ability resolution.
• Hero gameplay topology survey: source material used by the gameplay domain.
• Constant wrapper and settings-boolean forms: which constants are written with a wrapper and which boolean word settings use.
• Canonical action layout: validated WIR action-width and structured action expansion behavior.
• Test fixture source attribution: source origin and verification for raw Workshop/settings fixtures.

Architecture decision history

See ADR registry. ADRs explain why decisions were made; current architecture is routed from docs/architecture/.

Current registry:

• ADR-0001: Workshop catalog, locale, provenance, and version boundaries
• ADR-0002: Workshop conformance result and feature identity contract
• ADR-0003: Canonical sharded Workshop feature census
• ADR-0004: Provenance-linked real-project evidence
• ADR-0005: Seasonal Workshop client validation workflow
• ADR-0006: Canonical typed Workshop settings semantics
• ADR-0007: Hero gameplay domain API and provenance boundary
• ADR-0008: Canonical public Workshop Program boundary
• ADR-0009: Domain-local Workshop ownership and verification placement
• ADR-0010: Canonical Workshop target-layout and resource analysis
• ADR-0011: Contextual Workshop semantics at the catalog/code boundary
• ADR-0012: Tests-first Workshop verification
• ADR-0013: Source mapping across the provider boundary
• ADR-0014: Evidence for canonical validation of slot acceptance
• ADR-0015: Contextual literal substitutions are accepted, not normalized
• ADR-0016: Catalog content stays outside the Rust public API

Release and operations

• Release automation: release/publish workflow, artifacts, checksums, and maintainer runbook.

Note

Source-language syntax, runtime lowering, compiler quirks, and reconstruction remain owned by opy-rs / deltin-rs, even when those implementations consume canonical Workshop contracts from this repository.