1## Why23The engine is ready for dynamic rules and automata, but it has no shared4contract for mechanics that carry state across turns. Gates, switches, and5one-step tiles will otherwise add fields that work in play but disappear on6Undo, restore, sharing, or solver replay. The solver already has an explicit7registry for compact mechanic fields, but the gameplay engine and mod boundary8do not provide the corresponding lifecycle.910## What Changes1112- Define a versioned, declarative mechanic metadata contract for levels and13 CommonJS packs.14- Add an engine-owned `state.mechanics` envelope initialized from authored15 metadata and carried through reset, turns, Undo, restore, and `getState()`.16- Define named mechanic turn hooks around the existing movement, transform,17 automata, and contact phases without allowing arbitrary mod code to run.18- Extend settled events with normalized mechanic transitions and diagnostics.19- Preserve mechanic metadata through normalized packs, data-only sharing, and20 CommonJS export/import.21- Require every dynamic mechanic field to register a deterministic compact22 solver representation and fail closed when state is unregistered or cannot23 round-trip through authoritative restore.2425This change defines the foundation only. It does not decide gate occupancy,26switch edge behavior, FRAIL timing, crumble leftovers, or any other mechanic's27gameplay semantics. Those behaviors belong in separate changes with world28fixtures and design approval.2930## Capabilities3132### New Capabilities3334- `declarative-mechanic-state`: validated mechanic metadata, lifecycle state,35 events, snapshots, sharing, and solver registration.3637### Modified Capabilities3839None.4041## Impact4243The engine state and restore boundary, CommonJS/mod validation, normalized pack44and sharing paths, solver codec/transition setup, and focused tests will change.45Existing levels without mechanic metadata retain the current state shape and46behavior. Designer-owned rendering and world-owned level content remain out of47scope.