194 lines
9.2 KiB
Markdown
194 lines
9.2 KiB
Markdown
# 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
|
|
```
|