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 / rule-engine / spec.md
spec.md 12.3K source

rule-engine Specification

Purpose

Define deterministic grid state, movable word rules, turn resolution, contact effects, undo, and the settled event records consumed by presentation.

Requirements

Requirement: The engine SHALL represent a deterministic stacked grid state

The engine SHALL represent a level as a bounded rectangular grid containing uniquely identified object and word entities. Multiple entities, including words, SHALL be allowed in one cell, and a turn snapshot SHALL include positions, entity kinds, word text, active rules, move count, win state, and the complete history needed for undo.

Scenario: Multiple words share a cell

  • WHEN two word entities occupy the same coordinate
  • THEN both remain addressable and rule scanning considers both word texts at that coordinate

Scenario: Invalid movement is rejected

  • WHEN a caller requests a diagonal move, an out-of-bounds move, or a move after the level is won
  • THEN the engine leaves state and undo history unchanged

Requirement: The engine SHALL derive the MVP rule vocabulary from movable words

The engine SHALL scan horizontal and vertical straight lines for NOUN IS VALUE sentences, with adjacent AND terms expanding the noun side or value side. The initial semantic properties SHALL be exactly YOU, PUSH, STOP, WIN, SINK, and DEFEAT; a noun-to-noun value SHALL be treated as a transformation. Rules SHALL be recomputed from the current word positions after a turn that changes board state, including after contact effects remove word entities. The settled active rules, physical sentence spans, derived properties, and rule deltas SHALL describe only surviving words before the next player intent.

Scenario: An AND sentence expands to multiple properties

  • WHEN the board contains BABA IS YOU AND PUSH in one straight line
  • THEN the active rule table contains BABA IS YOU and BABA IS PUSH

Scenario: A moved word changes the active rules

  • WHEN a legal move changes the position of a word entity
  • THEN the engine replaces the active rule table with rules parsed from the new word positions before the next player intent

Scenario: A malformed line is ignored

  • WHEN a word line lacks IS or has no noun and value on both sides
  • THEN the line produces no active rule and does not make the turn fail

Scenario: SINK removes a rule word

  • WHEN a turn causes SINK to destroy the STOP word in ROCK IS STOP
  • THEN the settled state has no ROCK IS STOP rule or sentence span, the event reports that rule removed, and the next move onto ROCK is not blocked by STOP

Scenario: Contact removal updates derived control and automata

  • WHEN contact destruction removes a word granting YOU or a declared automaton property
  • THEN the settled state's control and automata carriers reflect the surviving words, and Undo restores the previous derivations

Scenario: A destroyed WIN word cannot grant a final victory

  • WHEN a contact destroys the word that supplied a surviving entity's WIN property
  • THEN the final victory check uses the surviving rule table and does not mark the level won from the destroyed word

Scenario: Restore a state after rule-word destruction

  • WHEN a settled snapshot lacking a destroyed rule word is restored or the level is reset
  • THEN the restored state derives rules from its present words, while reset restores the initial words and their rules

Requirement: The engine SHALL resolve controlled movement and pushes atomically

Entities whose noun has YOU SHALL receive the requested cardinal intent. A moving entity SHALL push a contiguous chain of PUSH entities when every destination is in bounds and free of STOP entities; a blocked chain SHALL not move any member. Word entities SHALL be pushable by default so that players can edit rules.

  • WHEN a YOU entity moves toward one or more adjacent PUSH entities with an empty in-bounds destination
  • THEN the chain moves one cell in the requested direction and the move count increases by one

Scenario: STOP blocks a push

  • WHEN a requested movement would push an entity into a STOP entity or outside the grid
  • THEN no entity moves and the move count does not increase

Scenario: Several YOU entities use stable ordering

  • WHEN more than one YOU entity receives the same intent
  • THEN the engine resolves them in a documented stable order and produces the same state for the same initial state and intent

Requirement: The engine SHALL apply transformations and contact effects deterministically

After movement, the engine SHALL apply active noun-to-noun transformations, then resolve contact effects using the MVP properties. SINK SHALL remove all occupants of a contact cell, DEFEAT SHALL remove controlled entities sharing its cell, and WIN SHALL mark the level won when a surviving entity has both YOU and WIN or when a surviving YOU shares its cell with a distinct surviving WIN entity. The engine SHALL expose the settled state only after these effects complete.

Scenario: A noun transforms

  • WHEN the active rule BABA IS FENN is present after a successful turn
  • THEN every object with noun BABA becomes noun FENN before the next rule scan

Scenario: Sink removes contact occupants

  • WHEN an entity with SINK shares a cell with another entity after movement
  • THEN every entity in that cell is removed before the turn is committed

Scenario: Defeat removes YOU

  • WHEN a YOU entity shares a cell with an entity having DEFEAT
  • THEN the controlled entity is removed and the level is not marked won by that contact

Scenario: A surviving same-entity YOU and WIN wins

  • WHEN a surviving entity has both YOU and WIN after transformations and contact destruction settle
  • THEN the engine marks the level won and the settled event reports won: true

Scenario: Distinct YOU and WIN entities still win

  • WHEN a surviving YOU entity shares a cell with a distinct surviving entity having WIN
  • THEN the engine marks the level won and rejects later movement until reset or progression

