- commit
- cdfcc2666875afc142e05e02b6a226084e3fa41f
- parent
- 8cb67adaa4f0c072d80da675303d79cf5ab1d777
- author
- Dami <dami.etoile@gmail.com>
No content changes.
No content changes.
No content changes.
No content changes.
No content changes.
No content changes.
No content changes.
No content changes.
@@ -0,0 +1,57 @@
1+# solver-state-search Specification2+3+## Purpose4+TBD - created by archiving change scale-solver-state-search. Update Purpose after archive.5+## Requirements6+### Requirement: Solver state SHALL have a canonical compact identity7+For one authored level, the solver SHALL encode each settled nonterminal state in stable authored-ID order for entities and stable system-ID order for automata. The identity SHALL include every dynamic value that can change a future transition: existence, position, and noun of each entity; phase of each automaton; and registered stateful-mechanic fields. It SHALL exclude values derived from those fields and SHALL reject a dynamic field with no codec registration.8+9+#### Scenario: Object order does not change identity10+- **WHEN** two settled snapshots contain the same surviving entities, coordinates, nouns, and automata phases but list objects in different array orders11+- **THEN** their compact solver identities are equal12+13+#### Scenario: Removal and phase change remain distinct14+- **WHEN** otherwise identical states differ by a removed entity or by one automaton phase15+- **THEN** their compact solver identities differ16+17+#### Scenario: Future mechanic state cannot be silently merged18+- **WHEN** two otherwise identical states differ in a registered gate, switch, or crumble field19+- **THEN** their identities differ; if that dynamic field lacks a registration, encoding fails with an actionable error20+21+### Requirement: Compact states SHALL round-trip through authoritative restore22+Encoding and decoding a settled state SHALL preserve its behavior under the public engine's next accepted movement or wait. Decoding SHALL use the authored level for static data and SHALL not apply noun transformations or advance automata until the subsequent turn.23+24+#### Scenario: One-link transformation survives round-trip25+- **WHEN** a state contains ROCK after `BABA IS ROCK` with `ROCK IS FLAG` also active26+- **THEN** encoding and restoring it leaves ROCK in place; a later accepted turn may transform it to FLAG27+28+#### Scenario: Automaton phase survives round-trip29+- **WHEN** two states share entity positions but have different automaton phases30+- **THEN** decoding each state restores its own phase and the next wait produces the same result as ordinary engine replay31+32+### Requirement: Solver search SHALL retain shortest-path and analysis behavior33+The compact breadth-first search SHALL preserve the real engine's accepted-transition graph. It SHALL return shortest paths, use the configured expansion cap, and preserve `--replay` and already-won reporting. It SHALL report BYPASS when the player never pushes a word and HANDS-OFF when no word moves by any cause. Search nodes SHALL not retain full cloned snapshots or full path strings.34+35+#### Scenario: Shortest route remains stable36+- **WHEN** core and bundled teaching levels are searched with the compact frontier37+- **THEN** solved/limited status, shortest route length, and BYPASS classification match the authoritative baseline under the same cap38+39+#### Scenario: A forbidden rule is never active40+- **WHEN** an author runs `--forbid "GAP IS CRATE"`41+- **THEN** the search rejects an initially active rule and every transition that activates it at any rule-evaluation phase, including a rule that disappears before the turn settles42+43+#### Scenario: Automaton word motion is distinguished from player work44+- **WHEN** an automaton pushes a word on a winning path and the player never pushes a word45+- **THEN** the solver reports BYPASS but not HANDS-OFF46+47+### Requirement: Fast solver transitions SHALL match public gameplay transitions48+An event-free engine transition SHALL return the same next gameplay state or rejection as public `step()` and `wait()` for the same settled input. It SHALL expose word-motion provenance and every evaluated rule set needed by solver constraints without constructing presentation events or Undo history. The solver SHALL only enable this path after differential fixtures cover the current rule vocabulary and automata.49+50+#### Scenario: W6 contact and rule ordering match51+- **WHEN** a reachable state has stacked word alternatives, PUSH with STOP, noun transformation, or simultaneous WIN and DEFEAT contact52+- **THEN** the fast transition and public engine produce equivalent surviving entities, rules, automata phases, win state, and accepted status53+54+#### Scenario: Clockwork wait matches55+- **WHEN** a Clockwork state advances an automaton through a wait action56+- **THEN** the fast transition yields the same actor positions and next phase as public `wait()`57+