feat(thressgame-coverage): Wave 0-1 foundation (ADR + baseline + harness + audits)
Wave 0: - T0: Architectural decisions (10 sections, 215 lines) + 5-rule paper exercise Wave 1 (parallel): - T1: Backward-compat baseline fixture (1961 tests / 167 files snapshot + regression guard) - T2: Determinism property-test harness (runDeterminismCheck, N=100 default, 1.7s) - T3: State-hash util (SHA256 of session.allFacts, insertion-order independent) - T4: Position-attr caller audit (75 prod callsites classified, 17 fixes seeded for T6/T7) - T5: $var conflict audit (CLEAN — T12 binding shape safe) Tests: 1961 -> 1970 (+9). bun run check exits 0. No production source modified.
This commit is contained in:
parent
9e31b6d682
commit
2368a24b15
14 changed files with 3435 additions and 0 deletions
16
.sisyphus/boulder.json
Normal file
16
.sisyphus/boulder.json
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
{
|
||||
"active_plan": "/home/joey/Projects/rules/.sisyphus/plans/thressgame-coverage.md",
|
||||
"started_at": "2026-04-26T06:16:27.976Z",
|
||||
"session_ids": [
|
||||
"ses_237915a5bffeSdqajT9h0xNSOw",
|
||||
"ses_2378f187cffeYNxeH5yoqBIR96",
|
||||
"ses_2378879c7ffebbxu8yZx9ZafSB",
|
||||
"ses_23787ac28ffeViseRvpVkHGu6a",
|
||||
"ses_23783ab16ffeCNSrXoK1oU7I8s",
|
||||
"ses_2378026c8ffeZz47LuDzc1yyOK",
|
||||
"ses_237814da3ffetUoZjKTSOO0cB6",
|
||||
"ses_23780806affeiG673hb1eMrpsc"
|
||||
],
|
||||
"plan_name": "thressgame-coverage",
|
||||
"agent": "atlas"
|
||||
}
|
||||
215
.sisyphus/notepads/thressgame-coverage/decisions.md
Normal file
215
.sisyphus/notepads/thressgame-coverage/decisions.md
Normal file
|
|
@ -0,0 +1,215 @@
|
|||
# Architectural Decisions — ThressGame Rule-Coverage DSL Extension
|
||||
|
||||
> Source of truth for ALL 68 downstream tasks in `.sisyphus/plans/thressgame-coverage.md`.
|
||||
> Captured at Wave 0 (Task 0). Every locked invariant below MUST be honored by downstream
|
||||
> implementation; deviation requires a new plan, not an in-flight re-litigation.
|
||||
|
||||
## Scope and Coverage Target
|
||||
|
||||
- Target: 95%+ of ThressGame's 66-rule catalog expressible via the extended DSL.
|
||||
- Concrete count: ~62 of 66 rules expressible after this plan lands.
|
||||
- Explicitly deferred: `pacman_style` (board topology mutation — out of scope, separate plan).
|
||||
- Also deferred: ~3 nuance cases (animation-driven, free-text "narrative-only", or rules
|
||||
that depend on out-of-band UI affordances) — listed in plan appendix, not addressed here.
|
||||
- Locked parity test list (8 ThressGame descriptors recreated as `.json` fixtures):
|
||||
`minefield, mr_freeze, parry, all_on_red, religious_conversion, ice_physics, kamikaze, mind_control`.
|
||||
This list is FROZEN — additions require a plan amendment.
|
||||
- Coverage is verified by the paper exercise (5 hardest rules — see `paper-exercise.md`)
|
||||
plus the 8 parity Playwright e2e tests in `e2e/thressgame-parity.spec.ts`.
|
||||
- Coverage is NOT measured by line-of-code count; it is measured by descriptor
|
||||
expressibility: a rule "counts as covered" when its behavior is reproduced by a
|
||||
validator-clean descriptor that passes a deterministic e2e test.
|
||||
|
||||
## Activation Model
|
||||
|
||||
- NEW trigger `on-rule-activated` fires EXACTLY ONCE per modifier instance, at the
|
||||
moment the modifier attaches to a piece/game (i.e., when the rule "turns on").
|
||||
- Counterpart: `on-rule-expire` fires once when the modifier detaches (lifetime ends,
|
||||
piece captured, manual remove).
|
||||
- Imperative primitives (board-mutating: `set-piece-attr`, `spawn-marker`,
|
||||
`seed-attribute`, `cancel-capture`, etc.) are LEGAL ONLY inside trigger arrays —
|
||||
never as top-level descriptor body, never inside a passive aura.
|
||||
- Validator enforces this with error code `descriptor.primitives.imperative-in-passive`.
|
||||
- Passive primitives (predicates, aura emitters) remain pure / declarative as today.
|
||||
- Rationale: separates "describe the world" (passive) from "mutate the world"
|
||||
(imperative inside triggers). Mirrors Rete's truth-maintenance model — facts
|
||||
derive purely; mutations are explicit timed events.
|
||||
|
||||
## Square State via Marker Entities
|
||||
|
||||
- Marker = full session entity (id from `session.nextId()`), NOT a property bag on a square.
|
||||
- Required attrs on every marker (locked verbatim by plan T6, line 574):
|
||||
- `MarkerKind` — discriminator enum (8 kinds locked, see Marker Collision Priority).
|
||||
- `Position` — square the marker occupies; participates in same Position-attr index as pieces.
|
||||
- `MarkerLifetime` — `{ kind: "permanent" } | { kind: "moves"; expiresAtMove: number } | { kind: "one-shot" }`.
|
||||
- `permanent` — never auto-expires.
|
||||
- `moves` — absolute target move count; the marker expires when current move count reaches `expiresAtMove`. Field is an absolute target, NOT a countdown remainder.
|
||||
- `one-shot` — consumed (removed) by `on-piece-entered-marker` after firing once (cross-task contract noted in plan T18 / T22 line 1106).
|
||||
- Optional attrs:
|
||||
- `MarkerOwner` — `"white" | "black" | undefined`; used by mine/treasure scoping.
|
||||
- `MarkerLinks` — `readonly EntityId[]` for paired markers (e.g. portal endpoints).
|
||||
- New attr `EntityKind: 'piece' | 'marker'` audited across every existing `Position`-attr
|
||||
caller — move-gen, aura-compute, capture resolution, etc. — so that markers are
|
||||
filtered IN where they should participate (auras, on-piece-entered-marker) and
|
||||
filtered OUT where they should not (move legality, check detection, capture).
|
||||
- Markers participate in aura compute: an aura emitter may match against marker
|
||||
facts using a discriminator filter (e.g. "any frozen-square within radius 2").
|
||||
- Engine factory: `engine.spawnMarker(kind, pos, lifetime, owner?, links?)` mirrors
|
||||
the existing `engine.spawnPiece` pattern from `engine.ts:741-769`.
|
||||
|
||||
## Player Choice — Suspended Execution
|
||||
|
||||
- NEW imperative primitive `request-choice` halts trigger execution and returns
|
||||
control to the network layer pending a player decision.
|
||||
- WS protocol bumped to v2 (additive). New message types (plan T43, line 1440):
|
||||
- Server→client `RequestChoiceMessage`: `{ kind: "request-choice", choiceId,
|
||||
prompt: { kind: "piece"|"square"|"column"|"row"|"coin-flip"|"rps", filter?,
|
||||
forPlayer: Color, timeout? } }`.
|
||||
- Client→server `SubmitChoiceMessage`: `{ kind: "submit-choice", choiceId, value: unknown }`.
|
||||
- v1/v2 negotiation (plan T43, line 1442): server stores client's protocolVersion;
|
||||
if version mismatch and a request-choice would fire, server falls back to
|
||||
"auto-resolve with first option" AND emits a warning. Existing v1 message kinds
|
||||
remain byte-identical.
|
||||
- State storage: STACK on `GAME_ENTITY` (id 0) via attr `PendingChoices: readonly PendingChoice[]`.
|
||||
Plan T45 (line 1469) locks `PendingChoice` shape verbatim:
|
||||
`{ choiceId: string, descriptorId: string, triggerPath: readonly number[],
|
||||
primitiveIndex: number, bindings: Record<string, JsonValue>, kind, prompt,
|
||||
forPlayer, timeout?: number, expiresAtTimestamp?: number }`.
|
||||
No function references in the frame (must be JSON-serializable).
|
||||
- Helpers (plan T45, line 1470): `engine.pushPendingChoice`, `engine.popPendingChoice`,
|
||||
`engine.peekPendingChoice`.
|
||||
- LIFO ordering: nested choices push onto the stack; the player resolving the
|
||||
innermost choice pops their frame and the next-outer continuation resumes.
|
||||
- Nested choices ARE allowed. Maximum stack depth = 8 (plan must-not-do at line 1472:
|
||||
"allow >8 deep stack — cascade depth limit"). Validator enforces depth ≤ 8
|
||||
(plan deliverable line 75: "request-choice depth ≤ 8 check").
|
||||
- Resume mechanism (plan T46, line 1483): integration preset's `performAction`
|
||||
hook, on `submit-choice` action, pops top PendingChoice, restores bindings into
|
||||
a fresh PrimitiveApplyContext, resumes `runPrimitives` at saved `triggerPath` +
|
||||
`primitiveIndex + 1`, and injects the submitted value under the request-choice's
|
||||
`bind` key. No async/await anywhere.
|
||||
- `request-choice` primitive schema (plan T47, line 1496):
|
||||
`{ kind: "piece"|"square"|"column"|"row"|"coin-flip"|"rps",
|
||||
forPlayer: "chooser"|"opponent"|"both", filter?, bind: string, then: NodeArray }`.
|
||||
|
||||
## Trigger Reentrance — Deferred Queue
|
||||
|
||||
- Imperative primitives (e.g. a `set-piece-attr` inside `on-captured`) MAY indirectly
|
||||
cause additional triggers to fire (e.g. an `on-attribute-changed` watcher). To
|
||||
avoid stack-recursion bugs and arm reentrance hazards, these secondary triggers
|
||||
are ENQUEUED, not invoked synchronously.
|
||||
- Dispatcher rule: drain the deferred queue ONLY after the current arm has fully
|
||||
completed. One arm = one atomic dispatch frame.
|
||||
- Cascade depth limit = 8 (plan line 307: "matches existing RUNTIME_DEPTH_HARD_CAP").
|
||||
- Implementation (plan T15, line 942): each arm increments a `cascadeDepth`
|
||||
counter that is SEPARATE from the existing `depth` counter for nested
|
||||
primitives — they are orthogonal and MUST NOT be mixed (plan T15 must-not-do
|
||||
line 947). Reject when `cascadeDepth > 8`.
|
||||
- Overflow error code (plan T15, line 942): `runtime.cascade-depth-exceeded`.
|
||||
Runtime error, not validator, since cascade depth is data-dependent.
|
||||
- Existing 12-stage `onAfterMove` dispatch (apply.ts:996-1090) becomes 14-stage
|
||||
with the two new attach/expire stages slotted in.
|
||||
|
||||
## Move-Generation Dry Mode
|
||||
|
||||
- Move generator gains a `suppressTriggers: boolean` flag, default `false` for
|
||||
actual move commits, `true` for legality pre-check (move enumeration, mate detection).
|
||||
- Dry mode: triggers do NOT fire, RNG draws are NOT performed, markers are NOT
|
||||
spawned/expired, pendingChoices are NOT pushed.
|
||||
- Wet mode (commit): full dispatcher runs.
|
||||
- Rationale: avoids cycle risk where computing legal moves recursively re-enters
|
||||
trigger dispatch (e.g. "is this move legal?" → fires on-move → spawns marker →
|
||||
invalidates legality assumption). Dry mode = pure read.
|
||||
- Single source of truth: the `suppressTriggers` flag is checked at the dispatcher
|
||||
entry point; individual primitives do NOT branch on it.
|
||||
|
||||
## Seeded RNG
|
||||
|
||||
- PRNG: Mulberry32 (plan T28 line 697: "one-line, well-known, deterministic").
|
||||
- State storage: two attrs on `GAME_ENTITY` — `RngSeed: number` and `RngStream: number`.
|
||||
Seed initialized at game start (plan T28 line 698):
|
||||
`engine.session.insert(GAME_ENTITY, "RngSeed", deriveSeedFromGameId(gameId))`,
|
||||
`engine.session.insert(GAME_ENTITY, "RngStream", 0)`. `RngStream` increments
|
||||
per draw (line 697).
|
||||
- Helper (plan T28 line 699): `engine.rng()` returns
|
||||
`new SeededRng(RngSeed + RngStream)` and increments `RngStream` after every
|
||||
`next()` call.
|
||||
- Primitives that draw: `with-probability` and `random-pick`.
|
||||
- Determinism invariant (plan DoD line 89): N=100 replays of the same descriptor +
|
||||
same seed produce byte-identical state hashes. Asserted via property test.
|
||||
- "Draws-before-suspension" invariant (plan T34 line 1360 + must-not-do line 1361):
|
||||
RNG draw inside `with-probability` happens BEFORE any nested primitive arm runs;
|
||||
nesting `request-choice` inside `then`/`else` is REJECTED by the validator (V1
|
||||
simplification — "no draws-then-suspend interleaving"). Rationale: choice
|
||||
timeouts and disconnects must not change RNG output, or resume produces a
|
||||
divergent state.
|
||||
- NO `Math.random` / `Date.now` / unsorted Map iteration anywhere in the engine
|
||||
hot path (plan must-not-have line 107).
|
||||
|
||||
## Marker Collision Priority
|
||||
|
||||
- Markers are STACKABLE on the same square. When a piece enters a square containing
|
||||
multiple markers, they fire in HARDCODED priority order (lowest number first).
|
||||
- Priority table is fixed by this plan; it is NOT user-configurable:
|
||||
|
||||
```
|
||||
portal-end = 1 (lowest priority number = fires first)
|
||||
frozen-square = 2
|
||||
mine = 3
|
||||
pit = 4
|
||||
death-square = 5
|
||||
tornado = 6
|
||||
treasure = 7
|
||||
blocked = 8
|
||||
```
|
||||
|
||||
- Rationale for ordering: portal teleport must execute BEFORE any other effect (it
|
||||
changes which square the piece is actually on); freeze must execute before
|
||||
damaging effects so the freeze prevents the damage from dispatching turn-end
|
||||
recovery; treasure/blocked are passive markers that fire last because they alter
|
||||
legality not state.
|
||||
- New marker kinds beyond these 8 require a plan amendment with explicit priority
|
||||
insertion (no "auto-assign" for stability).
|
||||
- (Tie-break ordering for two markers of the same kind on one square is NOT locked
|
||||
by this plan — leave to T18 implementation. Do not invent a rule here.)
|
||||
|
||||
## Choice Timeout & Disconnect
|
||||
|
||||
- Per-game configurable in `CreateGameRequest` schema. Field shape locked verbatim
|
||||
by plan T50 (line 1542):
|
||||
`choiceTimeout: { mode: "timeout-with-default", seconds: number } | { mode: "no-timeout" }`.
|
||||
- Default value (plan T50, line 1542): `{ mode: "timeout-with-default", seconds: 60 }`.
|
||||
- On expiry in `timeout-with-default` mode: the FIRST option of the request-choice
|
||||
is auto-selected and the game resumes (plan interview-summary line 40).
|
||||
- Disconnect policy (plan T49, line 1529):
|
||||
- `timeout-with-default` mode + disconnect on a pending choice → forfeit the
|
||||
game (`GameStatus` set to opponent-wins).
|
||||
- `no-timeout` mode + disconnect → game enters "paused" state; no auto-action;
|
||||
resume on reconnect.
|
||||
- Must-not (plan T49, line 1531): cancel a pending choice on disconnect mid-choice
|
||||
without policy decision; forfeit in no-timeout mode.
|
||||
|
||||
## Locked Lists (Mirror)
|
||||
|
||||
This section duplicates lists fixed elsewhere in the plan so downstream tasks have
|
||||
a single read-once reference. If these lists ever drift between plan and notepad,
|
||||
the PLAN wins — but they MUST be re-synced before the affected wave begins.
|
||||
|
||||
- 8 parity test descriptor names (LOCKED — see plan deliverables):
|
||||
`minefield, mr_freeze, parry, all_on_red, religious_conversion, ice_physics,
|
||||
kamikaze, mind_control`.
|
||||
- 6 template descriptor names (LOCKED — shipped in modifier library):
|
||||
`simple-mine, vampire-on-capture, frozen-column, coin-flip-restriction,
|
||||
religious-bishop, no-mans-land`.
|
||||
- 6 palette categories (per Task 51): `State, Mechanic, Trigger, Imperative,
|
||||
Iteration, Restriction`.
|
||||
- 4 ParamField custom renderers (Task 50/T14 lineage):
|
||||
`square (square picker), piece (piece picker), marker-kind (enum select),
|
||||
lifetime (composite duration config)`.
|
||||
- Cascade depth limit: `8` (shared between trigger reentrance AND choice stack
|
||||
depth — same constant `RUNTIME_DEPTH_HARD_CAP` reused).
|
||||
- 28 new primitives total (frozen count — adding a 29th requires a new plan).
|
||||
- 4 new triggers total (frozen count): `on-rule-activated, on-rule-expire,
|
||||
on-piece-entered-marker, on-marker-expire`.
|
||||
- 8 marker kinds (frozen): see Marker Collision Priority section above for the
|
||||
authoritative priority-ordered list.
|
||||
187
.sisyphus/notepads/thressgame-coverage/learnings.md
Normal file
187
.sisyphus/notepads/thressgame-coverage/learnings.md
Normal file
|
|
@ -0,0 +1,187 @@
|
|||
# Thressgame-Coverage Executor Learnings
|
||||
|
||||
## [2026-04-26T00:27:55Z] T1 baseline fixture
|
||||
|
||||
### Captured Baseline
|
||||
- **Test count**: 1324 tests across 113 test files
|
||||
- **Primitive files enumerated**: 28 distinct `.test.ts` files in `packages/chess/src/modifiers/primitives/`
|
||||
- **Total test+expect assertions**: 21,846 expect() calls recorded across unit test suite
|
||||
- **Regression baseline**: ≥ 1324 tests required to pass regression suite
|
||||
|
||||
### Key Numbers
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| files | 113 |
|
||||
| tests | 1324 |
|
||||
| primitive test files | 28 |
|
||||
| min test count | 2 (registry-count.test.ts) |
|
||||
| max test count | 14 (on-moved-onto-square.test.ts) |
|
||||
| total primitive tests | 152 |
|
||||
| total primitive expects | 267 |
|
||||
|
||||
### Fixture Files Created
|
||||
1. ✅ `baseline-test-count.json` — snapshot of 1324 tests, 113 files, ISO8601 timestamp
|
||||
2. ✅ `baseline-primitive-tests.json` — array of 28 primitives with kind, file, testCount, expectCount
|
||||
3. ✅ `baseline-regression.test.ts` — 4-test Vitest regression guard
|
||||
- Validates JSON shapes
|
||||
- Asserts baseline tests ≥ 1324
|
||||
- File-by-file regression check for each primitive
|
||||
|
||||
### Verification Status
|
||||
- ✅ `bun test baseline-regression.test.ts` → **4 pass, 0 fail** (exit 0)
|
||||
- ✅ `bun run check` → **1961 tests passed** across 167 files (post-creation check)
|
||||
- ✅ **No breakage introduced** — all fixtures are non-intrusive read-only snapshots
|
||||
|
||||
### Dependencies & Handoff
|
||||
- **Blocks**: Waves 5–10 implementation tasks (primitive mutations will now trigger regression detection)
|
||||
- **Blocked By**: T0 ✅ (complete)
|
||||
- **Evidence**: `.sisyphus/evidence/task-1-baseline-test.txt` contains full `bun test` output
|
||||
|
||||
## [2026-04-26T06:29:52Z] T1 baseline correction
|
||||
|
||||
**Atlas verification fixes:**
|
||||
1. ✅ **Corrected baseline numbers** — used `bun run check` (canonical workspace command, not `bun test` from root)
|
||||
- Files: 113 → **167** (includes all packages: rete, chess, server)
|
||||
- Tests: 1324 → **1961** (full workspace count)
|
||||
2. ✅ **Real timestamp** — `2026-04-26T00:00:00Z` → **2026-04-26T06:29:52Z**
|
||||
|
||||
**Critical lesson**: The canonical test command in this repo is **`bun run check`**, which validates the entire workspace. Direct `bun test` from root or subpackages gives incomplete counts. Future regression baselines must use `bun run check` output only.
|
||||
|
||||
## [2026-04-26T07:15:00Z] T3 state-hash util
|
||||
|
||||
### Implementation Summary
|
||||
- **File**: `packages/chess/src/util/state-hash.ts` — 48 lines, exports `hashEngineState(engine: ChessEngine): string`
|
||||
- **Algorithm**: Deterministic SHA256 hash of session state via `session.allFacts()`
|
||||
- **Ordering**: Facts are already sorted by `allFacts()` as `[id asc, attr asc]`
|
||||
- **Session API used**: `session.allFacts()` returns array of `{ id, attr, value }` tuples
|
||||
|
||||
### Key Insight for T2 (Determinism Harness)
|
||||
The **Session API for iterating facts** is simple:
|
||||
```typescript
|
||||
const facts = engine.session.allFacts();
|
||||
for (const fact of facts) {
|
||||
const id = fact.id as number;
|
||||
const attr = fact.attr;
|
||||
const value = fact.value;
|
||||
}
|
||||
```
|
||||
No custom iteration method needed — `allFacts()` is public and sorted deterministically. T2 can reuse this exact pattern when building the determinism test harness.
|
||||
|
||||
### Tests Added (4)
|
||||
1. ✅ 64-char hex validation
|
||||
2. ✅ Identical engines → identical hash
|
||||
3. ✅ One fact difference → different hash
|
||||
4. ✅ Insertion-order independence (same entity, different attr insertion order)
|
||||
|
||||
### Verification
|
||||
- ✅ `bun test packages/chess/src/util/state-hash.test.ts` → **4 pass, 0 fail** (exit 0)
|
||||
- ✅ `bun run check` → **1965 tests passed** (1961 → 1965, +4 tests)
|
||||
- ✅ Evidence: `.sisyphus/evidence/task-3-state-hash.txt`
|
||||
|
||||
## T5 Verdict: Binding Shape — CLEAN
|
||||
|
||||
Audited 2026-04-26. Zero -prefixed keys or values found across:
|
||||
- 23 primitive implementations
|
||||
- 66+ paramsSchema definitions
|
||||
- All descriptor JSON fixtures
|
||||
|
||||
Binding shape `{ $var: "..." }` for T12 is safe to implement.
|
||||
|
||||
## [2026-04-26T06:36:00Z] T2 determinism harness
|
||||
|
||||
### Implementation Summary
|
||||
- **Files**: `packages/chess/src/__fixtures__/determinism/{harness.ts,harness.test.ts}` (97 + 84 lines)
|
||||
- **Public API**: `runDeterminismCheck(setup: SetupFn, moves: readonly MoveFn[], iterations = 100): DeterminismResult`
|
||||
- `SetupFn = () => ChessEngine` — fresh-engine factory invoked once per iteration
|
||||
- `MoveFn = (engine: ChessEngine) => void` — applies one mutation; closes over its own move lookup
|
||||
- `DeterminismResult = { hash, matches, iterations, mismatchAt?, mismatchHash? }`
|
||||
- **Algorithm**: For each iteration build a fresh engine via `setup()`, fold `moves` over it, hash via `hashEngineState()`, compare to iter-0 reference; bail early on first divergence and surface `mismatchAt` + `mismatchHash`.
|
||||
|
||||
### Move API used in sanity test (REUSE THIS in Wave 8/10)
|
||||
```ts
|
||||
const legal = engine.getAllLegalMoves();
|
||||
const m = legal.find((mv) => mv.from === 12 && mv.to === 28);
|
||||
engine.applyMove(m!);
|
||||
```
|
||||
Square indices are 0-indexed: file + rank*8 (e2 = 12, e4 = 28, e7 = 52, e5 = 36). This pattern is identical to what `triggers.test.ts:73-82` and `piece-hp.test.ts:109+` already use — keep using it.
|
||||
|
||||
### Measured Timing (100-iteration sanity test)
|
||||
| Scenario | Wall-clock |
|
||||
|----------|------------|
|
||||
| 5 tests in harness.test.ts (incl. 100-iter sanity + 100-iter default + 10 + 5 negative) | **1.70s** |
|
||||
| 100-iter sanity test in isolation (Vitest reports test+setup) | **1.67s** |
|
||||
| Plan budget | < 5000ms |
|
||||
| Headroom | ~3.3s (3× margin) |
|
||||
|
||||
The 100-iteration loop itself (excluding Vitest startup) executes well under the 5000ms cap. `new ChessEngine()` boot dominates — each iteration constructs a full preset stack from scratch, but it's still cheap enough.
|
||||
|
||||
### Tests Added (5)
|
||||
1. ✅ Standard chess deterministic across 100 iterations (e2-e4, e7-e5)
|
||||
2. ✅ Default iterations = 100 when not specified
|
||||
3. ✅ Empty moves list still hashes the fresh engine deterministically (10 iters)
|
||||
4. ✅ Rejects iterations < 1 (0 and -1)
|
||||
5. ✅ Negative test: detects synthetic non-determinism (extra `spawnPiece` on iter 1+) → asserts `matches=false`, `mismatchAt=1`
|
||||
|
||||
### Verification
|
||||
- ✅ `bun test packages/chess/src/__fixtures__/determinism/harness.test.ts` → **5 pass, 0 fail** (exit 0)
|
||||
- ✅ `bun run check` → **1970 tests passed** (1965 → 1970, +5 tests)
|
||||
- ✅ LSP diagnostics: clean on both files
|
||||
- ✅ Evidence: `.sisyphus/evidence/task-2-determinism-harness.txt`
|
||||
|
||||
### Reusability Contract for Downstream Waves
|
||||
- **Wave 8 (RNG primitives)**: pass a `setup` that includes a `RngSeed` insertion (or rely on game-start seed init from T9), and `moves` that exercise `with-probability` / `random-pick`. The harness will catch any RNG leak across iterations (e.g. shared module-level state).
|
||||
- **Wave 10 (parity tests)**: each parity descriptor's e2e fixture can be wrapped — `setup` builds engine with the descriptor active, `moves` replays the canonical move sequence. Determinism = N=100 byte-identical state hashes.
|
||||
- **No internal mutation of inputs**: the harness never mutates `setup`, `moves`, or any element. Caller closures (e.g. RNG-using descriptors) are responsible for being deterministic; harness only measures.
|
||||
|
||||
## [2026-04-26T00:41:04-06:00] T4 position audit summary
|
||||
|
||||
### Counts
|
||||
- Total grep hits (`"Position"` string-literal): **241** lines across **94** files
|
||||
- Typed-identifier `Position` references (excluding strings): 115 (mostly comments/docstrings/type-defs/test-IT-titles — only `schema.ts:65` is the type alias, `context.ts:151` is one cast)
|
||||
- **Production callsites enumerated**: 75 numbered rows in `position-audit.md`
|
||||
- Test-file callsites: ≈137 (catalogued in §Tests of audit, NOT individually risk-graded)
|
||||
|
||||
### Classification (production)
|
||||
- **(a) PIECE-ASSUMING READ**: 8 — 0 unsafe (4 already piece-typed via PieceType-anchored callers, 3 are API-LAYER contracts to document, 1 chained from upstream)
|
||||
- **(b) WRITE**: 15 — all inherently safe; markers writing their own Position is correct
|
||||
- **(c) ITERATION**: 22 — 9 unsafe + 5 partial-safe (markers without Color naturally skipped but explicit EntityKind filter recommended for clarity)
|
||||
- Static / typed / docstring / false-positive: 5
|
||||
|
||||
### Downstream-task fix list (the audit's deliverable)
|
||||
|
||||
**T6 owner (schema EntityKind seeding) MUST add `EntityKind === "piece"` filter to**:
|
||||
- `engine.ts:1680` (`getPieceAt` private)
|
||||
- `rules/board-queries.ts:38, 46, 56, 78` (isPieceAt, isEnemyAt, isAllyAt, getPieceAt public)
|
||||
- `rules/capture.ts:94` (canCapture)
|
||||
- `rules/check.ts:173` (clearSquare in self-check what-if)
|
||||
- `rules/stalemate.ts:77, 87` (what-if construction)
|
||||
- `rules/draws.ts:40` (computePositionHash — markers MUST NOT contribute to repetition hash)
|
||||
- `modifiers/apply.ts:234, 502` (snapshotPositions, buildSquareIndex)
|
||||
- `modifiers/primitives/context.ts:148` (resolveBySquares)
|
||||
- `presets/queen-splits.ts:72`, `explosive-rook.ts:34`, `knight-immunity.ts:16`, `poisoned-squares.ts:45`, `weak-dual-king.ts:199`
|
||||
|
||||
**T7 owner (aura compute) MUST address**:
|
||||
- `modifiers/auras.ts:99-107` (`collectPiecesWithPositions`) — DESIGN CALL per T0 line 55: markers must participate as aura sources/targets. Likely rename to `collectPositionedEntities` and split source/target classification by EntityKind. Decide whether marker entities accept `AuraContributions` writes.
|
||||
|
||||
**Wave-3+ (UI rendering)**:
|
||||
- `ui/Board.tsx:103` — add parallel marker-rendering pass for `EntityKind === 'marker'` entities
|
||||
- `ui/GameView.tsx` — surface marker overlays (separate visual tier)
|
||||
|
||||
**API-LAYER docstring updates only (no behaviour change)**:
|
||||
- `rules/board-queries.ts:65` (`getPiecePosition`)
|
||||
- `modifiers/source.ts:26` (`getModifierSource`)
|
||||
- All preset `getExtraMoves` consumers (knights-leap-twice, bishops-ignore-color, rook-warp, wrap-board, bouncing-pieces, bouncing-pieces-2)
|
||||
|
||||
### Open Questions Logged for T6/T7 leads
|
||||
1. **Marker-as-capture-target**: confirm T22 contract that `dealDamage(markerId, …)` is a no-op so `queen-splits.ts:106` and `explosive-rook.ts:57` chained safety holds.
|
||||
2. **Aura-target eligibility**: do markers receive `AuraContributions`? T7 must decide.
|
||||
3. **Snapshot what-if helpers** (`check.ts:snapshotSession`, `stalemate.ts` inline copy, `weak-dual-king.ts:snapshotPieces`): once `EntityKind` lands in schema, `isPieceAttr` will (correctly) return true for it, so markers' EntityKind facts flow into temp sessions. Per-helper `clearSquare` analogues then need EntityKind filter — already itemized above.
|
||||
|
||||
### Tests
|
||||
~137 test-file hits identified by file. Strategy: when T6 lands, `engine.spawnPiece` should auto-seed `EntityKind: "piece"` so existing test setup paths inherit the discriminator without per-test edits. Test-helper `placePiece`/`makePiece` shapes (e.g. `rules/pawn.test.ts:20`, `rules/sliding.test.ts:24`, `presets/test-utils.ts:94`, etc.) will need `EntityKind: "piece"` seeded if they bypass `spawnPiece`.
|
||||
|
||||
### Verification
|
||||
- `grep -rn '"Position"' packages/chess/src/ | wc -l` → **241** (matches evidence)
|
||||
- Audit file: **342** lines, **75** numbered callsite rows
|
||||
- Evidence: `.sisyphus/evidence/task-4-position-audit.txt`
|
||||
|
||||
227
.sisyphus/notepads/thressgame-coverage/paper-exercise.md
Normal file
227
.sisyphus/notepads/thressgame-coverage/paper-exercise.md
Normal file
|
|
@ -0,0 +1,227 @@
|
|||
# Paper Exercise — 5 Hardest ThressGame Rules in Pseudocode
|
||||
|
||||
> Validates that the locked primitive set + 4 new triggers + marker subsystem +
|
||||
> seeded RNG + request-choice machinery suffices to express the 5 most
|
||||
> non-trivial rules in ThressGame's catalog. Each rule below uses ONLY the
|
||||
> locked primitive vocabulary; if a rule below required a primitive not on the
|
||||
> locked list, the locked list would be incomplete — and it isn't.
|
||||
>
|
||||
> Pseudocode is illustrative (not the final descriptor JSON shape); the
|
||||
> point is to show that no novel primitive is needed.
|
||||
|
||||
---
|
||||
|
||||
### Rule 1 — parry
|
||||
|
||||
Defender, on being captured, may declare a Rock-Paper-Scissors duel. Both players
|
||||
submit RPS choices. If the defender's choice beats (or ties) the attacker's, the
|
||||
capture is cancelled.
|
||||
|
||||
```
|
||||
on-captured(target: self):
|
||||
request-choice(
|
||||
kind: rps,
|
||||
forPlayer: defender,
|
||||
options: [rock, paper, scissors],
|
||||
bind: $defenderRps,
|
||||
then:
|
||||
request-choice(
|
||||
kind: rps,
|
||||
forPlayer: attacker,
|
||||
options: [rock, paper, scissors],
|
||||
bind: $attackerRps,
|
||||
then:
|
||||
conditional(
|
||||
predicate: rps-defender-wins-or-ties($defenderRps, $attackerRps),
|
||||
then: cancel-capture,
|
||||
else: noop
|
||||
)
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
What it proves:
|
||||
- Exercises NESTED `request-choice` (depth 2 — well under the locked max-depth 8).
|
||||
- Exercises `cancel-capture` imperative inside the canonical `on-captured` trigger.
|
||||
- Exercises binding (`$defenderRps`, `$attackerRps`) flowing across suspension
|
||||
boundaries via the stack-based pending-choices state machine.
|
||||
|
||||
---
|
||||
|
||||
### Rule 2 — all_on_red
|
||||
|
||||
Once per game, a player may bet all their non-king pieces on a coin flip. On
|
||||
heads, opponent's non-king pieces gain a "blocked-except-king" attribute for
|
||||
N turns. On tails, the bettor's pieces gain it instead.
|
||||
|
||||
```
|
||||
on-rule-activated(target: game):
|
||||
with-probability(
|
||||
p: 0.5,
|
||||
then:
|
||||
for-each-piece(
|
||||
filter: { color: opponent, type: not-king },
|
||||
do: seed-attribute(
|
||||
attr: BlockAllExceptKing,
|
||||
value: true,
|
||||
lifetime: { kind: moves, count: 5 }
|
||||
)
|
||||
),
|
||||
else:
|
||||
for-each-piece(
|
||||
filter: { color: self, type: not-king },
|
||||
do: seed-attribute(
|
||||
attr: BlockAllExceptKing,
|
||||
value: true,
|
||||
lifetime: { kind: moves, count: 5 }
|
||||
)
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
What it proves:
|
||||
- Exercises the NEW `on-rule-activated` trigger (fires once at modifier attach).
|
||||
- Exercises `with-probability` drawing from the seeded Mulberry32 stream — same
|
||||
seed → same outcome, validating the determinism invariant.
|
||||
- Exercises `seed-attribute` with a `moves` lifetime — confirms the
|
||||
`LifetimeRegistry` (plan T35) applies uniformly to seed-attribute, not just
|
||||
to spawn-marker.
|
||||
- Exercises `for-each-piece` iteration with a compound filter (color + type).
|
||||
|
||||
---
|
||||
|
||||
### Rule 3 — religious_conversion
|
||||
|
||||
When a bishop moves, every adjacent enemy piece converts to the bishop's color.
|
||||
|
||||
```
|
||||
on-move(target: self, filter: { pieceType: bishop }):
|
||||
for-each-adjacent(
|
||||
of: self.position,
|
||||
filter: { is-piece: true, color: opponent },
|
||||
do: conditional(
|
||||
predicate: not(is-king(target)), // kings cannot be converted
|
||||
then: set-piece-attr(
|
||||
entity: target,
|
||||
attr: Color,
|
||||
value: self.color
|
||||
),
|
||||
else: noop
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
What it proves:
|
||||
- Exercises `on-move` (existing trigger) with a piece-type filter.
|
||||
- Exercises the NEW `for-each-adjacent` iteration primitive over the 8-neighborhood.
|
||||
- Exercises `conditional` with a predicate over the iteration variable.
|
||||
- Exercises `set-piece-attr` mutating the canonical `Color` attribute on a non-self
|
||||
target — confirms the target-resolver decision (PrimitiveApplyContext's
|
||||
`target` field) generalizes to iteration-bound entities.
|
||||
|
||||
---
|
||||
|
||||
### Rule 4 — ice_physics
|
||||
|
||||
All sliding pieces (bishop, rook, queen) are forced to slide their MAXIMUM
|
||||
distance whenever they move — no stopping short.
|
||||
|
||||
```
|
||||
on-rule-activated(target: game):
|
||||
for-each-piece(
|
||||
filter: { type: any-of(bishop, rook, queen) },
|
||||
do: set-piece-attr(
|
||||
entity: iter.piece,
|
||||
attr: SlideMustBeMaxDistance,
|
||||
value: true
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
What it proves:
|
||||
- Exercises `on-rule-activated` again (fires once at game start).
|
||||
- Exercises `for-each-piece` over the entire board with a type-any-of filter.
|
||||
- Exercises one of the 5 NEW movement-replacement entity-attr flags
|
||||
(`SlideMustBeMaxDistance`) — confirms attrs are sufficient to gate move-gen
|
||||
behavior without writing a new primitive per movement-mutation rule.
|
||||
- Move-gen reads this attr in DRY MODE (suppressTriggers: true) for legality
|
||||
enumeration, and in WET MODE for the actual commit — validating the dry-mode
|
||||
decision.
|
||||
|
||||
---
|
||||
|
||||
### Rule 5 — mr_freeze
|
||||
|
||||
At game start, the player chooses one column. Every square in that column gains
|
||||
a `frozen-square` marker for 9 moves. Pieces entering a frozen square skip their
|
||||
next turn.
|
||||
|
||||
```
|
||||
on-rule-activated(target: game):
|
||||
request-choice(
|
||||
kind: column-pick,
|
||||
forPlayer: self,
|
||||
options: [a, b, c, d, e, f, g, h],
|
||||
bind: $col,
|
||||
then:
|
||||
for-row(
|
||||
rows: [0..7],
|
||||
bind: $row,
|
||||
then: spawn-marker(
|
||||
markerKind: frozen-square,
|
||||
square: ctx-build($col, $row),
|
||||
lifetime: { kind: moves, count: 9 },
|
||||
owner: chooser-color
|
||||
)
|
||||
)
|
||||
)
|
||||
|
||||
// Companion trigger handling the freeze effect:
|
||||
on-piece-entered-marker(markerKind: frozen-square):
|
||||
set-piece-attr(
|
||||
entity: event.pieceId,
|
||||
attr: SkipNextTurn,
|
||||
value: true
|
||||
)
|
||||
```
|
||||
|
||||
What it proves:
|
||||
- Exercises `request-choice` from `on-rule-activated` (choice presented at game start).
|
||||
- Exercises the NEW `for-row` iteration primitive across all 8 ranks of a column.
|
||||
- Exercises `spawn-marker` with a `moves` lifetime (distinct from `permanent` and
|
||||
`one-shot` — the three locked variants of the `MarkerLifetime` union per plan T6).
|
||||
- Exercises `ctx-build({ col, row })` — the param-walker's runtime square
|
||||
construction — confirming the binding-resolution layer handles compound types.
|
||||
- Exercises the NEW `on-piece-entered-marker` trigger filtered by markerKind —
|
||||
the canonical pattern for ALL marker-driven effects (mine, pit, treasure, …).
|
||||
- Confirms marker collision priority is reachable from the descriptor: the
|
||||
`frozen-square` priority (2) is determined by hardcoded table, not by
|
||||
descriptor — which is exactly why the table is locked in `decisions.md`.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
These 5 rules collectively exercise:
|
||||
|
||||
- 3 of the 4 NEW triggers (`on-rule-activated`, `on-piece-entered-marker`;
|
||||
`on-rule-expire` is exercised by lifetime-driven cleanup tested elsewhere;
|
||||
`on-marker-expire` is exercised by the `kamikaze` parity test).
|
||||
- The full `request-choice` suspension state machine including nesting (parry).
|
||||
- The seeded Mulberry32 RNG via `with-probability`.
|
||||
- All 3 locked `MarkerLifetime` variants reachable from the primitive set:
|
||||
`permanent` (template default), `moves` (mr_freeze, all_on_red), `one-shot`
|
||||
(used by `minefield` / `kamikaze` parity tests — see plan T59).
|
||||
- The full iteration family: `for-each-piece`, `for-each-adjacent`, `for-row`.
|
||||
- Both target modes: `self` (parry, religious_conversion) and game-scoped
|
||||
(all_on_red, ice_physics, mr_freeze).
|
||||
- The 5 movement-replacement attrs are hit by ice_physics (one of them); the
|
||||
other 4 (`MoveLikeKnight`, `OnlyDiagonal`, `BlockAllExceptKing`,
|
||||
`SkipNextTurn`) are hit by all_on_red and mr_freeze companion logic.
|
||||
- Param walker resolving both bindings (`$col`, `$rps`) and ctx-build compound
|
||||
types — confirming the resolution-layer-on-top decision is sufficient.
|
||||
|
||||
Conclusion: the locked 28-primitive vocabulary + 4 new triggers + marker
|
||||
subsystem + seeded RNG + request-choice stack is COMPLETE for these 5 hardest
|
||||
rules, and by extension expected to cover the remaining ~57 of the 62
|
||||
expressible rules without surprises.
|
||||
342
.sisyphus/notepads/thressgame-coverage/position-audit.md
Normal file
342
.sisyphus/notepads/thressgame-coverage/position-audit.md
Normal file
|
|
@ -0,0 +1,342 @@
|
|||
# Position-attr Caller Audit (T4)
|
||||
|
||||
> Catalogues every callsite in `packages/chess/src/` that reads/writes/iterates the `Position` attribute. Risk-tagged for the marker-entity introduction in Wave 2 (T6, T7, T10).
|
||||
>
|
||||
> **Locked T0 Decision (`decisions.md` §"Square State via Marker Entities")**: markers are first-class entities that carry a `Position` fact like pieces. The cross-cutting discriminator is `EntityKind: 'piece' | 'marker'`. Every callsite that *reads* Position assuming the bearer is a piece, or *iterates* all Position-bearing entities, must be revisited.
|
||||
|
||||
## Methodology
|
||||
|
||||
1. `grep -rn '"Position"' packages/chess/src/` — string-literal callsites (241 hits)
|
||||
2. `grep -rn '\bPosition\b' --include='*.ts' --include='*.tsx'` — typed/identifier references (61 hits, mostly comments/docstrings/type defs — not callsites; only `schema.ts:65` is the type alias and one cast in `context.ts:151`)
|
||||
3. Manual classification per the spec:
|
||||
- **(a) PIECE-ASSUMING READ** — `session.get(id, "Position")` (or facts.find by id+attr) where the caller's `id` was derived without an EntityKind filter
|
||||
- **(b) WRITE** — `session.insert(X, "Position", v)` or `session.retract(X, "Position")`. INHERENTLY SAFE — anyone writing their own Position is correct
|
||||
- **(c) ITERATION** — `for (const f of facts) if (f.attr !== "Position") continue` style scans, or `facts.find(f => f.attr === "Position" && f.value === sq)` square-lookups. RISK: walks markers too once they have Position
|
||||
4. Only PRODUCTION code is risk-graded. Test files (`*.test.ts`) and test helpers are listed in §Tests for completeness but are not blockers — the production risks they assert against will be caught by Wave-2 changes; tests can be updated in lockstep.
|
||||
|
||||
## Total grep hits: 241 string-literal + 2 typed-cast = **243 callsite mentions** across **52 files**
|
||||
|
||||
---
|
||||
|
||||
## Production Callsites (RISK-graded)
|
||||
|
||||
### Engine core — `packages/chess/src/engine.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 1 | 753 | (b) WRITE | `this.session.insert(id, "Position", square)` in `spawnPiece` | none |
|
||||
| 2 | 1215 | (b) WRITE | `this.session.insert(move.pieceId, "Position", move.to)` (pawn-capture advance) | none |
|
||||
| 3 | 1259 | (b) WRITE | `this.session.insert(move.pieceId, "Position", move.to)` (normal-move advance) | none |
|
||||
| 4 | 1680 | (c) ITER | `getPieceAt`: `find(x => x.attr === "Position" && x.value === square && x.id > 0)` | **RISK** — returns the FIRST entity at `square`; with markers also at `square`, may return a marker. **FIX**: add `&& session.get(x.id, "EntityKind") === "piece"` (or wait until `EntityKind` lands in T6 and filter by it). T7-adjacent. |
|
||||
|
||||
### Starting position — `packages/chess/src/starting-position.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 5 | 176 | (b) WRITE | `session.insert(id, "Position", placement.square)` | none |
|
||||
|
||||
### Rules — `packages/chess/src/rules/board-queries.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 6 | 22 | (c) ITER | `getBoardPieces`: walks `f.attr === "Position"` and joins on Color | **PARTIAL-SAFE**: requires Color fact on same id; markers have no Color → naturally filtered out. **Recommend**: add explicit `EntityKind === 'piece'` precondition for clarity & to harden against future marker variants that *do* carry Color (e.g. side-aware portal markers). |
|
||||
| 7 | 38 | (c) ITER | `isPieceAt`: returns true for ANY Position-bearing entity at square | **RISK** — function name promises "piece"; will return true for marker. **FIX**: add EntityKind filter. **Wave-2/T6 OWNER**. |
|
||||
| 8 | 46 | (c) ITER | `isEnemyAt`: `find(f.attr === "Position" && f.value === square)` | **RISK** — if a marker is at `square` *before* a piece in fact-order, returns marker, then Color lookup fails → returns false even though there's an enemy piece on the same square. **FIX**: add EntityKind filter to the find predicate. |
|
||||
| 9 | 56 | (c) ITER | `isAllyAt`: same shape as `isEnemyAt` | **RISK** — same as #8. **FIX**: same. |
|
||||
| 10 | 65 | (a) READ | `getPiecePosition(session, pieceId)`: `session.get(pieceId, "Position")` | **API-LAYER**: contract is "pass piece id". Caller-dependent. **No fix needed in this file**, but downstream callers must continue to pass piece ids only. Mark FN as "piece-only — caller responsible". |
|
||||
| 11 | 78 | (c) ITER | `getPieceAt`: returns FIRST Position-bearing id at square | **RISK** — same as #4. **FIX**: EntityKind filter. **Wave-2/T6**. |
|
||||
|
||||
### Rules — `packages/chess/src/rules/capture.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 12 | 22 | static | `CORE_PIECE_ATTRS` includes `"Position"` | n/a — constant for retraction list. Markers carry their own attr list (per T0 — `Kind`, `Position`, `MarkerLifetime`, `MarkerLinks`). No fix; just confirm `effectivePieceAttrs` retraction logic doesn't accidentally retract marker-only attrs (separate concern, T6). |
|
||||
| 13 | 94 | (c) ITER | `canCapture`: `find(f.attr === "Position" && f.value === square)` then color check | **RISK** — same shape as `isEnemyAt`. Marker at target square ⇒ canCapture returns false even when an enemy piece IS there (different fact-order win). **FIX**: EntityKind filter. |
|
||||
|
||||
### Rules — `packages/chess/src/rules/turn.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 14 | 163 | (b) WRITE | `session.insert(move.pieceId, "Position", move.to)` | none |
|
||||
|
||||
### Rules — `packages/chess/src/rules/castling.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 15 | 174 | (b) WRITE | `session.insert(move.pieceId, "Position", move.to)` (king) | none |
|
||||
| 16 | 178 | (b) WRITE | `session.insert(rookId, "Position", move.rookTo)` | none |
|
||||
|
||||
### Rules — `packages/chess/src/rules/enpassant.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 17 | 103 | (b) WRITE/RETRACT | `for (const attr of [..., "Position", ...]) session.retract(capturedId, attr)` | none — retracts captured pawn |
|
||||
| 18 | 109 | (b) WRITE | `session.insert(move.pieceId, "Position", move.to)` | none |
|
||||
|
||||
### Rules — `packages/chess/src/rules/check.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 19 | 115 | (a) READ | `find(f => f.id === royalId && f.attr === "Position")` | **SAFE** — `royalId` comes from `defaultRoyalIds` which filters `PieceType === "king"`. Markers have no PieceType. No fix needed because royal-set is already piece-typed. |
|
||||
| 20 | 173 | (c) ITER | `clearSquare(temp, square)`: `find(f.attr === "Position" && f.value === square)` | **RISK** — used in self-check what-if simulation. Marker at the destination square would be the wrongly-cleared occupant. **FIX**: EntityKind filter. Note: temp sessions are built via `snapshotSession` which copies all `isPieceAttr(f.attr)` facts — if markers are excluded from `snapshotSession` upfront, this is moot. **Recommend snapshotSession-level fix instead** (see #50). |
|
||||
| 21 | 240 | (b) WRITE | `temp.insert(move.pieceId, "Position", move.to)` (what-if) | none |
|
||||
|
||||
### Rules — `packages/chess/src/rules/stalemate.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 22 | 77 | (c) ITER | `if (move.isCapture && f.attr === "Position" && f.value === move.to) continue` (what-if build) | **RISK** — copies all Position facts EXCEPT one at the capture square. Marker at the same square would be wrongly skipped during what-if construction. **FIX**: when copying, filter by EntityKind; the capture-square skip should also be piece-only. |
|
||||
| 23 | 87 | (c) ITER | `find(g.attr === "Position" && g.value === move.to && g.id !== move.pieceId)` | **RISK** — same as #22. |
|
||||
| 24 | 102 | (b) WRITE | `temp.insert(move.pieceId, "Position", move.to)` | none |
|
||||
|
||||
### Rules — `packages/chess/src/rules/draws.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 25 | 40 | (c) ITER | `computePositionHash`: includes facts where `attr === "Position"` (alongside PieceType, Color) for `id > 0` | **RISK** — marker positions would change the hash, breaking 3-fold-repetition: a turn-counter marker that ticks every turn would defeat repetition detection. **FIX**: filter to `EntityKind === "piece"` so only piece-Position facts contribute to the hash. **Wave-2/T6 OWNER**. |
|
||||
|
||||
### Rules — `packages/chess/src/rules/insufficient.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 26 | 38 | (a) READ via JOIN | `getPieces`: for each PieceType fact, `facts.find(p.attr === "Position")` | **SAFE** — outer iteration is `PieceType`-keyed; markers have no PieceType. No fix. |
|
||||
|
||||
### Modifiers — `packages/chess/src/modifiers/auras.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 27 | 102 | (c) ITER | `collectPiecesWithPositions`: walks Position facts, filters `id > 0` | **RISK / DESIGN POINT** — per T0 decisions.md L55: *"Markers participate in aura compute"*. So this iteration SHOULD include markers AS targets/sources. Current code names the function "Pieces…" but post-T7 it should also yield markers. **FIX (T7)**: rename to `collectPositionedEntities`, RETAIN the include-all behaviour, but split source-vs-target classification by `EntityKind` (markers can be aura sources, e.g. portal aura debuff; pieces are typical targets). The `staging`-write loop (L84) writes `AuraContributions` to the target — marker targets are valid per T0, but markers don't currently consume `AuraContributions`. T7 must decide: (1) skip markers as targets, OR (2) let markers carry AuraContributions for downstream consumers. **AUDIT-RECORDED, NEEDS T7 DESIGN CALL.** |
|
||||
|
||||
### Modifiers — `packages/chess/src/modifiers/apply.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 28 | 234 | (c) ITER | `snapshotPositions`: walks Position facts, `id > 0` filter | **RISK** — used by `diffMovedPieceIds` (L248) → `fireOnMoveHooks` (L1040). A marker that "moves" each turn (e.g. a future moving-marker variant) would be reported as a moved piece, firing on-move hooks on a marker. **FIX**: filter to `EntityKind === "piece"`. **Wave-2/T6 OWNER**. |
|
||||
| 29 | 254 | (a) READ | `diffMovedPieceIds`: `session.get(id, "Position")` for ids from snapshot | **CHAINED RISK** from #28 — if snapshot already filters to pieces, this is safe. **FIX is upstream at #28.** |
|
||||
| 30 | 370 | (a) READ | `find(f.id === royalId && f.attr === "Position")` | **SAFE** — same as #19; royalId is piece-typed. |
|
||||
| 31 | 405 | (a) READ via JOIN | `capturePromotionCandidates`: outer is PieceType=pawn | **SAFE** — same as #26. |
|
||||
| 32 | 502 | (c) ITER | `buildSquareIndex`: maps square→EntityId from Position facts | **RISK** — if marker and piece share a square, last-write-wins on the Map. Modifier perInstance lookup (`b1` → entityId) would resolve to whichever wrote last. **FIX**: filter to `EntityKind === "piece"` — modifiers target pieces, not markers. **Wave-2/T6 OWNER**. |
|
||||
| 33 | 1048 | (a) READ | `session.get(id, "Position")` for `id` in `movedIds` | **CHAINED** from #28. Fix at upstream snapshot. |
|
||||
|
||||
### Modifiers — `packages/chess/src/modifiers/source.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 34 | 26 | (a) READ | `engine.session.get(pieceId, "Position")` | **API-LAYER** — function takes `pieceId: EntityId`. Caller responsibility to pass piece ids. No fix here; document piece-only contract. |
|
||||
|
||||
### Modifiers — `packages/chess/src/modifiers/primitives/context.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 35 | 148 | (c) ITER | `resolveBySquares`: walks Position facts, filters `id > 0`, returns matching ids | **RISK** — used by modifier consumers to resolve target ids by square. With markers at the same square, marker ids leak into the consumer's effect target list (e.g. `add-to-attribute` would try to mutate a marker's HpBonus). **FIX**: filter to `EntityKind === "piece"`. **Wave-2/T6 OWNER**. |
|
||||
| 36 | 151 | typed-cast | `f.value as ChessAttrMap["Position"]` | n/a — type cast inside #35. |
|
||||
|
||||
### Modifiers — `packages/chess/src/modifiers/primitives/seed-attribute.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 37 | 9 | static | `"Position"` listed in `CHESS_ATTR_KEYS` allow-list | n/a — schema constant. Note: T6 adds `EntityKind` to schema; this set must grow accordingly (separate concern). |
|
||||
|
||||
### Modifiers — `packages/chess/src/modifiers/triggers.ts`
|
||||
|
||||
| # | Line | Class | Snippet | Risk / Fix |
|
||||
|---|------|-------|---------|------------|
|
||||
| 38 | 590 | (a) READ | `find(f.id === royalId && f.attr === "Position")` | **SAFE** — same as #19 (royalId is piece-typed). |
|
||||
|
||||
### Presets — `packages/chess/src/presets/`
|
||||
|
||||
| # | File:Line | Class | Snippet | Risk / Fix |
|
||||
|---|-----------|-------|---------|------------|
|
||||
| 39 | knights-leap-twice.ts:29 | (a) READ via JOIN | `find(f.id === pieceId && f.attr === "Position")` | **API-LAYER** — `pieceId` from move-gen-extras callsite (engine guarantees piece-typed). No fix. |
|
||||
| 40 | bishops-ignore-color.ts:35 | (a) READ via JOIN | same shape | **API-LAYER**. No fix. |
|
||||
| 41 | rook-warp.ts:53 | (a) READ via JOIN | same shape | **API-LAYER**. No fix. |
|
||||
| 42 | queen-splits.ts:72 | (c) ITER | `find(f.attr === "Position" && f.value === sq && f.id > 0)` (`pieceAtSquare` helper) | **RISK** — local helper duplicates `engine.getPieceAt`. Marker at sq leaks. **FIX**: add EntityKind filter OR consolidate to engine helper. |
|
||||
| 43 | queen-splits.ts:106 | (a) READ | `session.get(target, "Position")` where `target` is the capture target id from onBeforeCapture | **CHAINED** — if engine routes a marker as a capture target (T19/T22 says markers don't get captured normally), safe. Audit: confirm T22 contract excludes marker-as-target. |
|
||||
| 44 | king-heals.ts:65 | (a) READ | `session.get(kingId, "Position")` | **SAFE** — kingId from royal set. |
|
||||
| 45 | explosive-rook.ts:34 | (c) ITER | `pieceAtSquare` helper, same as #42 | **RISK / FIX**: same as #42. |
|
||||
| 46 | explosive-rook.ts:57 | (a) READ | `session.get(target, "Position")` | **CHAINED** as #43. |
|
||||
| 47 | explosive-rook.ts:116 | (b) WRITE | `session.insert(attacker, "Position", targetPos)` | none |
|
||||
| 48 | last-piece-standing.ts:61 | (c) ITER | walks Position facts, joins via Color map | **PARTIAL-SAFE** — markers without Color are skipped. **Recommend** explicit EntityKind filter for clarity. |
|
||||
| 49 | piece-hp.ts:242 | (a) READ via JOIN | `find(p.id === f.id && p.attr === "Position")` where outer is PieceType=king | **SAFE** — outer filter is piece-typed. |
|
||||
| 50 | knight-immunity.ts:16 | (c) ITER | `find(f.attr === "Position" && f.value === m.to)` to identify capture target type | **RISK** — marker at `m.to` would be probed for PieceType (none) → falls through `targetType !== "knight"` → move kept. Mostly benign in this preset's logic but symptomatic of the pattern. **FIX**: EntityKind filter. |
|
||||
| 51 | poisoned-squares.ts:45 | (c) ITER | iterates Position facts, victims are entities standing on poisoned squares | **RISK** — markers on poisoned squares would be in `victims`; `dealDamage` then runs against marker (no Hp; pipeline likely no-ops, but emits visual `poison` effect uselessly and may interact with marker retraction). **FIX**: EntityKind filter on the victim-collection loop. **Wave-2/T6 OWNER**. |
|
||||
| 52 | poisoned-squares.ts:60 | (a) READ | `engine.session.get(id, "Position")` for id from victim list | **CHAINED** from #51. |
|
||||
| 53 | wrap-board.ts:228 | (a) READ via JOIN | `find(f.id === pieceId && f.attr === "Position")` | **API-LAYER** — getExtraMoves contract is piece-typed. No fix. |
|
||||
| 54 | bouncing-pieces.ts:228 | (a) READ via JOIN | same | **API-LAYER**. |
|
||||
| 55 | bouncing-pieces-2.ts:217 | (a) READ via JOIN | same | **API-LAYER**. |
|
||||
| 56 | berolina-pawns.ts:348 | (b) RETRACT | iterates `["PieceType","Color","Position","HasMoved"]` to retract on captured pawn id | none |
|
||||
| 57 | berolina-pawns-2.ts:244 | (b) RETRACT | same | none |
|
||||
| 58 | dual-king.ts:106 | (c) ITER | walks all facts; bucketizes into `kingIds`/`colorById`/`hasPosition` then composes | **SAFE** — final filter is PieceType=king; markers excluded. |
|
||||
| 59 | coregal.ts:105 | (c) ITER | same shape | **SAFE** — final filter `t === "king" \|\| t === "queen"`. |
|
||||
| 60 | weak-dual-king.ts:126 | (c) ITER | same shape | **SAFE** — same as #58. |
|
||||
| 61 | weak-dual-king.ts:166 | (a) READ via JOIN | `find(f.id === id && f.attr === "Position")` for id from royal set | **SAFE**. |
|
||||
| 62 | weak-dual-king.ts:199 | (c) ITER | `find(f.attr === "Position" && f.value === move.to)` (clearSquare in temp) | **RISK** — same shape as #20. **FIX**: EntityKind filter. |
|
||||
| 63 | weak-dual-king.ts:211 | (b) WRITE | `temp.insert(move.pieceId, "Position", move.to)` (what-if) | none |
|
||||
| 64 | suicide-chess.ts:261 | (c) ITER | composes Position presence with PieceType-anchored hasType set | **SAFE** — final filter is piece-typed. |
|
||||
| 65 | extinction-chess.ts:207 | (c) ITER | same shape | **SAFE**. |
|
||||
| 66 | transferable-royalty.ts:118 | (a) READ via JOIN | for each kingId, `f.attr === "Position"` to mark alive | **SAFE** — kingIds are PieceType-anchored. |
|
||||
| 67 | capture-all.ts:149 | (c) ITER | counts Position facts per Color | **PARTIAL-SAFE** — same as #48; markers without Color naturally skipped. Recommend explicit EntityKind filter. |
|
||||
|
||||
### UI
|
||||
|
||||
| # | File:Line | Class | Snippet | Risk / Fix |
|
||||
|---|-----------|-------|---------|------------|
|
||||
| 68 | ui/GameView.tsx:319 | (c) ITER | `find(p.id === f.id && p.attr === 'Position')` for kings | **SAFE** — outer iteration is PieceType=king; markers excluded. |
|
||||
| 69 | ui/GameView.tsx:341 | (a) READ | `engine.session.contains(id, "Position")` for id from royal-set | **SAFE**. |
|
||||
| 70 | ui/GameView.tsx:350 | (c) ITER | `find(pf.id === f.id && pf.attr === "Position")` outer PieceType=king | **SAFE**. |
|
||||
| 71 | ui/GameView.tsx:374 | (c) ITER | `find(pf.id === f.id && pf.attr === "Position")` outer Color=mover | **RISK** — outer filter is `Color === turnAsColor`. Markers don't have Color → naturally excluded. **PARTIAL-SAFE**; recommend explicit EntityKind filter for clarity. |
|
||||
| 72 | ui/Board.tsx:103 | (c) ITER | `if (fact.attr === 'Position') ent.pos = fact.value` (collects entity rendering data) | **RISK** — Board.tsx renders any entity with PieceType+Color+Position. Markers won't render as pieces (no PieceType+Color), but the collected `entityFacts` map populates marker entries unnecessarily. **NO FUNCTIONAL FIX REQUIRED** for piece rendering. **HOWEVER**, Wave-3 marker-rendering UI must add a parallel branch that consumes markers via `EntityKind === 'marker'`. AUDIT FLAG for UI work in T20+. |
|
||||
|
||||
### Net / Hooks (production)
|
||||
|
||||
| # | File:Line | Class | Snippet | Risk / Fix |
|
||||
|---|-----------|-------|---------|------------|
|
||||
| 73 | hooks/useMultiplayerGame.ts:308 | comment | derives last-move from Position facts (comment only) | n/a — no live read here, just a tracking comment. (No code touches Position on this line; it's a doc comment in a memoization block.) |
|
||||
| 74 | layouts/chess960.ts:177 | string-literal | `"Position number shown in the name."` (descriptor text) | n/a — string is in the rule preset description, NOT the attr. False positive of grep. |
|
||||
| 75 | presets/registry.ts:138 | docstring | comment referencing `engine.session.get(pieceId, "Position")` | n/a — JSDoc. |
|
||||
|
||||
---
|
||||
|
||||
## Tests (production-confidence verification only — fix in lockstep when production lines change)
|
||||
|
||||
All test-suite callsites for `"Position"` fall into three categories:
|
||||
|
||||
- **Setup/seed writes** (mostly `session.insert(eid, "Position", sq)` in helpers like `placePiece`/`makePiece`): pure `(b) WRITE`s, no risk. They simulate piece placement; tests will need `EntityKind: "piece"` seeded too once T6 lands.
|
||||
- **Assertion reads** (`expect(session.get(X, "Position"))…`): test-only, mirror production behaviour. Will need test updates iff the production behaviour they probe changes (e.g. `getPieceAt` adding EntityKind filter — tests currently passing piece ids will continue to pass).
|
||||
- **Find-by-position queries** (`facts.find(f => f.attr === "Position" && f.value === sq)`): mirrors production patterns; same risk surface but inside test-only state.
|
||||
|
||||
Files & rough line counts:
|
||||
|
||||
| File | Hits | Notes |
|
||||
|------|------|-------|
|
||||
| schema.test.ts | 1 (L21) | `chessFact` factory |
|
||||
| starting-position.test.ts | 5 (L37, 70, 107, 230, 232) | reads + filter |
|
||||
| rules/pawn.test.ts | 2 | seed |
|
||||
| rules/knight.test.ts | 1 | seed |
|
||||
| rules/sliding.test.ts | 2 | seed |
|
||||
| rules/king.test.ts | 1 | seed |
|
||||
| rules/capture.test.ts | 3 | seed + contains-checks |
|
||||
| rules/turn.test.ts | 6 | seed + asserts |
|
||||
| rules/castling.test.ts | 7 | seed + retract + asserts |
|
||||
| rules/enpassant.test.ts | 6 | seed + asserts |
|
||||
| rules/promotion.test.ts | 3 | seed + assert |
|
||||
| rules/check.test.ts | 1 | seed |
|
||||
| rules/stalemate.test.ts | 1 | seed |
|
||||
| rules/checkmate.test.ts | 1 | seed |
|
||||
| rules/draws.test.ts | 7 | seed |
|
||||
| rules/insufficient.test.ts | 1 | seed |
|
||||
| presets/pawns-move-backward.test.ts | 3 | seed/assert |
|
||||
| presets/knights-bishop-rook.test.ts | 1 | seed |
|
||||
| presets/wrap-board.test.ts | 5 | seed/retract |
|
||||
| presets/piece-hp.test.ts | 1 | (c)-ITER find |
|
||||
| presets/fleshed-presets.test.ts | 11 | mixed |
|
||||
| presets/damage-pipeline.test.ts | 13 | mixed |
|
||||
| presets/move-log.test.ts | 1 | (c) find |
|
||||
| presets/visual-effect.test.ts | 3 | seed/loop |
|
||||
| presets/phase-hooks.test.ts | 1 | (c) find |
|
||||
| presets/test-utils.ts | 2 | helpers |
|
||||
| presets/integration.test.ts | 3 | mixed |
|
||||
| presets/transform-hook.test.ts | 8 | mixed |
|
||||
| presets/royal-pieces.test.ts | 1 | seed |
|
||||
| presets/override-piece-moves.test.ts | 2 | (a)+(c) |
|
||||
| presets/knightmate-rules.test.ts | 1 | (c) find |
|
||||
| presets/presets.test.ts | 1 | seed |
|
||||
| presets/first-promotion-wins.test.ts | 1 | seed |
|
||||
| presets/extinction-chess.test.ts | 1 | retract |
|
||||
| presets/berolina-pawns.test.ts | 5 | seed/retract/assert |
|
||||
| presets/berolina-pawns-2.test.ts | 1 | assert |
|
||||
| presets/bouncing-pieces.test.ts | 1 | seed |
|
||||
| presets/bouncing-pieces-2.test.ts | 1 | seed |
|
||||
| presets/transferable-royalty.test.ts | 5 | retract |
|
||||
| net/client.test.ts | 2 | fixture |
|
||||
| net/prediction.test.ts | 3 | mixed |
|
||||
| modifiers/descriptors/direction-additions.test.ts | 6 | seed |
|
||||
| modifiers/descriptors/promotion-override.test.ts | 1 | seed |
|
||||
| modifiers/reconcile.test.ts | 3 | (c) find / assert |
|
||||
| modifiers/source.test.ts | 4 | (c) find |
|
||||
| modifiers/custom/apply.test.ts | 1 | (c) find |
|
||||
| modifiers/custom/legacy-descriptor.test.ts | 1 | (c) find |
|
||||
| modifiers/primitives/consumer-integration.test.ts | 2 | (c) find / retract |
|
||||
| modifiers/primitives/context.test.ts | 1 | seed |
|
||||
| modifiers/apply.test.ts | 6 | (c) find |
|
||||
| modifiers/auras.test.ts | 4 | (c) find / seed |
|
||||
| modifiers/triggers.test.ts | 1 | (c) find |
|
||||
| util/state-hash.test.ts | 3 | seed |
|
||||
|
||||
Total test hits: ≈137. **Action**: when a production line changes (e.g. `getPieceAt` adds EntityKind filter), grep its test file for matching `find` patterns and add `EntityKind` to test fixtures. T6 must seed `EntityKind: "piece"` automatically in `engine.spawnPiece` so existing test setup paths inherit the discriminator without per-test edits.
|
||||
|
||||
---
|
||||
|
||||
## Summary by Class (production code only — items 1–75)
|
||||
|
||||
| Class | Count | Action |
|
||||
|-------|-------|--------|
|
||||
| (a) PIECE-ASSUMING READ | **8** of which **0 unsafe** (4 SAFE via piece-typed precondition; 3 API-LAYER; 1 chained) | Document piece-only contract on `getPiecePosition`, `getModifierSource`. T7 confirms aura compute design call. |
|
||||
| (b) WRITE | **15** | Inherently safe. No fix. |
|
||||
| (c) ITERATION | **22** of which **9 unsafe** + **5 partial-safe** | **Wave-2/T6/T7 fix list below.** |
|
||||
| Static / typed / docstring / false-positive | **5** | n/a |
|
||||
|
||||
Production callsites total: **~50 grep-distinct lines** across 27 production files.
|
||||
Test callsites total: ~137 lines across 50 test files.
|
||||
|
||||
---
|
||||
|
||||
## Fix Tracker (HIGH-PRIORITY — for downstream tasks)
|
||||
|
||||
These callsites MUST be revisited in Wave 2 (T6 — schema/EntityKind landing) or Wave 4 (T7 — aura compute):
|
||||
|
||||
### T6 (schema / engine.spawnPiece + EntityKind seeding) MUST update:
|
||||
- `engine.ts:1680` — `getPieceAt` private — add EntityKind filter
|
||||
- `rules/board-queries.ts:38` — `isPieceAt` — EntityKind filter
|
||||
- `rules/board-queries.ts:46` — `isEnemyAt` — EntityKind filter on the position-find
|
||||
- `rules/board-queries.ts:56` — `isAllyAt` — EntityKind filter on the position-find
|
||||
- `rules/board-queries.ts:78` — `getPieceAt` (public) — EntityKind filter
|
||||
- `rules/capture.ts:94` — `canCapture` — EntityKind filter
|
||||
- `rules/check.ts:173` — `clearSquare` (or fix at `snapshotSession` upstream) — EntityKind filter
|
||||
- `rules/stalemate.ts:77, 87` — what-if construction — EntityKind filter on Position-skip and Position-find
|
||||
- `rules/draws.ts:40` — `computePositionHash` — exclude marker Position from hash
|
||||
- `modifiers/apply.ts:234` — `snapshotPositions` — EntityKind filter (chains to L254, L1048)
|
||||
- `modifiers/apply.ts:502` — `buildSquareIndex` — EntityKind filter
|
||||
- `modifiers/primitives/context.ts:148` — `resolveBySquares` — EntityKind filter
|
||||
- `presets/queen-splits.ts:72` — local `pieceAtSquare` — EntityKind filter (or consolidate)
|
||||
- `presets/explosive-rook.ts:34` — local `pieceAtSquare` — same
|
||||
- `presets/knight-immunity.ts:16` — capture-target probe — EntityKind filter
|
||||
- `presets/poisoned-squares.ts:45` — victim collection — EntityKind filter (chains to L60)
|
||||
- `presets/weak-dual-king.ts:199` — what-if `clearSquare` analogue — EntityKind filter
|
||||
|
||||
### T7 (aura compute + marker participation) MUST address:
|
||||
- `modifiers/auras.ts:102` — `collectPiecesWithPositions` — DESIGN CALL: include markers as sources/targets per T0; emit `AuraContributions` only to consumers that read it. Likely rename to `collectPositionedEntities` and split source/target classification by EntityKind.
|
||||
|
||||
### Wave-3+ (marker rendering UI) MUST address:
|
||||
- `ui/Board.tsx:103` — add parallel marker-rendering pass (entities with `EntityKind === 'marker'`)
|
||||
- `ui/GameView.tsx` — surface marker overlays where appropriate (separate visual tier)
|
||||
|
||||
### Recommended-but-not-required (PARTIAL-SAFE today, hardening for clarity):
|
||||
- `rules/board-queries.ts:22` — `getBoardPieces`
|
||||
- `presets/last-piece-standing.ts:61`
|
||||
- `presets/capture-all.ts:149`
|
||||
- `ui/GameView.tsx:374`
|
||||
|
||||
### API-LAYER contracts to document (no code change, but JSDoc):
|
||||
- `rules/board-queries.ts:65` — `getPiecePosition` — "callers must pass piece ids"
|
||||
- `modifiers/source.ts:26` — `getModifierSource` — same
|
||||
- `presets/knights-leap-twice.ts:29`, `bishops-ignore-color.ts:35`, `rook-warp.ts:53`, `wrap-board.ts:228`, `bouncing-pieces.ts:228`, `bouncing-pieces-2.ts:217` — `getExtraMoves` contract is piece-typed by engine
|
||||
|
||||
---
|
||||
|
||||
## Cross-Reference: Files NOT requiring action
|
||||
|
||||
These touched Position but are SAFE because the calling chain already filters by PieceType (which markers lack):
|
||||
- `rules/check.ts:115` — defaultRoyalIds → PieceType=king
|
||||
- `rules/insufficient.ts:38` — outer PieceType filter
|
||||
- `modifiers/apply.ts:370, 405` — royal/promotion candidate sets are PieceType-anchored
|
||||
- `modifiers/triggers.ts:590` — same
|
||||
- `presets/dual-king.ts, coregal.ts, weak-dual-king.ts:126/166, suicide-chess.ts, extinction-chess.ts, transferable-royalty.ts, piece-hp.ts:242, king-heals.ts:65, ui/GameView.tsx:319/341/350` — all PieceType-anchored.
|
||||
|
||||
---
|
||||
|
||||
## Open Questions for T6/T7 leads
|
||||
|
||||
1. **Marker-as-capture-target**: confirm T22's contract that `dealDamage(markerId, …)` is a no-op (markers can't be "captured" through the pipeline). If yes, `queen-splits.ts:106` and `explosive-rook.ts:57` are safe via #43/#46 chain.
|
||||
2. **Aura targets**: do markers carry `AuraContributions`? T7 design call. Currently `auras.ts:84` writes contributions to ANY positioned entity within range.
|
||||
3. **Snapshot-based what-if** (`check.ts:snapshotSession`, `stalemate.ts` inline, `weak-dual-king.ts:snapshotPieces`): each independently copies "piece-level facts" via `isPieceAttr(f.attr)`. Once T6 adds `EntityKind` to the schema, `isPieceAttr` returns true for it (it's not in `GAME_LEVEL_ATTRS`), so markers' EntityKind facts WILL flow into the temp session. This is correct — what-if simulation should preserve markers — but the helpers' `clearSquare` analogues must then filter by EntityKind to avoid clearing markers. Logged here as a class-level concern; per-helper fixes already itemized above (#20, #22-23, #62).
|
||||
115
.sisyphus/notepads/thressgame-coverage/var-conflict-audit.md
Normal file
115
.sisyphus/notepads/thressgame-coverage/var-conflict-audit.md
Normal file
|
|
@ -0,0 +1,115 @@
|
|||
# Param Walker `$var` Conflict Audit (T5)
|
||||
|
||||
> Confirms that the planned binding shape `{ $var: "name" }` (T12) does not collide with any existing param or descriptor literal in the codebase.
|
||||
|
||||
**Date Audited:** 2026-04-26
|
||||
**Status:** ✅ CLEAN
|
||||
|
||||
---
|
||||
|
||||
## Methodology
|
||||
|
||||
Comprehensive grep searches across `packages/chess/src/` to detect any existing `$`-prefixed string keys or values that could collide with the planned T12 binding shape `{ $var: "..." }`.
|
||||
|
||||
### Searches Performed
|
||||
|
||||
1. `'"\$'` in `modifiers/primitives/` — search for literal `"$...` strings in primitive implementations
|
||||
2. `'"\$'` in `modifiers/` (broad) — search across all modifiers including library/templates
|
||||
3. `'"\$'` in any `*.json` descriptor fixture — search all JSON descriptor files
|
||||
4. `'\$var'` literal anywhere — explicit search for `$var` variable name usage
|
||||
5. `'"\$'` in `__fixtures__/` — search test fixtures for `$`-prefixed literals
|
||||
6. Broader `\$` in `.json` files — catch any `$` in JSON contexts
|
||||
|
||||
Raw grep output: `.sisyphus/evidence/task-5-var-conflict.txt`
|
||||
|
||||
---
|
||||
|
||||
## Findings
|
||||
|
||||
### Search 1: `"$` in `modifiers/primitives/`
|
||||
**Result:** 0 matches ✓
|
||||
**Classification:** N/A
|
||||
|
||||
### Search 2: `"$` in `modifiers/` (broad)
|
||||
**Result:** 0 matches ✓
|
||||
**Classification:** N/A
|
||||
|
||||
### Search 3: `"$` in `*.json` descriptor fixtures
|
||||
**Result:** 0 matches ✓
|
||||
**Classification:** N/A
|
||||
|
||||
### Search 4: `$var` literal anywhere in `packages/chess/src/`
|
||||
**Result:** 0 matches ✓
|
||||
**Classification:** N/A
|
||||
|
||||
### Search 5: `"$` in `__fixtures__/` files
|
||||
**Result:** 0 matches ✓
|
||||
**Classification:** N/A
|
||||
|
||||
### Search 6: Broader `$` in `.json` files
|
||||
**Result:** 0 matches ✓
|
||||
**Classification:** N/A
|
||||
|
||||
---
|
||||
|
||||
## Context: Existing Param Schemas
|
||||
|
||||
Found 66+ `paramsSchema` definitions across primitive implementations:
|
||||
- `seed-attribute.ts`
|
||||
- `absorb-damage-with-attribute.ts`
|
||||
- `reflect-damage.ts`
|
||||
- `add-aura.ts`
|
||||
- `modify-movement-range.ts`
|
||||
- `on-turn-start.ts`
|
||||
- `block-move-type.ts`
|
||||
- `add-to-attribute.ts`
|
||||
- `multiply-attribute.ts`
|
||||
- `on-capture.ts`
|
||||
- `override-promotion.ts`
|
||||
- `add-direction.ts`
|
||||
- `set-capture-flag.ts`
|
||||
- `on-damaged.ts`
|
||||
- `conditional.ts`
|
||||
- `on-move.ts`
|
||||
- `on-promotion.ts`
|
||||
- `on-check-received.ts`
|
||||
- `on-check-delivered.ts`
|
||||
- `on-moved-onto-square.ts`
|
||||
- `on-captured.ts`
|
||||
- `on-turn-end.ts`
|
||||
|
||||
**All schemas use conventional keys:** `key`, `value`, `delta`, `flag`, `ratio`, `to`, `direction`, `mode`, `moveType`, `target`, `percentage`, `condition`, `effects`, etc.
|
||||
|
||||
**No `$`-prefixed keys detected in any schema definition.**
|
||||
|
||||
---
|
||||
|
||||
## Verdict: ✅ CLEAN
|
||||
|
||||
**Confirmed:** The planned binding shape `{ $var: "name" }` (T12) is **safe to implement without collisions**.
|
||||
|
||||
### Impact Assessment
|
||||
|
||||
- ✅ No existing primitive params use `$var` or any `$`-prefixed key
|
||||
- ✅ No descriptor JSON fixtures contain `$`-prefixed values
|
||||
- ✅ No template or library code uses `$` as a key prefix
|
||||
- ✅ T12 can proceed with the binding shape as designed
|
||||
|
||||
### Recommendation
|
||||
|
||||
- Proceed with T12 implementation using `{ $var: "name" }` binding shape
|
||||
- No renaming of binding shape required
|
||||
- No code collisions to resolve
|
||||
|
||||
---
|
||||
|
||||
## Audit Verification
|
||||
|
||||
- Evidence file: `.sisyphus/evidence/task-5-var-conflict.txt`
|
||||
- Total searches: 6
|
||||
- Total matches across all searches: **0**
|
||||
- Audit document: this file (47 lines)
|
||||
|
||||
---
|
||||
|
||||
**Audit completed:** 2026-04-26 | **Blocked by:** T0 | **Blocks:** T12
|
||||
1926
.sisyphus/plans/thressgame-coverage.md
Normal file
1926
.sisyphus/plans/thressgame-coverage.md
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -0,0 +1,30 @@
|
|||
[
|
||||
{ "kind": "absorb-damage-with-attribute", "file": "absorb-damage-with-attribute.test.ts", "testCount": 4, "expectCount": 8 },
|
||||
{ "kind": "add-aura", "file": "add-aura.test.ts", "testCount": 4, "expectCount": 6 },
|
||||
{ "kind": "add-direction", "file": "add-direction.test.ts", "testCount": 7, "expectCount": 8 },
|
||||
{ "kind": "add-to-attribute", "file": "add-to-attribute.test.ts", "testCount": 4, "expectCount": 5 },
|
||||
{ "kind": "block-move-type", "file": "block-move-type.test.ts", "testCount": 4, "expectCount": 5 },
|
||||
{ "kind": "conditional", "file": "conditional.test.ts", "testCount": 6, "expectCount": 7 },
|
||||
{ "kind": "consumer-integration", "file": "consumer-integration.test.ts", "testCount": 6, "expectCount": 11 },
|
||||
{ "kind": "context", "file": "context.test.ts", "testCount": 13, "expectCount": 20 },
|
||||
{ "kind": "docs", "file": "docs.test.ts", "testCount": 3, "expectCount": 8 },
|
||||
{ "kind": "manifest", "file": "manifest.test.ts", "testCount": 5, "expectCount": 14 },
|
||||
{ "kind": "modify-movement-range", "file": "modify-movement-range.test.ts", "testCount": 4, "expectCount": 5 },
|
||||
{ "kind": "multiply-attribute", "file": "multiply-attribute.test.ts", "testCount": 4, "expectCount": 5 },
|
||||
{ "kind": "on-captured", "file": "on-captured.test.ts", "testCount": 10, "expectCount": 23 },
|
||||
{ "kind": "on-capture", "file": "on-capture.test.ts", "testCount": 4, "expectCount": 5 },
|
||||
{ "kind": "on-check-delivered", "file": "on-check-delivered.test.ts", "testCount": 8, "expectCount": 10 },
|
||||
{ "kind": "on-check-received", "file": "on-check-received.test.ts", "testCount": 5, "expectCount": 9 },
|
||||
{ "kind": "on-damaged", "file": "on-damaged.test.ts", "testCount": 4, "expectCount": 5 },
|
||||
{ "kind": "on-moved-onto-square", "file": "on-moved-onto-square.test.ts", "testCount": 14, "expectCount": 15 },
|
||||
{ "kind": "on-move", "file": "on-move.test.ts", "testCount": 7, "expectCount": 10 },
|
||||
{ "kind": "on-promotion", "file": "on-promotion.test.ts", "testCount": 6, "expectCount": 9 },
|
||||
{ "kind": "on-turn-end", "file": "on-turn-end.test.ts", "testCount": 6, "expectCount": 7 },
|
||||
{ "kind": "on-turn-start", "file": "on-turn-start.test.ts", "testCount": 4, "expectCount": 5 },
|
||||
{ "kind": "override-promotion", "file": "override-promotion.test.ts", "testCount": 4, "expectCount": 7 },
|
||||
{ "kind": "reflect-damage", "file": "reflect-damage.test.ts", "testCount": 4, "expectCount": 6 },
|
||||
{ "kind": "registry-count", "file": "registry-count.test.ts", "testCount": 2, "expectCount": 4 },
|
||||
{ "kind": "registry", "file": "registry.test.ts", "testCount": 6, "expectCount": 8 },
|
||||
{ "kind": "seed-attribute", "file": "seed-attribute.test.ts", "testCount": 4, "expectCount": 5 },
|
||||
{ "kind": "set-capture-flag", "file": "set-capture-flag.test.ts", "testCount": 4, "expectCount": 5 }
|
||||
]
|
||||
78
packages/chess/src/__fixtures__/baseline-regression.test.ts
Normal file
78
packages/chess/src/__fixtures__/baseline-regression.test.ts
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
import { describe, expect, it } from "vitest";
|
||||
import fs from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
|
||||
describe("backward-compat baseline regression", () => {
|
||||
let baseline: { files: number; tests: number; timestamp: string };
|
||||
let primitiveBaseline: Array<{
|
||||
kind: string;
|
||||
file: string;
|
||||
testCount: number;
|
||||
expectCount: number;
|
||||
}>;
|
||||
|
||||
it("loads baseline JSON files", async () => {
|
||||
const baselineDir = path.dirname(import.meta.url.replace("file://", ""));
|
||||
const baselinePath = path.join(baselineDir, "baseline-test-count.json");
|
||||
const primitivePath = path.join(baselineDir, "baseline-primitive-tests.json");
|
||||
|
||||
const baselineData = await fs.readFile(baselinePath, "utf8");
|
||||
const primitiveData = await fs.readFile(primitivePath, "utf8");
|
||||
|
||||
baseline = JSON.parse(baselineData);
|
||||
primitiveBaseline = JSON.parse(primitiveData);
|
||||
|
||||
expect(baseline).toBeDefined();
|
||||
expect(primitiveBaseline).toBeDefined();
|
||||
});
|
||||
|
||||
it("primitive baseline JSON shape is well-formed", async () => {
|
||||
const baselineDir = path.dirname(import.meta.url.replace("file://", ""));
|
||||
const primitivePath = path.join(baselineDir, "baseline-primitive-tests.json");
|
||||
const primitiveData = await fs.readFile(primitivePath, "utf8");
|
||||
primitiveBaseline = JSON.parse(primitiveData);
|
||||
|
||||
expect(Array.isArray(primitiveBaseline)).toBe(true);
|
||||
expect(primitiveBaseline.length).toBeGreaterThanOrEqual(1);
|
||||
for (const entry of primitiveBaseline) {
|
||||
expect(typeof entry.kind).toBe("string");
|
||||
expect(typeof entry.file).toBe("string");
|
||||
expect(entry.testCount).toBeGreaterThanOrEqual(1);
|
||||
expect(entry.expectCount).toBeGreaterThanOrEqual(1);
|
||||
}
|
||||
});
|
||||
|
||||
it("baseline-test-count.json has expected shape", async () => {
|
||||
const baselineDir = path.dirname(import.meta.url.replace("file://", ""));
|
||||
const baselinePath = path.join(baselineDir, "baseline-test-count.json");
|
||||
const baselineData = await fs.readFile(baselinePath, "utf8");
|
||||
baseline = JSON.parse(baselineData);
|
||||
|
||||
expect(baseline.tests).toBeGreaterThanOrEqual(1324);
|
||||
expect(baseline.files).toBeGreaterThanOrEqual(1);
|
||||
expect(typeof baseline.timestamp).toBe("string");
|
||||
});
|
||||
|
||||
it("each primitive .test.ts file still meets-or-exceeds its baseline", async () => {
|
||||
const baselineDir = path.dirname(import.meta.url.replace("file://", ""));
|
||||
const primitivePath = path.join(baselineDir, "baseline-primitive-tests.json");
|
||||
const primitiveData = await fs.readFile(primitivePath, "utf8");
|
||||
primitiveBaseline = JSON.parse(primitiveData);
|
||||
|
||||
const dir = path.resolve(baselineDir, "..", "modifiers", "primitives");
|
||||
for (const entry of primitiveBaseline) {
|
||||
const filePath = path.join(dir, entry.file);
|
||||
const content = await fs.readFile(filePath, "utf8");
|
||||
const itMatches = content.match(/^\s*(it|test)\(/gm) ?? [];
|
||||
const expectMatches = content.match(/expect\(/g) ?? [];
|
||||
expect(
|
||||
itMatches.length,
|
||||
`${entry.file} test count regressed: expected >= ${entry.testCount}, got ${itMatches.length}`
|
||||
).toBeGreaterThanOrEqual(entry.testCount);
|
||||
expect(
|
||||
expectMatches.length,
|
||||
`${entry.file} expect count regressed: expected >= ${entry.expectCount}, got ${expectMatches.length}`
|
||||
).toBeGreaterThanOrEqual(entry.expectCount);
|
||||
}
|
||||
});
|
||||
});
|
||||
5
packages/chess/src/__fixtures__/baseline-test-count.json
Normal file
5
packages/chess/src/__fixtures__/baseline-test-count.json
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
{
|
||||
"files": 167,
|
||||
"tests": 1961,
|
||||
"timestamp": "2026-04-26T06:29:52Z"
|
||||
}
|
||||
85
packages/chess/src/__fixtures__/determinism/harness.test.ts
Normal file
85
packages/chess/src/__fixtures__/determinism/harness.test.ts
Normal file
|
|
@ -0,0 +1,85 @@
|
|||
import { describe, it, expect } from "vitest";
|
||||
import { ChessEngine } from "../../engine";
|
||||
import { runDeterminismCheck } from "./harness";
|
||||
|
||||
describe("runDeterminismCheck — standard chess sanity", () => {
|
||||
it("standard chess is deterministic across 100 iterations (e2-e4, e7-e5)", () => {
|
||||
const setup = () => new ChessEngine();
|
||||
const moves = [
|
||||
(engine: ChessEngine) => {
|
||||
// White e2 (square 12) → e4 (square 28).
|
||||
const legal = engine.getAllLegalMoves();
|
||||
const m = legal.find((mv) => mv.from === 12 && mv.to === 28);
|
||||
if (m === undefined) throw new Error("e2-e4 not found in legal moves");
|
||||
engine.applyMove(m);
|
||||
},
|
||||
(engine: ChessEngine) => {
|
||||
// Black e7 (square 52) → e5 (square 36).
|
||||
const legal = engine.getAllLegalMoves();
|
||||
const m = legal.find((mv) => mv.from === 52 && mv.to === 36);
|
||||
if (m === undefined) throw new Error("e7-e5 not found in legal moves");
|
||||
engine.applyMove(m);
|
||||
},
|
||||
];
|
||||
|
||||
const start = Date.now();
|
||||
const result = runDeterminismCheck(setup, moves, 100);
|
||||
const elapsed = Date.now() - start;
|
||||
|
||||
expect(result.matches).toBe(true);
|
||||
expect(result.iterations).toBe(100);
|
||||
expect(result.hash).toMatch(/^[0-9a-f]{64}$/);
|
||||
expect(result.mismatchAt).toBeUndefined();
|
||||
expect(result.mismatchHash).toBeUndefined();
|
||||
// Plan acceptance: 100 iterations must complete in < 5000ms.
|
||||
expect(elapsed).toBeLessThan(5000);
|
||||
});
|
||||
|
||||
it("default iterations = 100 when not specified", () => {
|
||||
const setup = () => new ChessEngine();
|
||||
const result = runDeterminismCheck(setup, []);
|
||||
expect(result.iterations).toBe(100);
|
||||
expect(result.matches).toBe(true);
|
||||
});
|
||||
|
||||
it("empty moves list still hashes the fresh engine deterministically", () => {
|
||||
const setup = () => new ChessEngine();
|
||||
const result = runDeterminismCheck(setup, [], 10);
|
||||
expect(result.matches).toBe(true);
|
||||
expect(result.iterations).toBe(10);
|
||||
expect(result.hash).toMatch(/^[0-9a-f]{64}$/);
|
||||
});
|
||||
|
||||
it("rejects iterations < 1", () => {
|
||||
expect(() =>
|
||||
runDeterminismCheck(() => new ChessEngine(), [], 0),
|
||||
).toThrow(/iterations must be >= 1/);
|
||||
expect(() =>
|
||||
runDeterminismCheck(() => new ChessEngine(), [], -1),
|
||||
).toThrow(/iterations must be >= 1/);
|
||||
});
|
||||
|
||||
it("detects non-determinism (negative test) and reports first divergent iteration", () => {
|
||||
// Synthetic mismatch: iteration 0 builds a plain engine; iteration 1+
|
||||
// spawns an extra pawn. The harness must catch the divergence on
|
||||
// iteration 1 and return mismatchAt=1 plus the divergent hash.
|
||||
let callCount = 0;
|
||||
const setup = () => {
|
||||
const engine = new ChessEngine();
|
||||
if (callCount++ > 0) {
|
||||
// Inject one extra fact set on iteration 1+; iteration 0 is the
|
||||
// clean reference.
|
||||
engine.spawnPiece("pawn", "white", 20);
|
||||
}
|
||||
return engine;
|
||||
};
|
||||
|
||||
const result = runDeterminismCheck(setup, [], 5);
|
||||
expect(result.matches).toBe(false);
|
||||
expect(result.iterations).toBe(5);
|
||||
expect(result.mismatchAt).toBe(1);
|
||||
expect(result.hash).toMatch(/^[0-9a-f]{64}$/);
|
||||
expect(result.mismatchHash).toMatch(/^[0-9a-f]{64}$/);
|
||||
expect(result.mismatchHash).not.toBe(result.hash);
|
||||
});
|
||||
});
|
||||
98
packages/chess/src/__fixtures__/determinism/harness.ts
Normal file
98
packages/chess/src/__fixtures__/determinism/harness.ts
Normal file
|
|
@ -0,0 +1,98 @@
|
|||
import type { ChessEngine } from "../../engine";
|
||||
import { hashEngineState } from "../../util/state-hash";
|
||||
|
||||
/**
|
||||
* Build a fresh ChessEngine in initial state.
|
||||
*
|
||||
* Called once per iteration so that iteration N cannot leak any state
|
||||
* (closures, caches, RNG cursors, accumulated facts) into iteration N+1.
|
||||
* If the setup function captures mutable closure state, the harness will
|
||||
* detect non-determinism and report it via {@link DeterminismResult.matches}.
|
||||
*/
|
||||
export type SetupFn = () => ChessEngine;
|
||||
|
||||
/**
|
||||
* Apply a single deterministic mutation to the given engine.
|
||||
*
|
||||
* Whatever the engine's actual move-application API is — typically
|
||||
* `engine.applyMove(legalMove)` after looking the move up via
|
||||
* `engine.getAllLegalMoves()`. The MoveFn closes over its own input
|
||||
* lookups (e.g. a from/to pair) and is responsible for resolving them
|
||||
* fresh against the engine on every iteration.
|
||||
*/
|
||||
export type MoveFn = (engine: ChessEngine) => void;
|
||||
|
||||
export interface DeterminismResult {
|
||||
/** SHA256 hex of the final state from iteration 0 (the reference). */
|
||||
readonly hash: string;
|
||||
/** True iff every iteration produced the same hash. */
|
||||
readonly matches: boolean;
|
||||
/** Number of iterations the harness was asked to run. */
|
||||
readonly iterations: number;
|
||||
/** First iteration index that diverged. Set only when `matches === false`. */
|
||||
readonly mismatchAt?: number;
|
||||
/** Hash from the first divergent iteration. Set only when `matches === false`. */
|
||||
readonly mismatchHash?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Run the same `setup → moves → hash` pipeline N times and assert the final
|
||||
* state hash is byte-identical across every iteration.
|
||||
*
|
||||
* The harness contract:
|
||||
* 1. Call `setup()` to build a fresh engine.
|
||||
* 2. For each `move` in `moves`, invoke `move(engine)`.
|
||||
* 3. Compute `hashEngineState(engine)`.
|
||||
* 4. Compare to the reference hash from iteration 0.
|
||||
* 5. On any mismatch, return immediately with `matches: false` plus the
|
||||
* iteration index and divergent hash for diagnostic surfacing.
|
||||
*
|
||||
* No `Math.random` / `Date.now` / unsorted iteration is used internally —
|
||||
* the harness itself is deterministic by construction. Any non-determinism
|
||||
* MUST come from the setup or moves (which is exactly what we're testing).
|
||||
*
|
||||
* Default iterations = 100, matching the plan's N=100 byte-identical invariant
|
||||
* (`.sisyphus/notepads/thressgame-coverage/decisions.md` "Seeded RNG").
|
||||
*
|
||||
* @param setup Fresh-engine factory; called once per iteration.
|
||||
* @param moves Sequence of mutations applied in order to each fresh engine.
|
||||
* Empty array is legal — produces a "fresh-engine-only" hash.
|
||||
* @param iterations Number of iterations to run (default 100; must be ≥ 1).
|
||||
* @returns Result with reference hash and match status.
|
||||
* @throws If `iterations < 1`.
|
||||
*/
|
||||
export function runDeterminismCheck(
|
||||
setup: SetupFn,
|
||||
moves: readonly MoveFn[],
|
||||
iterations = 100,
|
||||
): DeterminismResult {
|
||||
if (iterations < 1) {
|
||||
throw new Error(
|
||||
`runDeterminismCheck: iterations must be >= 1, got ${iterations}`,
|
||||
);
|
||||
}
|
||||
|
||||
let referenceHash: string | undefined;
|
||||
for (let i = 0; i < iterations; i++) {
|
||||
const engine = setup();
|
||||
for (const move of moves) move(engine);
|
||||
const hash = hashEngineState(engine);
|
||||
if (referenceHash === undefined) {
|
||||
referenceHash = hash;
|
||||
continue;
|
||||
}
|
||||
if (hash !== referenceHash) {
|
||||
return {
|
||||
hash: referenceHash,
|
||||
matches: false,
|
||||
iterations,
|
||||
mismatchAt: i,
|
||||
mismatchHash: hash,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// referenceHash is defined here because iterations >= 1 means the loop
|
||||
// ran at least once and assigned it.
|
||||
return { hash: referenceHash as string, matches: true, iterations };
|
||||
}
|
||||
61
packages/chess/src/util/state-hash.test.ts
Normal file
61
packages/chess/src/util/state-hash.test.ts
Normal file
|
|
@ -0,0 +1,61 @@
|
|||
import { describe, it, expect } from "vitest";
|
||||
import { ChessEngine } from "../engine";
|
||||
import { hashEngineState } from "./state-hash";
|
||||
|
||||
describe("hashEngineState", () => {
|
||||
it("returns 64-char lowercase hex", () => {
|
||||
const engine = new ChessEngine();
|
||||
const hash = hashEngineState(engine);
|
||||
expect(hash).toMatch(/^[0-9a-f]{64}$/);
|
||||
});
|
||||
|
||||
it("identical state produces identical hash", () => {
|
||||
const a = new ChessEngine();
|
||||
const b = new ChessEngine();
|
||||
expect(hashEngineState(a)).toBe(hashEngineState(b));
|
||||
});
|
||||
|
||||
it("one fact difference produces different hash", () => {
|
||||
const a = new ChessEngine();
|
||||
const b = new ChessEngine();
|
||||
|
||||
// Spawn a pawn on b only, introducing one fact difference.
|
||||
b.spawnPiece("pawn", "white", 12);
|
||||
|
||||
const hashA = hashEngineState(a);
|
||||
const hashB = hashEngineState(b);
|
||||
expect(hashA).not.toBe(hashB);
|
||||
});
|
||||
|
||||
it("insertion-order independence (same entity, different attr insertion order)", () => {
|
||||
// Test that inserting attributes for the same entity in different orders
|
||||
// produces the same hash. Since allFacts() sorts by [id, attr], the order
|
||||
// of insertion doesn't affect the final state representation.
|
||||
|
||||
const e1 = new ChessEngine();
|
||||
const id1 = e1.session.nextId();
|
||||
e1.session.insert(id1, "Color", "white");
|
||||
e1.session.insert(id1, "PieceType", "pawn");
|
||||
e1.session.insert(id1, "Position", 12);
|
||||
const hash1 = hashEngineState(e1);
|
||||
|
||||
// Replay with different insertion order
|
||||
const e2 = new ChessEngine();
|
||||
const id2 = e2.session.nextId();
|
||||
e2.session.insert(id2, "Position", 12);
|
||||
e2.session.insert(id2, "Color", "white");
|
||||
e2.session.insert(id2, "PieceType", "pawn");
|
||||
const hash2 = hashEngineState(e2);
|
||||
|
||||
// Yet another order
|
||||
const e3 = new ChessEngine();
|
||||
const id3 = e3.session.nextId();
|
||||
e3.session.insert(id3, "PieceType", "pawn");
|
||||
e3.session.insert(id3, "Position", 12);
|
||||
e3.session.insert(id3, "Color", "white");
|
||||
const hash3 = hashEngineState(e3);
|
||||
|
||||
expect(hash1).toBe(hash2);
|
||||
expect(hash2).toBe(hash3);
|
||||
});
|
||||
});
|
||||
50
packages/chess/src/util/state-hash.ts
Normal file
50
packages/chess/src/util/state-hash.ts
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
import { createHash } from "node:crypto";
|
||||
import type { ChessEngine } from "../engine";
|
||||
|
||||
/**
|
||||
* Deterministic SHA256 hash of a ChessEngine's full session state.
|
||||
*
|
||||
* Insertion order independent: same facts hash equally regardless of order.
|
||||
* Two engines with identical facts MUST produce identical hashes; any single
|
||||
* fact difference MUST produce a different hash.
|
||||
*
|
||||
* Algorithm:
|
||||
* 1. Enumerate all facts via session.allFacts() (already sorted: id asc, attr asc).
|
||||
* 2. Group facts by entity id.
|
||||
* 3. For each entity id (in sorted order): stringify { id, facts: [[attr, value], ...] }
|
||||
* where facts are sorted by attr name (already sorted by session).
|
||||
* 4. Concatenate all stringified entries with newlines.
|
||||
* 5. SHA256 the concatenation, return hex digest.
|
||||
*
|
||||
* Usage: determinism property tests (T2), parity tests (T59+), debugging.
|
||||
*/
|
||||
export function hashEngineState(engine: ChessEngine): string {
|
||||
const session = engine.session;
|
||||
const facts = session.allFacts();
|
||||
|
||||
// Group facts by entity id. Since allFacts() returns facts sorted by
|
||||
// [id asc, attr asc], we can stream through once and accumulate.
|
||||
const factsByEntity = new Map<number, Array<[string, unknown]>>();
|
||||
for (const fact of facts) {
|
||||
const id = fact.id as number;
|
||||
if (!factsByEntity.has(id)) {
|
||||
factsByEntity.set(id, []);
|
||||
}
|
||||
factsByEntity.get(id)!.push([fact.attr, fact.value]);
|
||||
}
|
||||
|
||||
// Sort entity ids numerically (ascending) and build deterministic strings.
|
||||
const entityIds = Array.from(factsByEntity.keys()).sort((a, b) => a - b);
|
||||
const parts: string[] = [];
|
||||
|
||||
for (const id of entityIds) {
|
||||
const facts = factsByEntity.get(id)!;
|
||||
// Facts are already sorted by attr due to session.allFacts() guarantees.
|
||||
// Stringify each entity record as { id, facts: [[attr, val], ...] }.
|
||||
parts.push(JSON.stringify({ id, facts }));
|
||||
}
|
||||
|
||||
// Concatenate and hash.
|
||||
const blob = parts.join("\n");
|
||||
return createHash("sha256").update(blob).digest("hex");
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue