Establish a canonical fixture distribution and compatibility protocol

[knytcomics-ui]

Category

Advanced

Summary

Define and implement compatibility rules between published testkit versions and vendored downstream consumers.

Current Behavior

The adapter manually copies JSON and generated text modules; its contract test is pinned and scheduled.

Problem

A locally valid fixture release can break a downstream schema, generated module, or lookup assumption.

Why This Matters

The testkit is shared data infrastructure, so releases need explicit compatibility guarantees.

Proposed Scope

Define schema versions, additive/breaking rules, generated-file synchronization, supported consumer versions, deprecation policy, and release failure reporting.

Acceptance Criteria

• Compatibility rules are documented and machine-readable.
• Releases identify schema and supported consumers.
• At least one downstream revision is checked automatically.
• Generated modules are verified against published sources.
• Unsupported versions fail with migration guidance.

Technical Considerations

Coordinate with adapter schema validation and the existing consumer workflow.

Testing Requirements

Test additive fields, removed fields, stale generated modules, and unsupported versions.

Cross-Repository Impact

Directly affects the adapter and indirectly extension/research.

Out of Scope

Do not implement live oracle reads.

Complexity

Release policy, metadata, compatibility tooling, and coordinated CI.

Impact

Critical — protects downstream evaluation.

Suggested Labels

advanced, area: cross-repo, area: validation