# Project Phases

## Phase 0 — Specification Lock
In-scope deliverables:
- `packages/rete/SPEC.md` — engine semantics (10 sections)
- `docs/PHASES.md` — this document
- `packages/chess/RULES.md` — 15 preset custom rules with compat matrix
- `packages/server/PROTOCOL.md` — WebSocket protocol v1 (8+ message types)
- Monorepo scaffold: Bun workspaces, tsconfig base, eslint flat config, vitest workspace, playwright config, lefthook pre-commit hook, GitHub Actions CI
- Three package skeletons: `packages/rete`, `packages/chess`, `packages/server`

Acceptance gate (executable):
```bash
test -f packages/rete/SPEC.md && test -f docs/PHASES.md && test -f packages/chess/RULES.md && test -f packages/server/PROTOCOL.md
bun install && bun run check  # exits 0
gh run list --limit 1 --json conclusion -q '.[0].conclusion'  # "success"
```

Must NOT have in this phase: any engine implementation, any chess rules, any UI, any server logic.

## Phase 1 — Pararules Parity
In-scope deliverables:
- `packages/rete/src/schema.ts` — typed EAV schema + Fact type
- `packages/rete/src/wm.ts` — WorkingMemory with deterministic iteration
- `packages/rete/src/alpha.ts` — AlphaNetwork + AlphaMemory with inverted-index dispatch
- `packages/rete/src/session.ts` — Session lifecycle (init, add, insert, retract, fireRules)
- `packages/rete/src/builder.ts` — Typed rule builder + `v()` variable helper
- `packages/rete/src/registry.ts` — HandlerRegistry + PredicateRegistry
- `packages/rete/src/serialize.ts` — JSON round-trip serialization (RULE_SCHEMA_V1)
- `packages/rete/src/beta.ts` — BetaMemory + Token propagation
- `packages/rete/src/join.ts` — JoinNode with variable-binding equality tests
- `packages/rete/src/condition.ts` — FilterNode with registered predicates
- `packages/rete/src/query.ts` — query() / queryAll() API
- `packages/rete/src/derived.ts` — thenFinally + truth maintenance
- `packages/rete/src/cycle.ts` — RecursionLimitExceededError + recursion counter
- `packages/rete/src/conflict.ts` — deterministic activation ordering
- `packages/rete/tests/golden/` — pararules golden-file test port (5-10 tests)
- tsup build output: `packages/rete/dist/` with ESM + CJS + .d.ts

Acceptance gate:
```bash
bun test packages/rete  # all green
bun run test:coverage -- packages/rete  # ≥90% line coverage
bun run check  # exits 0
git tag v0.1.0-phase1  # after gate passes
```

Must NOT have: negation nodes, NCC, existential, aggregation (those are Phase 2).

## Phase 2 — Rete II + Chess Engine
In-scope deliverables:
- `packages/rete/src/negation.ts` — NegationNode (NOT)
- `packages/rete/src/existential.ts` — ExistentialNode (EXISTS)
- `packages/rete/src/ncc.ts` — NccNode (not-count-condition)
- `packages/rete/src/aggregate.ts` — AggregationNode (count/sum/collect/min/max)
- `packages/chess/src/schema.ts` — chess attribute schema (piece types, squares, colors)
- `packages/chess/src/coord.ts` — square coordinate helpers
- `packages/chess/src/starting-position.ts` — FIDE starting position fact generator
- `packages/chess/src/rules/` — all FIDE chess rules as Rete productions:
  - `primitives.ts`, `pawn.ts`, `knight.ts`, `sliding.ts`, `king.ts`, `turn.ts`, `capture.ts`
  - `castling.ts`, `enpassant.ts`, `promotion.ts`, `check.ts`
  - `checkmate.ts`, `stalemate.ts`, `draws.ts`, `insufficient.ts`
- `packages/chess/src/pgn.ts` — minimal SAN parser (no external dep)
- `packages/chess/tests/fide-games/` — 5 classic game PGN fixtures + replay tests

Acceptance gate:
```bash
bun test packages/rete  # Rete II nodes green
bun test packages/chess/tests/fide-games  # 5 games replay to completion
bun run check  # exits 0
git tag v0.2.0-phase2
```

Must NOT have: time-travel, UI, localStorage, server, presets, Playwright.

## Phase 3 — Time-Travel + Presets + UI
In-scope deliverables:
- `packages/rete/src/eventlog.ts` — append-only event log with monotonic seq
- `packages/rete/src/snapshot.ts` — Immer snapshots every N ticks
- `packages/rete/src/replay.ts` — replay engine + stateHash() determinism verifier
- `scripts/replay-determinism.ts` — CI replay verifier script
- `packages/chess/src/presets/` — all 15 preset rules with registry
- `packages/chess/src/ui/` — React + Vite chess app:
  - `Board.tsx`, `Rules.tsx`, `SavePanel.tsx`, `ImportExport.tsx`
- `packages/chess/src/persist/` — autosave.ts + io.ts
- `packages/chess/e2e/full-flow.spec.ts` — end-to-end UI scenario

Acceptance gate:
```bash
bun run playwright test packages/chess/e2e/full-flow.spec.ts  # green
bun run scripts/replay-determinism.ts  # all hashes match
bun run check  # exits 0
git tag v0.3.0-phase3
```