Scenario: Destruction takes precedence over same-entity victory

  • WHEN an entity with both YOU and WIN is removed by SINK or DEFEAT during contact resolution
  • THEN the entity is listed in destruction details and the level is not marked won by that removed entity

Scenario: Proof 03 reaches the win state

  • WHEN the authored proof 03 rule MIAU IS YOU AND WIN is active and the controlled MIAU completes its winning move
  • THEN the settled state and event report won: true, and the browser opens the existing Win scene

Requirement: The engine SHALL support complete turn undo and reset

The engine SHALL save the complete pre-turn state before each successful movement and SHALL restore it with undo. reset SHALL restore the original level, clear history, clear the win state, and rebuild rules and derived effects.

Scenario: Undo restores a rule edit

  • WHEN a successful push moves a word and the caller invokes undo
  • THEN the word positions, active rules, objects, move count, and win state match the state before that push

Scenario: Undo with no history is harmless

  • WHEN the caller invokes undo before any successful move
  • THEN the engine returns a false or equivalent no-op result and leaves the state unchanged

Scenario: Reset returns to the level start

  • WHEN the caller invokes reset after any sequence of moves and effects
  • THEN the initial entities and rules are restored, move count is zero, win is false, and undo history is empty

Requirement: Active rules SHALL identify their source words

Each active semantic rule SHALL expose the word entity IDs that formed it in reading order and whether the sentence runs horizontally or vertically. Duplicate semantic rules at different physical locations SHALL remain deduplicated in the active rule table while retaining deterministic source information. The settled state SHALL additionally expose sentences, an ordered list of every physical maximal sentence span as { ids, axis }. A span that is a strict subset of a longer span on the same axis SHALL be omitted; exact duplicate sentences at different locations SHALL both remain.

Scenario: A horizontal sentence reports its source

  • WHEN adjacent word entities form MIAU IS YOU from left to right
  • THEN the resulting semantic rule identifies those word IDs in order, reports horizontal axis, and state.sentences contains the physical span with those ids and axis h

Scenario: A vertical sentence reports its source

  • WHEN adjacent word entities form ROCK IS PUSH from top to bottom
  • THEN the resulting semantic rule identifies those word IDs in order, reports vertical axis, and state.sentences contains the physical span with those ids and axis v

Scenario: Exact duplicate sentences remain physical spans

  • WHEN two separate word runs form the same semantic sentence
  • THEN the active rule table contains one semantic rule while state.sentences contains both physical spans

Scenario: Strict subsets are removed

  • WHEN a candidate span is a strict subset of a longer valid span on the same axis
  • THEN state.sentences contains only the longer maximal span

Scenario: Stacked words create separate spans

  • WHEN two noun words share a cell and each forms a valid sentence with the same following words
  • THEN state.sentences contains one span for each physical noun path

Requirement: Engine actions SHALL return settled turn events

step, undo, and reset SHALL return an event record after resolving state. Every record SHALL have kind: 'step' | 'undo' | 'reset', accepted, ordered moved, full-record rulesAdded and rulesRemoved, ordered transformed, ordered destroyed, controlLost, and final won fields. A blocked or invalid step SHALL retain kind: 'step', report accepted: false, and leave state unchanged.

For movement, each entry SHALL be { id, from, to, pushedBy }, where pushedBy is the immediate pusher's entity id or null for a directly controlled mover. A physical block SHALL be { id, dir, blockerId, reason }, where blockerId is the blocking entity id or null at the board edge and reason is stop or bounds. Rule delta entries SHALL be complete rule records with subject, predicate, sourceIds, and axis. Destroyed entries SHALL be { id, noun|text, at, cause } with cause sink or defeat. Arrays SHALL preserve engine resolution order: movement, transformation, destruction, then win evaluation. controlLost SHALL be true when the settled state has no YOU entity.

Scenario: Breaking a rule produces a rule delta

  • WHEN a successful push moves a word out of a sentence
  • THEN the step result lists the word movement with from, to, and pushedBy, and lists the removed rule as a full record retaining its former sourceIds and axis

Scenario: A blocked push produces no state change

  • WHEN a push chain is blocked by STOP or the board edge
  • THEN the step result has kind: 'step', reports accepted: false, identifies id, dir, blockerId, and reason, and leaves move count and history unchanged

Scenario: Undo reports a restored state

  • WHEN a successful move is undone
  • THEN the undo result has kind: 'undo', reports accepted: true, the reverse movement with pushedBy: null, the rule changes, controlLost, and the restored win state

Scenario: Contact destruction includes presentation details

  • WHEN a SINK or DEFEAT interaction removes an entity
  • THEN the step result lists its id, noun or text, cell coordinate, and cause in the destruction order

Scenario: Control loss is explicit

  • WHEN a settled step removes the last entity with the YOU property
  • THEN the step result reports controlLost: true even though the state remains inspectable for the loss feedback

Scenario: Event arrays preserve resolution order

  • WHEN one accepted step moves entities, transforms an object, destroys contacts, and evaluates a win
  • THEN the event arrays retain movement order first, transformation order second, destruction order third, and the final win result after those phases