jyapayne/houserules
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
houserules/docs/adr/modifier-profiles.md

14 KiB
Raw Blame History

ADR: Piece Modifier Profiles Architecture

This document captures the eight architectural decisions that shape the T1 piece-modifier-profiles feature. Each section is self-contained and records the decision, the reasoning behind it, and the alternatives that were considered and rejected.

ADR-1: Move Generator Hook Contract — WRAP (not REPLACE)

Decision

Introduce a new hook signature on modifier/preset descriptors:

transformMoveGenerator?(engine, pieceId, prevGenerator) => MoveGenerator

Each hook receives the previous generator in the chain and returns a new one. Multiple presets plus the active profile can all contribute, composing in precedence order. The generator returned by the chain emits pseudo-legal moves only.

Rationale

  • Composition over replacement. Several modifier sources (presets, per-type profile entries, per-instance profile entries) must be able to stack without one clobbering another.
  • Clear layering. The engine's legality layer (self-check filter, turn validation, repetition detection) always runs downstream of the generator chain. Hooks never need to reason about whole-board legality — only about the piece's own movement facts.
  • Deterministic ordering. Precedence (ADR-5) uniquely defines the order in which generators are wrapped, so the final generator is reproducible from the profile alone.

Rejected Alternatives

  • REPLACE semantics (only the first/highest-priority hook wins): kills composition. Two independent modifiers that both want to alter movement could not coexist, forcing users to choose one or hand-merge them.
  • Mid-chain interception (hooks can peek at or mutate moves emitted by other hooks): dramatically more complex to reason about, breaks locality, and makes determinism hard to audit.

ADR-2: Per-Instance Identity Keying — Layout-Slot Bound (Option B)

Decision

Per-instance modifier entries in a profile are keyed by the piece's starting square in algebraic notation (e.g. "b1"). The profile document carries an optional layoutId field. At game start, applyProfileToSession resolves each square → EntityId by consulting the layout's piece placement array.

