enjine 0.1.0

data/docs/ARCHITECTURE.md

@@ -0,0 +1,141 @@
+# Enjine — Architecture
+
+Companion to [DESIGN.md](DESIGN.md). Describes how the code is laid out and why.
+Rules reference: Comprehensive Rules effective **2026-11-06**.
+
+## Folder structure
+
+```
+lib/enjine.rb                     # entry point; requires everything except card pools
+lib/enjine/
+  version.rb                      # VERSION, RULES_VERSION (pinned CR date)
+  errors.rb                       # Error hierarchy
+  rng.rb                          # PCG32, integer state -> JSON-exportable, deterministic
+  mana.rb                         # mana costs, symbols, pools
+
+  # ---- static world: cards & decks (no game state) ----
+  primitive.rb                    # Primitive base class + Registry (every mechanic registers here)
+  mechanics.rb                    # helpers to build primitives from data entries
+  card_definition.rb              # immutable, validated blueprint built from a data Hash
+  catalog.rb                      # id -> CardDefinition, conflict detection
+  deck.rb  player.rb  setup.rb    # decklists, players, compiled pairings
+
+  mechanics/                      # ONE PLACE PER MECHANIC: <category>/<mechanic>.rb, all registered primitives
+    types/ supertypes/ subtypes/  card types, supertypes, subtypes (permanent_types spell_types land saga auras_and_equipment ...)
+    keywords/                     keyword abilities, CR 702 (evergreen flags crew kicker ward station alternative_costs ...)
+    abilities/                    other abilities: stack_abilities (spell activated triggered loyalty), static, mana_ability,
+                                  replacement_effects, play_permissions, cost_changes, enters_tapped ...
+    triggers/                     trigger events grouped by what happens (zone_changes combat casting life ...)
+    costs/ effects/ filters/ counters/   one file per cost, effect (damage exile counters library ...), filter, counter kind
+    */base.rb                     shared bases of effects, triggers, filters, costs (abilities: stack_abilities.rb),
+                                  loaded first; a file requires any other mechanic it extends
+    selector.rb values.rb         who an effect applies to (target / self / you / each ...); amounts and conditions
+    linked.rb card_spec.rb ...    shared helpers: linked abilities, token/copy card specs, mana spent
+
+  # ---- dynamic world: a running game ----
+  game.rb                         # public facade: pending_decision / submit / apply / export / views
+  state.rb                        # State, PlayerState, GameObject (plain mutable structs)
+  engine.rb                       # the state machine: accessors, emit, options/submit!; one module per area below
+  engine/
+    pregame.rb priority.rb        # CR 103 start and mulligans; CR 117 priority
+    turn_structure.rb             # CR 500-502: advance!, steps, untap step, land plays
+    zones.rb                      # CR 400: create/move objects (through replacements), tokens, draw, tap
+    casting/                      # CR 601/602: casting.rb (announce, targets, cancel/rewind), payment.rb,
+                                  #   cast_choices.rb, costs.rb, target_counts.rb, alt_casting.rb, permissions.rb
+    mana_sources.rb               # CR 106/605: affordability, mana abilities, mana pools
+    resolution.rb entering.rb     # CR 608: resolve top of stack, fizzle; "as this enters" choices
+    triggers.rb                   # CR 603: matching events, pending triggers
+    combat.rb                     # CR 506-511: attackers, blockers, damage assignment
+    damage.rb                     # damage, life, counters
+    state_based_actions.rb        # CR 704 and game end (CR 104)
+    characteristics.rb            # CR 613 layer pipeline for P/T, continuous effects, cleanup
+    rules.rb copies.rb faces.rb ...   # player rules and control; copies (CR 707); faces; sagas, phasing, speed ...
+  steps.rb                        # 12 step objects with turn-based actions
+  events.rb                       # typed, serializable events + per-viewer redaction
+  decisions/                      # one class per decision kind
+    priority play_or_draw mulligan bottom discard casting(choose_target, pay_cost) combat(...)
+  actions/                        # options offered at priority
+    pass play_land activate_mana_ability cast(cast, activate)
+  snapshot.rb                     # export/import + full consistency validation (also the fuzz invariant)
+  view.rb  history.rb             # per-viewer views and histories
+
+  # ---- tooling (no game logic) ----
+  docs.rb                         # generates docs/reference/*.md + SUPPORTED.md from the Registry
+  agents/random.rb  fuzz.rb       # random legal player, invariant-checking fuzzer
+  cli.rb  cli/text.rb             # interactive hot-seat CLI + text renderer, --validate
+  deck_builder.rb                 # OPT-IN random constructed decks from a card pool
+exe/enjine
+examples/                         # ready-to-play decks and a card pool (not in the gem)
+spec/ unit/ integration/ e2e/ support/scenario.rb  fixtures/cards/ (the test and fuzz cards)
+docs/ DESIGN.md ARCHITECTURE.md MECHANICS_COVERAGE.md SUPPORTED.md(root) reference/ guides/
+```
+
+## Key design decisions
+
+### 1. Two worlds: static vs dynamic
+- **Static** (`CardDefinition`, `Catalog`, `Deck`, `Player`, `Setup`) is validated
+  once and frozen. Shared by every game spawned from a `Setup` — no per-game cost.
+- **Dynamic** (`State`, `GameObject`, ...) is plain mutable data. Objects refer to
+  definitions **by id** (`"forest"`), never by Ruby reference, so state is small,
+  Marshal-copyable, and serializable.
+
+### 2. The engine is an explicit state machine
+No Ruby call stack ever holds game progress. Turn, step, priority holder, pass
+count, stack and the pending decision are fields on `State`. `submit(option)`
+mutates the state one tick and `Engine#advance!` runs forward until the next
+decision is needed. This is what makes export (including the pending decision),
+import, transactional `apply`, `restart`, and replay possible.
+
+### 3. Mechanics are registered primitives (composition, not inheritance)
+```
+Primitive (base: name, category, description, rules[], params, example, validate/build)
+ ├─ category :type       -> Mechanics::Types::Land, (Creature, Instant, ... later)
+ ├─ category :supertype  -> Basic
+ ├─ category :subtype    -> Plains/Island/Swamp/Mountain/Forest
+ ├─ category :ability    -> ManaAbility (Triggered, Static, Activated ... later)
+ ├─ category :cost       -> Tap (Mana, Sacrifice ... later)
+ └─ category :effect     -> (DealDamage, AddCounters ... milestone 2)
+```
+A card is a *set* of type primitives plus a list of ability primitives. A card
+data block naming anything not in the Registry fails with
+`InvalidCardDefinition` and a full list of path-addressed errors. Docs and
+`SUPPORTED.md` are generated from the same Registry, so they cannot drift.
+
+### 4. Decisions and actions are small classes with one job each
+- `Decisions::*`: a kind of pending decision (`priority`, `mulligan`, `bottom`,
+  `discard`, `play_or_draw`). Each one has `options(engine, pending)` and
+  `submit(engine, pending, option)`.
+- `Actions::*`: what you can do at priority (`pass`, `play_land`,
+  `activate_mana`, and later `cast` / `activate`). Priority options are the union
+  of every registered action's options. Adding casting means adding one Action class.
+- Options are plain frozen hashes (`{type: "play_land", object: "forest#12"}`), so
+  they are JSON-able and comparable with `==`.
+
+### 5. Events are the single source of change
+Every mutation emits a typed event (`Data` classes). Events feed history, the CLI
+log, subscribers and test assertions, and triggered abilities later. Each event
+knows how to redact itself for a viewer: a library→hand move shows only "drew
+a card" to the opponent.
+
+### 6. Determinism and IDs
+- PCG32 RNG, with its state stored as an integer in the snapshot.
+- Object id = `<definition_id>#<n>` from a per-game counter. A card gets a new id
+  on every zone change (CR 400.7).
+- `Setup` + seed reproduces a game exactly, and `restart` uses the same path.
+
+### 6a. Cards outside the game
+A game doesn't know about a match, so a deck's optional `outside` list stands for the
+cards its player owns outside the game (a constructed sideboard, CR 400.11a, 100.4a).
+At setup each player gets `PlayerState#outside`, a list of definition ids. These are not
+objects, because outside the game isn't a zone and the cards have no ids yet
+(CR 400.11). `State#outside_lists` keeps the starting lists for `restart`. Both
+round-trip through snapshots, which check every id against the catalog. Legal actions
+name such a card `outside:<card id>`, and legality checks use a detached stand-in
+object that is never stored. The real object is created only as the card enters
+the stack or the battlefield (`Engine#bring_in_from_outside!`), owned by that player
+(CR 108.3). A cancelled cast puts the id back in the list.
+
+### 7. Atomicity
+`submit` validates against the legal options before touching anything. `apply`
+and `import` work on a Marshal copy and swap it in only on success. Events are
+buffered and delivered to subscribers only after success.

