game-system

name	game-system
description	Workflow and checks for adding a new game system
user-invocable	true

Adding a New Game System

Use docs/architecture/game-systems.md for the comprehensive guide, checklist, and Daggerheart reference implementation.

Quick-start workflow

1. Start at manifest.go — open internal/services/game/domain/systems/manifest/manifest.go first. It shows all three registry surfaces (BuildModule, BuildMetadataSystem, BuildAdapter) wired from one SystemDescriptor. Read an existing entry (Daggerheart) to understand the shape, then add yours.

2. Pick the right DecideFunc helper — see the decision tree in docs/architecture/game-systems.md under "DecideFunc decision tree":

   • DecideFunc[P] — no state needed, same payload for command/event
   • DecideFuncWithState[S, P] — needs state for validation
   • DecideFuncTransform[S, PIn, POut] — event payload differs from command
   • Raw Decide switch — multi-event or custom routing

3. Follow the numbered steps in docs/architecture/game-systems.md § "Adding a new system (current flow)" (steps 1–10).

4. Run conformance tests after wiring:

   go test ./internal/services/game/domain/module/testkit/...
   

   testkit.ValidateSystemConformance composes all startup validators for module + adapter pairs and fails loudly on missing registrations.

5. Run full verification:

   make test          # unit tests
   make smoke         # quick gRPC + scenario confidence
   make check         # required before opening or updating a PR
   

Testing guardrails

• Prefer contract tests for new system behavior; avoid preserving tests that only assert removed mechanics stay absent.
• Negative assertions require an adjacent Invariant: rationale.

Startup validator troubleshooting

Validator	What it checks	Fix
ValidateDeciderCommandCoverage	Every registered system command has a decider case	Add missing command type to decider's DeciderHandledCommands() and Decide()
ValidateSystemFoldCoverage	Every emittable event with replay intent has a fold handler	Register a HandleFold for the missing event type
ValidateAdapterEventCoverage	Every emittable event with projection intent has an adapter handler	Register a HandleAdapter for the missing event type
ValidateCommandTypeNamespace	System command types match sys.<system_id>.*	Fix the command type constant string
ValidateEventTypeNamespace	System event types match sys.<system_id>.*	Fix the event type constant string

Key reference files

Concern	Location
Manifest registry	domain/systems/manifest/manifest.go
Module interface	domain/module/registry.go
Adapter interface	domain/systems/adapter_registry.go
ProfileAdapter	domain/systems/adapter_registry.go
DecideFunc helpers	domain/module/decide_func.go
FoldRouter	domain/module/fold_router.go
Conformance tests	domain/module/testkit/
Daggerheart example	domain/systems/daggerheart/