cat / miau-is-true
clone

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

main
miau-is-true / openspec / specs / solver-state-search / spec.md
spec.md 4.5K source

solver-state-search Specification

Purpose

TBD - created by archiving change scale-solver-state-search. Update Purpose after archive.

Requirements

Requirement: Solver state SHALL have a canonical compact identity

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.

Scenario: Object order does not change identity

  • WHEN two settled snapshots contain the same surviving entities, coordinates, nouns, and automata phases but list objects in different array orders
  • THEN their compact solver identities are equal

Scenario: Removal and phase change remain distinct

  • WHEN otherwise identical states differ by a removed entity or by one automaton phase
  • THEN their compact solver identities differ

Scenario: Future mechanic state cannot be silently merged

  • WHEN two otherwise identical states differ in a registered gate, switch, or crumble field
  • THEN their identities differ; if that dynamic field lacks a registration, encoding fails with an actionable error

Requirement: Compact states SHALL round-trip through authoritative restore

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.

  • WHEN a state contains ROCK after BABA IS ROCK with ROCK IS FLAG also active
  • THEN encoding and restoring it leaves ROCK in place; a later accepted turn may transform it to FLAG

Scenario: Automaton phase survives round-trip

  • WHEN two states share entity positions but have different automaton phases
  • THEN decoding each state restores its own phase and the next wait produces the same result as ordinary engine replay

Requirement: Solver search SHALL retain shortest-path and analysis behavior

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.

Scenario: Shortest route remains stable

  • WHEN core and bundled teaching levels are searched with the compact frontier
  • THEN solved/limited status, shortest route length, and BYPASS classification match the authoritative baseline under the same cap

Scenario: A forbidden rule is never active

  • WHEN an author runs --forbid "GAP IS CRATE"
  • 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 settles

Scenario: Automaton word motion is distinguished from player work

  • WHEN an automaton pushes a word on a winning path and the player never pushes a word
  • THEN the solver reports BYPASS but not HANDS-OFF

Requirement: Fast solver transitions SHALL match public gameplay transitions

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.

Scenario: W6 contact and rule ordering match

  • WHEN a reachable state has stacked word alternatives, PUSH with STOP, noun transformation, or simultaneous WIN and DEFEAT contact
  • THEN the fast transition and public engine produce equivalent surviving entities, rules, automata phases, win state, and accepted status

Scenario: Clockwork wait matches

  • WHEN a Clockwork state advances an automaton through a wait action
  • THEN the fast transition yields the same actor positions and next phase as public wait()