data/docs/DESIGN.md

@@ -0,0 +1,139 @@
+# Enjine — Design
+
+Enjine is a Ruby gem that runs two-player Magic: The Gathering games with strict
+Comprehensive Rules (CR) fidelity. It is pure gameplay infrastructure: no AI, no
+heuristics, no "smartness". Callers (a text CLI today, reinforcement-learning
+agents in a separate project later) drive it through an atomic decision API.
+
+## 1. Scope
+
+- **Standard.** The target is every mechanic on the cards of the current
+  Standard-legal sets, plus the core rules (CR 1–6) every game needs. Mechanics
+  found only on cards outside Standard, multiplayer and casual variants are out of
+  scope until a Standard card needs them. New Standard sets add mechanics; rotated
+  sets keep theirs.
+- Two-player constructed: 20 life, deck ≥ 60 cards, max 4 copies of a card
+  (basic lands and "any number" cards exempt). No sideboard tracking.
+- Single games, start to finish. No best-of-3 / match object.
+- The engine knows **no cards**: every card arrives as data, in a deck document or a
+  `DeckBuilder` pool. The test and fuzz cards live in `spec/fixtures/cards/`.
+- Pinned to a dated CR version. Code and tests cite rule numbers (`# CR 704.5a`).
+
+## 2. Cards
+
+- **Data-first.** Card definitions are pure data (JSON / Hash). No Ruby card code.
+- **Primitive registry.** Abilities are composed of named primitives: effects,
+  costs, targets/filters, triggers, conditions, amounts, keywords, continuous
+  effects, replacements. Each primitive declares: name, parameter schema,
+  description, JSON example, CR references.
+- **Validation.** Loading validates against primitive schemas. Unknown/invalid
+  pieces raise `InvalidCardDefinition` listing *all* errors with paths
+  (`abilities[0].effect[1].deal_damage.amount`).
+- **Composition for card types.** A card has a *set* of types; each type is a
+  rule module (timing, destination zone, characteristics). Keywords are modules.
+  Inheritance only for engine abstractions (`Ability`, `Effect`, `Cost`,
+  `Decision`, `Event`, `Zone`).
+- **Extension.** A new mechanic = a new primitive class registered by name.
+- **IDs.** Definition id = canonical slug of the unique card name
+  (`"Lightning Bolt"` → `lightning_bolt`).
+
+## 3. Players, Setup, Game
+
+- `Player` = name + deck document (card definitions + decklist). `ready?` only
+  when the deck is valid. Between games the deck can be edited freely
+  (swap/add/remove, any number of cards) and is re-validated. Editing while
+  seated in an unfinished game raises `DeckLocked`.
+- `Setup` = frozen, compiled once from two ready players: validated catalog
+  (union of both players' definitions; differing definitions under the same
+  name → `CatalogConflict`), compiled decks. All games spawned from a Setup
+  share compiled definitions in memory.
+  - `setup.new_game(seed:)` — cheap new game (new shuffle, die roll, mulligans).
+  - `game.restart(seed: nil)` — back to the opening; same seed = identical game.
+  - `Setup + seed` fully reproduces a game; training stores seeds, not states.
+- The engine runs setup itself: shuffle, die roll, play/draw choice, London
+  mulligan, opening hands.
+
+## 4. Decision API
+
+- `game.pending_decision` → `{player, kind, options}`; `game.submit(option)`.
+- **No auto-skip.** Every priority point is an explicit decision.
+- **Atomic.** Each decision is one small choice: cast/activate, choose target,
+  tap a mana source (manual mana — one source at a time), declare attackers,
+  declare blockers, order/assign damage, choose X, choose mode, mulligan, etc.
+- **Cancel** is allowed until all costs are paid; it rolls back everything done
+  during that cast/activation (card back to hand, sources tapped during the
+  payment untap; mana that was in the pool before stays). Once costs are paid
+  the spell is cast and cannot be undone.
+- Invalid submission raises `IllegalDecision` (with the legal options); state is
+  never partially mutated.
+
+## 5. State, Events, History, Views
+
+- Mutable state of compact structs indexed by id; seeded RNG; fully deterministic.
+- **Object ids**: `<definition_id>#<n>` from a per-game counter. A new id on every
+  zone change (CR 400.7).
+- **Events**: every change is a typed, serializable event (`DamageDealt`,
+  `ZoneChanged`, `LifeChanged`, `CounterAdded`, `StepBegan`, ...). Events drive
+  triggers, history, the CLI log and test assertions.
+- **History**: ordered log of (turn, step, player, decision, resulting events).
+  `history_for(player)` hides what that player cannot know; the observer history
+  shows everything.
+- **Views**:
+  - `view_for(player)` — that player's legal knowledge (opponent hand and
+    libraries as counts).
+  - `view_for(:observer)` — omniscient: hands, face-down cards, library order.
+  - `state` — raw internals, for tests/debugging.
+
+## 6. Export / Import / Fast-forward
+
+- JSON snapshot: full state, RNG state, pending decision; versioned schema.
+- Replay: seed + decision log.
+- `game.apply([decisions])` and snapshot import are **transactional**: all or
+  nothing; on failure the game is restored and the error names the failing
+  index and reason.
+- Deck rules apply to new games only; an imported state must be internally
+  consistent (valid zones, real objects, legal step, matching pending decision).
+
+## 7. Errors
+
+`Enjine::Error` → `IllegalDecision`, `InvalidCardDefinition`, `InvalidDeck`,
+`InvalidSnapshot`, `CatalogConflict`, `DeckLocked`.
+
+## 8. Testing
+
+Every mechanic ships with three levels:
+
+1. **Unit** — the primitive in isolation (schema, validation, effect on a
+   minimal state).
+2. **Integration** — scenario builder imports a board position, asserts legal
+   options, submits a decision, asserts resulting state and events.
+3. **End-to-end** — full games from two 60-card decks via `Setup`, scripted and
+   fuzzed (random legal options), with invariant checks after every step.
+
+RSpec. CI (GitHub Actions): RSpec, RuboCop, SimpleCov ≥ 95% line + branch,
+docs drift check, short fuzz run.
+
+## 9. Docs
+
+- Generated from the primitive registry: `docs/reference/*.md`, `SUPPORTED.md`.
+  CI fails on drift.
+- Hand-written guides in `docs/guides/`: game lifecycle, decision API, card data
+  format, adding a mechanic.
+
+## 10. Tooling & Performance
+
+- Ruby 4.0.x with YJIT. Zero runtime dependencies.
+- Dev: rspec, rubocop(-rspec), simplecov, benchmark-ips, stackprof,
+  memory_profiler. Benchmarks/profiling are rake tasks, not CI gates.
+- `exe/enjine`: text CLI, random decks from the pool, seats `human` / `random`.
+
+## 11. Milestones
+
+1. **Skeleton** — setup, zones, turn structure, priority, mulligan, lands, manual
+   mana, vanilla creatures, combat, SBAs, win/lose, export/import, CLI, fuzzer.
+2. **Stack** — instants/sorceries, targeting, countering, activated & triggered
+   abilities, cancel.
+3. **Continuous effects** — layers (CR 613), static abilities,
+   replacement/prevention, counters, auras, equipment.
+4. **Keywords & planeswalkers**.
+5. **Long tail** — copy, control change, exotic mechanics, larger pool.