Skip to content

refactor(api): align settings and gameplay source metadata - #259

Merged
Teakowa merged 2 commits into
mainfrom
codex/workshop-rs-254
Sep 22, 2026
Merged

Teakowa merged 2 commits into
mainfrom
codex/workshop-rs-254

Conversation

@e54-bot

@e54-bot e54-bot commented Sep 22, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Replace the superseded generic evidence/provenance vocabulary in the public settings and gameplay APIs with concrete source terminology: SettingSource, SettingSourceKind, SourceReference, sources(), MissingSource, and SourceUnavailable.
  • Preserve dataset identity, source attribution, licensing, review status, source mappings, and source-preserving edits; update the embedded gameplay JSON and digest to the sources schema.
  • Add public-contract and fail-closed tests for source metadata serialization and missing/stale source locations, and update the related architecture and API documentation.

Verification

  • cargo fmt --all --check
  • cargo clippy --workspace --all-targets -- -D warnings
  • cargo test --workspace --all-targets
  • cargo run -p workshop-rs --bin workshop-catalog-gen -- check
  • git diff --check
  • Independent ablation: changing the embedded gameplay JSON keys from sources back to evidence makes the loader test fail with missing sources.

cargo semver-checks check-release --package workshop-rs reports the intentional public renames against the current 0.4.4 baseline. This is the pre-1.0 contract change covered by parent issue #252; the compatibility gate should be evaluated against the corresponding 1.0.0 release baseline.

The downstream opy-rs settings test still references the pre-change SettingDefinition::provenance() API and should be updated when the owner revision is pinned after this change merges.

Fixes #254

@Teakowa Teakowa left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

crates/workshop-rs/src/gameplay/data.rs / gameplay.json: the required wire field changed from evidence to sources, but the gameplay schema is still version 1. This makes two incompatible JSON shapes claim the same schema version. It also exposes a loader bug: load() fully deserializes GameplayFile before checking schema_version, so a real old v1 payload now fails as Malformed(missing field sources) instead of UnsupportedSchema(1).

Please version this wire-format change (e.g. v2) and make the schema-version check happen before deserializing version-specific hero records (or otherwise preserve explicit old-schema rejection). Update the embedded schema/digest/docs and add a regression using an actual v1-shaped payload, not only current JSON with the version integer changed.

@e54-bot

e54-bot commented Sep 22, 2026

Copy link
Copy Markdown
Contributor Author

Addressed in 4927f68.

  • Bumped the gameplay wire schema from v1 to v2 for the evidence to sources field change.
  • load() now probes schemaVersion before deserializing version-specific hero records, so a real v1 payload returns UnsupportedSchema(1).
  • Added a regression using the v1-shaped payload, updated the v3 rejection case, refreshed the embedded digest, and updated the gameplay data documentation.

Validation passed locally: cargo fmt --all --check, workspace Clippy with -D warnings, cargo test --workspace --all-targets, and catalog check.

@e54-bot
e54-bot requested a review from Teakowa September 22, 2026 18:27

@Teakowa Teakowa left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@Teakowa
Teakowa merged commit adbef5b into main Sep 22, 2026
4 of 5 checks passed
@Teakowa
Teakowa deleted the codex/workshop-rs-254 branch September 22, 2026 18:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Align public settings and gameplay source metadata with the tests-first contract

2 participants