clone

a browser grid puzzle game where you push words around to rewrite the rules of each level

main
miau-is-true / openspec / changes / archive / 2026-09-24-add-rules-compatibility-revision / proposal.md
proposal.md 1.7K source

Why

manifest.engine identifies the shape of the mod API, but it cannot tell the host which interpretation of a valid board the pack was authored against. The W6 precedence and rule-reading changes alter puzzle outcomes while keeping the CommonJS data shape valid. Without a separate semantic revision, an older pack can load successfully and quietly play differently.

What Changes

  • Add a numeric manifest.rules compatibility revision for puzzle semantics.
  • Define revision 2 as the current post-W6 rules contract.
  • Treat a missing revision as legacy revision 1 for imported packs and emit a nonblocking W11 diagnostic explaining that the proofs may play differently.
  • Emit the same diagnostic for any known older revision while evaluating the pack with the host's current semantics.
  • Reject a pack that declares a future rules revision the host does not know, with an actionable compatibility error before installation.
  • Preserve the effective revision through local loading, shared links, exports, installed pack records, and pack preview views without serializing warnings.

Capabilities

Modified Capabilities

  • commonjs-mods: validate and normalize the semantic rules revision at the mod boundary.
  • level-sharing: apply the same revision compatibility and nonfatal warning contract to local and data-only shared previews.

Impact

The mod loader, pack service, share encoder/decoder, and first-party pack manifests are affected. Current packs should declare rules: 2; older packs remain loadable with a visible note. Engine behavior is never downgraded for an older pack, and the diagnostic remains outside authored data, snapshots, and portable warning-free payloads.