houserules/.sisyphus/notepads/rete-rules-engine/learnings.md

[2026-04-16] Session ses_267b9d7a2ffeFkGcPFn1iv223J Start

Codebase State (Phase 3.8 complete)

• 323 tests pass, 0 fail across all packages
• Engine (packages/rete/src/): fully implemented — schema, WM, alpha/beta, join, filter, query, derived, negation, existential, NCC, aggregation, event log, snapshot, replay
• Chess (packages/chess/src/): all FIDE rules + 15 presets implemented
  • Presets in packages/chess/src/presets/registry.ts
  • Fact schema in packages/chess/src/schema.ts
  • Engine facade in packages/chess/src/engine.ts
• Chess package.json already has vite, @vitejs/plugin-react, react, react-dom, @types/react, @types/react-dom in devDeps
• No index.html, no src/app/, no UI files yet

Key Conventions

• Bun workspaces, bun test, NOT npm/node
• TypeScript strict: noImplicitAny, exactOptionalPropertyTypes, noUncheckedIndexedAccess
• ESLint flat config in eslint.config.js
• No as any, no @ts-ignore
• All tests: Vitest (not Jest)
• Tailwind for styling (per plan P3.9)
• React 19
• Square encoded as number 0..63
• Pieces as EntityId with multiple attrs

Chess Architecture

• Session from @paratype/rete — the game engine
• generateStartingPosition(session) — inserts 32 piece facts
• AttemptedMove fact = move intent
• LegalMove derived fact = legal moves per piece
• InCheck, GameOver derived facts
• Presets: PRESET_REGISTRY in packages/chess/src/presets/registry.ts
• engine.ts — higher-level facade wrapping Session

UI Requirements (P3.9-P3.15)

• Routes: Home (/), Game (/game), Rules (/rules), Save (/save)
• Board: [data-square="e2"], [data-piece="white-pawn"] selectors needed for Playwright
• Drag-drop: HTML5 DnD or react-dnd
• [data-action="undo"], [data-action="save"], [data-action="export"], [data-action="import"]
• [data-testid="app-root"] on root element
• [data-preset="{id}"] [data-role="toggle"]
• localStorage key: paratype-chess:v1:autosave