Must NOT have: WebSocket server, multiplayer, networked rooms.

## Phase 4 — Authoritative Multiplayer
In-scope deliverables:
- `packages/server/src/index.ts` — Bun HTTP+WS server
- `packages/server/src/protocol.ts` — zod message schemas
- `packages/server/src/rooms.ts` — RoomRegistry (6-char codes)
- `packages/server/src/middleware.ts` — rate limiting, origin allow-list, 64KB cap
- `packages/server/src/game-session.ts` — authoritative engine session per room
- `packages/server/src/broadcast.ts` — move validation + fact-delta broadcast
- `packages/server/src/reconnect.ts` — 60s grace reconnection
- `packages/server/src/logging.ts` — pino + Prometheus metrics
- `packages/chess/src/net/client.ts` — WS client with reconnect + seq ack
- `packages/chess/src/net/prediction.ts` — client prediction + reconciliation
- `packages/chess/src/ui/Lobby.tsx` — room create/join UI
- `packages/chess/e2e/multiplayer.spec.ts` — two-browser multiplayer scenario
- `scripts/ws-client.ts` — scripted WS client for integration tests

Acceptance gate:
```bash
bun run playwright test packages/chess/e2e/multiplayer.spec.ts  # green
bun run test:integration  # WebSocket handshake + move exchange + reconnect
bun run check  # exits 0
git tag v0.4.0-phase4
```

Must NOT have: spectators, AI opponent, server-side persistence across restart, mid-game rule toggle, accounts.

## Non-Goals (v1)
The following are explicitly out of scope for v1. Any agent that adds these will be considered scope-creep:
- Chess AI (Stockfish, minimax, MCTS, opening books)
- Puzzles, tutorials, analysis mode, engine evaluation
- ELO rating, matchmaking, tournaments, leaderboards
- Social features: chat, emotes, friend lists, profiles, avatars
- Rule marketplace, remote rule repository, user-authored JS rule upload
- Mid-game rule toggle (toggle only allowed between games)
- Spectators (2-player rooms only in v1)
- Server-side game persistence across server restart
- Mobile-native clients (responsive web only, no React Native / Capacitor)
- User accounts, OAuth, email/password, session tokens, analytics
- Telemetry, crash reporting, A/B testing, feature flags
- Internationalization (i18n), accessibility beyond keyboard-playable chess
- Additional games on the engine (no "build another game as proof")
- Visual rule editor / node graph editor (preset toggle only)
- Pararules Nim macro equivalents via runtime code-gen or eval
- External Rete library dependency (greenfield)
- chess.js or any hardcoded FIDE chess library
- Stockfish.wasm or any external chess engine
- Persistent user data beyond localStorage

## Performance Budgets
These are contractual. CI enforces bundle size. Unit tests enforce microsecond budgets.

| Metric | Budget | Enforcement |
|--------|--------|-------------|
| `session.insert(fact)` | < 0.5ms @ 10,000 facts | Vitest benchmark |
| `session.fireRules()` | < 5ms for chess ruleset (64 rules, ~100 facts) | Vitest benchmark |
| Replay 1,000 events | < 500ms | `scripts/replay-determinism.ts` |
| Alpha dispatch 10,000 inserts | < 50ms | Alpha network benchmark test |
| 3-condition join on 100 entities | < 10ms | Join benchmark test |
| 1,000 Immer snapshots memory | < 10MB (structural sharing) | Snapshot memory test |
| Engine bundle (`@paratype/rete`) | < 50KB min+gzip | size-limit in CI |
| Chess bundle (`@paratype/chess`) | < 200KB min+gzip | size-limit in CI |
| Server broadcast p99 latency | < 50ms per delta | Server integration test |

## Demo Scenarios
One scripted demo per phase that proves the phase deliverable works end-to-end.

**Phase 0 Demo**: Specs and scaffold exist.
```bash
bun install && bun run check  # exits 0 with zero errors
cat packages/rete/SPEC.md | grep '^## ' | wc -l  # outputs 10
cat packages/chess/RULES.md | grep '^### ' | wc -l  # outputs 15
cat packages/server/PROTOCOL.md | grep '^### Message:' | wc -l  # outputs ≥8
```

**Phase 1 Demo**: Run pararules golden test suite.
```bash
bun test packages/rete/tests/golden  # all green
bun run test:coverage -- packages/rete  # "All files | XX% | ... " with ≥90% line
```

**Phase 2 Demo**: Replay Kasparov vs Topalov 1999 (27 moves to spectacular win).
```bash
bun test packages/chess/tests/fide-games/kasparov-topalov-1999.test.ts
# Output: "Kasparov vs Topalov: all 27 moves legal, checkmate detected ✓"
```

**Phase 3 Demo**: Full UI flow.
```bash
bun run dev --filter @paratype/chess &
bun x playwright test packages/chess/e2e/full-flow.spec.ts --headed  # watch in browser
```

**Phase 4 Demo**: Two-browser multiplayer with reconnect.
```bash
bun run start:server &
bun x playwright test packages/chess/e2e/multiplayer.spec.ts --headed  # watch two windows play
```