# E7.M1 — QuestStateMachine

## Summary

| Field | Value |
|--------|--------|
| **Module ID** | E7.M1 |
| **Epic** | [Epic 7 — Quest / Faction](../epics/epic_07_quest_faction.md) |
| **Stage target** | Prototype |
| **Status** | Planned (see [dependency register](module_dependency_register.md)) |

## Purpose

Data-driven quest lifecycle: start, step progression, branching, failure/reset, and completion with durable persistence. Integrates crafting and combat outcomes so guided content ties together gather–craft–combat loops without duplicate rewards.

## Responsibilities

- Load and interpret `QuestDef`; track `QuestStepState` per player (or party scope as designed).
- Apply `QuestStateTransition` rules for advance, abandon, fail, and complete.
- Invoke or subscribe to [E3.M2](E3_M2_RefinementAndRecipeExecution.md) and [E5.M1](E5_M1_CombatRulesEngine.md) (or their events) for step completion predicates.

## Key contracts

| Contract | Role |
|----------|------|
| `QuestDef` | Steps, prerequisites, objectives, and branching metadata. |
| `QuestStepState` | Current step progress and internal flags. |
| `QuestStateTransition` | Valid transitions and side effects (before E7.M2 reward routing). |

## Module dependencies

- **E3.M2** — RefinementAndRecipeExecution: craft completion, item hand-ins, refine steps.
- **E5.M1** — CombatRulesEngine: defeat objectives, encounter-linked steps.

## Dependents (by design)

- **E7.M2** — [RewardAndUnlockRouter](E7_M2_RewardAndUnlockRouter.md): idempotent delivery after completion.
- **E7.M3** — [FactionReputationLedger](E7_M3_FactionReputationLedger.md): reputation-gated content (pre-production).
- **E5.M3** — [EncounterAndRewardTables](E5_M3_EncounterAndRewardTables.md): encounter completion and quest credit.
- **E6.M4** — [RewardParityEnforcer](E6_M4_RewardParityEnforcer.md): quest/PvP reward alignment.

## Related implementation slices

See Epic 7 **Slice 1 — Quest core and persistence**: 3–5 onboarding quests plus one chain across gather/craft/combat; telemetry `quest_start`, `quest_step_complete`, `quest_complete`, funnel times.

## Risks and telemetry

- Scripting weight: keep `QuestDef` data-first; templates in decomposition/tooling path per epic.
- Double-claim: design for idempotency before E7.M2; lint bundles vs E6.M4 / E3.M5.

## Source anchors

- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 7.
- [Module dependency register](module_dependency_register.md)