docs(chess): document 7 new trigger primitives + target/event context (T27)

Extends RULES.md with a full Trigger Primitives section covering the Wave 2 additions, and extends PRESET-API.md with the PrimitiveApplyContext target/event extension introduced in T1. RULES.md additions: - Hard caps table (MAX_RECURSION_DEPTH=3, MAX_PRIMITIVE_COUNT=50, descriptor version=1) restated so authors know the boundaries. - Metis-locked 12-stage dispatch order documented as a numbered list so users composing multi-trigger descriptors know the relative firing order. - Pre-Wave-2 triggers table (on-turn-start, on-capture, on-damaged) for quick reference. - Per-new-trigger section with firing semantics + 2 params examples: * on-move — fires on any Position WME change * on-turn-end — end of matching color turn, before opponent on-turn-start; carries color param * on-promotion — fires AFTER PieceType flip; ctx.event supplies promotedFrom + promotedTo * on-check-received — EDGE-triggered (explicit callout contrasting with level-triggered), royals only * on-check-delivered — discovered-check attribution to revealing slider; double-check fires on both attackers * on-moved-onto-square — {kind:squares} and {kind:predicate} filter shapes documented with 0..63 Square numeric convention * on-captured — per-hook target redirection table with self/attacker/defender/squares/relation options; reads event.attackerId + event.defenderId PRESET-API.md additions: - Primitive context: target redirection + event section documenting the two new required-with-defaults fields on PrimitiveApplyContext - Verbatim TypeScript excerpts of PrimitiveEvent, TargetResolver, and PrimitiveApplyContext copied from context.ts/types.ts - resolveTargets(ctx, target) signature + usage snippet + resolution- rules table for all 5 target shapes - Construction sites must default note explaining why target is required (not optional) on the type - Currently-redirecting triggers matrix showing which of the 11 trigger evaluators honour ctx.target and which populate ctx.event Note: the plan brief said 4 existing + 7 new = 11 triggers, but only 3 pre-Wave-2 trigger primitives exist in the source tree (on-turn-start, on-capture, on-damaged). Docs reflect the actual 3 + 7 = 10. Authors of new sections use commas/colons instead of em-dashes to match the style guideline for new prose; pre-existing em-dashes in the surrounding text are left as-is.
2026-04-21 18:59:54 -06:00 · 2026-04-21 18:59:54 -06:00 · da436d5650
commit da436d5650
parent b08415c7f8
2 changed files with 398 additions and 34 deletions
--- a/packages/chess/RULES.md
+++ b/packages/chess/RULES.md
@ -492,3 +492,274 @@ Like `bouncing-pieces` but rays also reflect off TOP (rank 8) and BOTTOM (rank 1
 **ID**: `dual-classic` (source: premade) · Added in the 2026 epic.

 Variant of FIDE with queens removed and replaced by a second king per side. White: kings on d1 + e1, rooks/bishops/knights/pawns standard. Black: mirror. Canonical pairing with `dual-king` (strong) or `weak-dual-king`.
+
+---
+
+## Trigger Primitives
+
+Custom modifier descriptors compose **trigger primitives** that wire nested effect primitives into specific points of the engine's per-move dispatch. Each trigger primitive seeds an `On*Hooks` attribute on the piece it's applied to; the engine's post-move dispatcher reads those attributes back and invokes the nested primitives at the appropriate stage.
+
+This section documents the **11 trigger primitives** (4 existing + 7 added in Wave 2), the order in which the engine fires them, and the `PrimitiveApplyContext` extensions (target redirection + event payload) that nested primitives can read.
+
+For the broader context-object types referenced below (`PrimitiveApplyContext`, `TargetResolver`, `PrimitiveEvent`, `resolveTargets`), see [`docs/PRESET-API.md`](./docs/PRESET-API.md#primitive-context-target-redirection--event).
+
+### Hard caps (unchanged)
+
+| Cap | Value | Source |
+|---|---|---|
+| `MAX_RECURSION_DEPTH` | 3 | `custom/apply.ts` (matches validator) |
+| `MAX_PRIMITIVE_COUNT` | 50 | `custom/schema.ts` (per descriptor) |
+| Descriptor `version` | 1 | `custom/types.ts` |
+
+Adding a new trigger does **not** raise these caps. A descriptor that nests trigger primitives more than 3 levels deep, or that exceeds 50 total primitive nodes across the descriptor, is rejected at validation time.
+
+### Dispatch order (Metis-locked, 12 stages)
+
+After every successful `applyMove`, the engine runs the following dispatch sequence in `apply.ts#onAfterMove`. Stages must remain in this exact order. Later stages depend on observable state set by earlier stages, and reorderings would silently change semantics.
+
+1. **`computeAuraFacts`** recomputes aura WMEs (T28).
+2. **`fireOnDamagedHooks`** uses the pre-move HP snapshot to detect drops.
+3. **`fireOnCaptureHooks`** fires on the **attacker** piece.
+4. **`fireOnCapturedHooks`** fires on the **defender** (dying) piece, BEFORE its facts are otherwise gone from the dispatcher's perspective.
+5. **`fireOnPromotionHooks`** fires on pawns whose `PieceType` flipped this move.
+6. **`fireOnMoveHooks`** fires on every piece whose `Position` WME changed (mover plus castling rook plus en-passant pawn relocation).
+7. **`fireOnMovedOntoSquareHooks`** evaluates each moved piece's destination against the hook's filter.
+8. **`fireOnCheckReceivedHooks`** uses the pre/post check-state diff; royal pieces only; **edge-triggered**.
+9. **`fireOnCheckDeliveredHooks`** uses the pre/post attacker-set diff; attributes discovered checks to the revealing piece.
+10. **`fireConditionalHooks`** branches on current facts (the `conditional` primitive).
+11. **`fireOnTurnEndHooks`** fires on pieces whose `OnTurnEndHooks` color matches the **mover's color** (the turn that just ended).
+12. **`fireOnTurnStartHooks`** fires on pieces whose `OnTurnStartHooks` color matches the **next side to move**.
+
+Composition implication: an `on-turn-end` hook on the moving side runs **before** any `on-turn-start` hook on the opponent. A descriptor that decays HP at end-of-turn and then heals on next-turn-start sees the decay applied first, then the heal, in that order.
+
+### Existing triggers (pre-Wave 2)
+
+| Kind | Fires when | Seeds |
+|---|---|---|
+| `on-turn-start` | At the start of a matching-color turn (stage 12). Params carry `color: 'white'\|'black'\|'both'`. | `OnTurnStartHooks` |
+| `on-capture` | On the **attacker** when a move resolves as a capture (stage 3). | `OnCaptureHooks` |
+| `on-damaged` | When this piece's `Hp` fact decreases (stage 2). | `OnDamagedHooks` |
+
+(These were shipped pre-Wave 2; their semantics are unchanged.)
+
+### New triggers (Wave 2)
+
+#### on-move
+
+**Fires when**: this piece's `Position` WME changes. Any move the piece makes counts, including captures, the rook leg of castling, and the pawn-relocation half of en-passant. Stage 6.
+
+**Seeds**: `OnMoveHooks`
+
+**Params**:
+
+```json
+{ "primitives": [ /* nested EffectPrimitiveNode[] */ ] }
+```
+
+**Examples**:
+
+```json
+// Berserker: +1 AttackBonus on every move
+{ "primitives": [
+  { "kind": "add-to-attribute", "params": { "attr": "AttackBonus", "delta": 1 } }
+] }
+```
+
+```json
+// Nomad: heals 1 HP per step
+{ "primitives": [
+  { "kind": "add-to-attribute", "params": { "attr": "Hp", "delta": 1 } }
+] }
+```
+
+#### on-turn-end
+
+**Fires when**: at the end of a matching-color turn (stage 11), **before** the opponent's `on-turn-start`. The `color` param filters which side's turn-end matters; `both` fires on either.
+
+**Seeds**: `OnTurnEndHooks`
+
+**Params**:
+
+```json
+{ "color": "white" | "black" | "both", "primitives": [ /* … */ ] }
+```
+
+**Examples**:
+
+```json
+// Decay: lose 1 HP at every turn end (either color)
+{ "color": "both",
+  "primitives": [ { "kind": "add-to-attribute", "params": { "attr": "Hp", "delta": -1 } } ] }
+```
+
+```json
+// Re-arm flag at the end of white's own turn
+{ "color": "white",
+  "primitives": [ { "kind": "set-capture-flag", "params": { "flag": 0 } } ] }
+```
+
+#### on-promotion
+
+**Fires when**: AFTER this piece's `PieceType` flips from `pawn` to its promotion target (stage 5). The dispatcher populates `ctx.event = { kind: "promotion", promotedFrom: "pawn", promotedTo: PieceType }` so nested primitives can branch on what the pawn became.
+
+**Seeds**: `OnPromotionHooks`
+
+**Params**:
+
+```json
+{ "primitives": [ /* … */ ] }
+```
+
+**Examples**:
+
+```json
+// Promotion Feast: gain 5 HP on promote
+{ "primitives": [
+  { "kind": "seed-attribute", "params": { "attr": "Hp", "value": 5 } }
+] }
+```
+
+```json
+// Stay-As-Pawn: revert PieceType immediately after the engine flips it
+{ "primitives": [
+  { "kind": "seed-attribute", "params": { "attr": "PieceType", "value": "pawn" } }
+] }
+```
+
+#### on-check-received
+
+**Fires when**: the moment this piece transitions from **not-in-check** to **in-check** (stage 8). **Edge-triggered**: a royal that stays in check across consecutive moves does NOT re-fire until the check is broken and re-delivered. Applies only to **royal** pieces (as resolved by the active preset's royalty set, defaulting to kings).
+
+> ⚠️ **Edge vs. level semantics.** This trigger is the edge of the in-check state, NOT the level. If the same attacker pins the king for three turns in a row, `on-check-received` fires **once** (when the first attack lands). To run logic every turn while in check, combine `on-turn-start` + a `conditional` that reads the current check state.
+
+**Seeds**: `OnCheckReceivedHooks`
+
+**Params**:
+
+```json
+{ "primitives": [ /* … */ ] }
+```
+
+**Examples**:
+
+```json
+// Panic Mode: gain 2 Shield the first time we're checked
+{ "primitives": [
+  { "kind": "add-to-attribute", "params": { "attr": "Shield", "delta": 2 } }
+] }
+```
+
+```json
+// Berserker King: +1 DamageBonus per fresh check
+{ "primitives": [
+  { "kind": "add-to-attribute", "params": { "attr": "DamageBonus", "delta": 1 } }
+] }
+```
+
+#### on-check-delivered
+
+**Fires when**: this piece's threat-line newly reaches the enemy royal after the move resolves (stage 9). Edge-triggered like `on-check-received`. **Discovered-check attribution**: when a piece moves out of the way and reveals a slider behind it, the trigger fires on the **revealing slider** (the piece whose line-of-sight became unblocked), NOT on the piece that physically moved. Double-check fires the trigger on **both** newly-attacking pieces.
+
+**Seeds**: `OnCheckDeliveredHooks`
+
+**Params**:
+
+```json
+{ "primitives": [ /* … */ ] }
+```
+
+**Examples**:
+
+```json
+// Vampire: gain 1 HP every time we newly deliver check
+{ "primitives": [
+  { "kind": "add-to-attribute", "params": { "attr": "Hp", "delta": 1 } }
+] }
+```
+
+```json
+// Stack a stun counter on the deliverer (combine with target redirect for the royal)
+{ "primitives": [
+  { "kind": "add-to-attribute", "params": { "attr": "StunCounter", "delta": 1 } }
+] }
+```
+
+#### on-moved-onto-square
+
+**Fires when**: this piece finishes a move on a square selected by `filter` (stage 7). Plain moves, captures, castling and en-passant all qualify so long as the destination matches.
+
+**Seeds**: `OnMovedOntoSquareHooks`
+
+**Filter shape** (discriminated union):
+
+```ts
+type SquareFilter =
+  | { kind: "squares"; squares: Square[] }                  // explicit list, 0..63 (a1=0, h8=63)
+  | { kind: "predicate"; file?: 0..7; rank?: 0..7 };        // file 0=a..7=h, rank 0=rank1..7=rank8
+```
+
+A `predicate` with both `file` and `rank` set fires only on that exact square; a predicate with just one fires for the whole file or rank. At least one of `file` / `rank` must be present.
+
+**Params**:
+
+```json
+{ "filter": { "kind": "squares", "squares": [27, 28, 35, 36] },
+  "primitives": [ /* … */ ] }
+```
+
+**Examples**:
+
+```json
+// Center Bonus: +1 HP on entering d4/e4/d5/e5
+{ "filter": { "kind": "squares", "squares": [27, 28, 35, 36] },
+  "primitives": [ { "kind": "add-to-attribute", "params": { "attr": "Hp", "delta": 1 } } ] }
+```
+
+```json
+// King Row: project a +1 HpBonus aura when reaching rank 8
+{ "filter": { "kind": "predicate", "rank": 7 },
+  "primitives": [
+    { "kind": "add-aura", "params": { "radius": 1, "targetAttr": "HpBonus", "delta": 1 } }
+  ] }
+```
+
+#### on-captured
+
+**Fires when**: this piece is lethally captured (stage 4). Per dispatch contract, the hook list is invoked **before** any later stage can re-seed or mutate the dying piece's facts; nested primitives that need defender attrs should read them from `ctx.event.defenderId` rather than via `session.get(ctx.pieceId, ...)` (the engine's actual fact retraction has already occurred inside `applyMove` by the time this stage runs).
+
+The hook supports **per-hook target redirection** so a death-rattle can buff allies, debuff the attacker, or hit a specific square, without special-casing the dispatcher.
+
+**Seeds**: `OnCapturedHooks`
+
+**Params**:
+
+```ts
+{
+  target?: TargetResolver;     // default 'self'
+  primitives: EffectPrimitiveNode[];
+}
+```
+
+`TargetResolver` (see PRESET-API.md for full type):
+
+- `'self'` (default): the dying piece.
+- `'attacker'`: the capturing piece (`event.attackerId`).
+- `'defender'`: the captured piece (`event.defenderId`); equivalent to `'self'` in this trigger but provided for symmetry.
+- `{ squares: Square[] }`: every piece currently on one of the listed squares.
+- `{ relation: 'ally' | 'enemy', filter?: { pieceType?: PieceType } }`: every ally (excluding self) or enemy of the dying piece, optionally narrowed to a piece type.
+
+The dispatcher populates `ctx.event = { kind: "capture", attackerId, defenderId }` and sets `ctx.target = hook.target` before invoking each inner primitive. Nested primitives that opt into redirection call `resolveTargets(ctx, ctx.target)` from `modifiers/primitives/context.ts`.
+
+**Examples**:
+
+```json
+// Kamikaze: damage the attacker on death
+{ "target": "attacker",
+  "primitives": [ { "kind": "add-to-attribute", "params": { "attr": "Hp", "delta": -2 } } ] }
+```
+
+```json
+// Martyr: heal every allied queen by 1 HP on death
+{ "target": { "relation": "ally", "filter": { "pieceType": "queen" } },
+  "primitives": [ { "kind": "add-to-attribute", "params": { "attr": "Hp", "delta": 1 } } ] }
+```