Cross-layout reuse is permitted for the per-type portion of a profile. The per-instance portion is dropped with a warning when the active layout does not contain the referenced square (orphan handling — see ADR-6 check #3).

Rationale

  • Human-readable. Profile JSON (and any URL-encoded form) stays legible: a designer can see "b1": { ... } and immediately know which piece it targets.
  • Portable within a layout. Two sessions using the same layout can share the profile verbatim.
  • Graceful degradation. When a profile is applied against a different layout, per-type rules still apply; only the now-meaningless per-instance keys are dropped, with a surfaced warning.

Rejected Alternatives

  • Option A — key by EntityId. EntityIds are session-scoped runtime handles; they are meaningless outside the session that produced them. This would make profiles non-portable and impossible to author by hand.
  • Option C — defer per-instance entirely to T2. Per-instance keying is the single feature that makes "this specific rook on b1" different from "all rooks" possible in T1; deferring it would gut the feature's value.

ADR-3: Hot-Swap Reconciliation Rules

Decision

When a profile is swapped on a live game, each modifier kind reconciles according to the following table:

Modifier On swap-apply On swap-remove
HpBonus maxHp recomputed; currentHp = min(currentHp, newMax) currentHp never grows (same rule)
RangeBonus Overwrite fact; next legal-move query reflects new range Revert to base; same query semantics
DirectionAdditions Overwrite fact; next legal-move query includes/excludes Revert to base direction set
CaptureFlags Overwrite; applies to the next capture event Revert; applies to next capture
PromotionOverride Overwrite; applies to future promotions only Revert; future promotions use base
DamageResistance Overwrite; applies to the next damage event Revert; next damage uses base

Timing. Hot-swaps are applied at the turn boundary only — after turnEnd fires and before the next turnStart. Any update received mid-turn is queued and flushed at that boundary.

Failure / rollback. The server is authoritative and clients hold no optimistic state for profile changes. If a swap is rejected (legality validator fails, permission denied, etc.) the server sends a NACK to the originating client and performs no broadcast. There is no per-event rollback to unwind partially-applied effects, because effects do not apply until the boundary.

Rationale

  • Determinism. Applying changes strictly at turn boundaries means every observer (players, spectators, replays) sees an identical sequence of (state, swap, state, swap) transitions.
  • HP invariant. The "never grows" rule for currentHp preserves the intuition that removing a buff should not heal; applying a buff raises the ceiling but never the floor.
  • Server authority. Keeping clients dumb about swap outcomes avoids a whole class of desync bugs; the NACK pattern keeps the protocol simple.

Rejected Alternatives

  • Mid-turn application. Introduces ordering ambiguity relative to queued events, move-generation caches, and partially-resolved attacks; determinism becomes painful to reason about.
  • Per-event rollback. Would require journaling every effect so it can be unwound on failure. T1 does not need this level of sophistication, and the boundary-only rule makes it unnecessary.

ADR-4: Stacking Rules per Modifier Kind

Decision

Each T1 modifier kind declares a fixed stacking rule, applied whenever more than one source contributes a value (per ADR-5 precedence):

Modifier Stacking rule Formula
HpBonus Additive sum of all sources
RangeBonus Additive, clamped [0, 7] sum, then clamp
DirectionAdditions Union set union of arrays
CaptureFlags Union (bitwise OR) flags OR'd together
PromotionOverride Precedence wins perInstance > perType > preset
DamageResistance Multiplicative 1 - ∏(1 - r_i), clamped ≥ 0

Rationale

  • Additive/union kinds have natural commutative/associative semantics, so order of application does not matter. This is safe to compute in any order.
  • Clamping RangeBonus to the 0..7 board diagonal keeps generators sane; an 8-square-wide board can never need more than 7 steps of range.
  • Multiplicative DamageResistance matches player intuition: two sources of 50% resistance yield 75% total, not 100%. This prevents accidental invulnerability from additive stacking.
  • PromotionOverride as "precedence wins" reflects that overrides are replacement-style facts — two simultaneous overrides cannot meaningfully merge, so the highest-priority one is chosen.

Rejected Alternatives

  • All-additive (including resistance): trivially produces 100% resistance with two modest sources, breaking balance.
  • All-overwrite: kills the expressive power of stacking entirely and forces designers to pre-merge any combination of modifiers they want.

ADR-5: Precedence Chain

Decision

When multiple sources contribute to the same piece and modifier kind, the priority order is:

per-instance (profile)  >  per-type (profile)  >  preset  >  engine base
  • For additive and union stacking rules (see ADR-4), all sources contribute; precedence only controls the order in which hooks wrap the move generator (ADR-1).
  • For override kinds (e.g. PromotionOverride), only the highest-priority source wins.

Rationale

  • Specificity first. Per-instance data is the most specific statement ("this piece on b1"), per-type is broader ("all bishops"), preset is broader still ("this game mode"), and engine base is the default. Higher specificity winning matches designer expectations and mirrors how CSS, config layering, and similar systems behave.
  • Composable by default. Treating additive/union kinds as contributors rather than gated by precedence means a per-type buff and a per-instance buff can both apply, which is the whole point of having two layers.

Rejected Alternatives

  • Preset-first (preset beats profile): undermines user-authored profiles and makes game modes unmodifiable.
  • Flat merge with no precedence: leaves override-style modifiers ambiguous.

ADR-6: Legality Validator Checklist

Decision

On every profile apply and every hot-swap, the engine runs a legality validator with five checks. Each check has a stable error code for client-side reporting.

  1. Both sides have ≥ 1 king. Code: E_PROFILE_NO_KING. Error.
  2. No king carries CaptureFlags = CANNOT_BE_CAPTURED. Code: E_PROFILE_INVULN_KING. Error.
  3. No orphan per-instance entries (per-instance key references a square not present in the active layout). Code: E_PROFILE_ORPHAN_INSTANCE. Warning only, not a rejection — the orphan entry is dropped per ADR-2.
  4. Each side has ≥ 1 legal move from the current position. Code: E_PROFILE_DEADLOCK. Error.
  5. Total resolved facts per piece ≤ 16 attributes. Code: E_PROFILE_ATTR_LIMIT. Error.

Checks that emit an error cause the apply/swap to be rejected atomically; no partial state is observable. Warnings are surfaced but do not block application.

Rationale

  • Win-condition integrity. Checks 1 and 2 guarantee the game can still be won — you cannot accidentally author a profile that removes all kings or makes a king uncapturable.
  • Playability. Check 4 prevents instant deadlocks at swap time.
  • Performance & sanity ceiling. Check 5 caps the fact-set per piece so that the attribute system cannot be overwhelmed by pathological profiles.
  • User experience. Check 3 is a warning rather than an error because dropping irrelevant per-instance keys (see ADR-2) is the documented behaviour when applying across layouts.

Rejected Alternatives

  • No validator — trust the author. Produces unrecoverable games and makes server state hard to reason about.
  • Validator as errors only (no warnings). Would force cross-layout reuse to be a hard failure, defeating ADR-2's portability goal.
  • Validator at game-start only. Misses hot-swap-introduced corruptions.

ADR-7: Single Active Profile Per Game (T1)

Decision

In T1, exactly one profile is active on a given game at a time. Changing the active profile is a full swap performed by sending a modifier-profile.update WebSocket message. Profile stacking or layered composition of multiple profiles is explicitly deferred to T2+.

Rationale

  • Scope control. T1 already introduces a new hook, registry, profile document shape, and validator. Adding multi-profile composition on top would multiply the edge cases (ordering between profiles, overlap conflicts, partial updates) and delay the feature.
  • Simple mental model. "One profile, swap to change it" is trivially understandable by end users and matches how presets are selected today.
  • Forward-compatible. The swap message already carries a full profile payload; a future multi-profile world can extend the same message shape (e.g. profiles: Profile[]) without breaking T1 clients.

Rejected Alternatives

  • Multi-profile composition in T1. Punts on too many unresolved design questions (inter-profile precedence, addition vs replacement, diffing) to fit in the T1 milestone.
  • Additive deltas only (no full swap). Harder to reason about when recovering from a corrupted state; the full-swap primitive is simpler and can always simulate a delta by applying a re-derived profile.

ADR-8: Registry Pattern for Modifier Catalog

Decision

Each T1 modifier kind lives in its own file under:

packages/chess/src/modifiers/descriptors/{kind}.ts

At module load time the file self-registers into MODIFIER_REGISTRY, mirroring the existing PRESET_REGISTRY and LAYOUT_REGISTRY patterns (with register(def), get(id), list(), has(id) surface).

The descriptor shape is:

{
  id,
  attrName,
  label,
  valueSchema,
  stackingRule,
  apply,
  describe,
  uiForm,
}

T3 custom (user-defined) modifiers will plug into this same registry, requiring no changes to the registry contract itself.

Rationale

  • One modifier = one file. Adding a new modifier kind is a single-file addition, not a multi-file edit across schema, engine, UI, and validator. This is the same ergonomic property that makes the preset and layout registries pleasant to extend.
  • Consistency with existing patterns. The codebase already has two registries following this shape; a third avoids introducing a new idiom to learn.
  • T3-ready. Framing the registry as the single integration point now means T3 custom modifiers can register through the same API without special-casing.
  • Discoverability. MODIFIER_REGISTRY.list() produces the full catalog for UI/UX (picker widgets, docs generators, validation hints).

Rejected Alternatives

  • Hardcoded switch/if-else. Adding a new modifier kind would require editing six or more files (schema, engine apply path, hooks, UI, docs, validator). Each edit is an opportunity for drift between layers.
  • Plugin manifest with lazy loading. Overkill for a fixed T1 catalog and incompatible with deterministic module load ordering.