neon-sprawl/docs/decomposition/modules/E7_M4_ContractMissionGenerator.md

# E7.M4 — ContractMissionGenerator

## Summary

| Field | Value |
|--------|--------|
| **Module ID** | E7.M4 |
| **Epic** | [Epic 7 — Quest / Faction](../epics/epic_07_quest_faction.md) |
| **Stage target** | Pre-production |
| **Status** | In Progress — Slice 4 backlog [E7M4-pre-production-backlog.md](../../plans/E7M4-pre-production-backlog.md): **E7M4-01** [NEO-144](https://linear.app/neon-sprawl/issue/NEO-144) → **E7M4-11** [NEO-154](https://linear.app/neon-sprawl/issue/NEO-154). Upstream: E5.M3 **Ready**, E7.M3 **Ready**; E4.M1 zone graph deferred (content-only `zoneDifficultyBand` in Slice 4 v1). |

## Purpose

Semi-procedural repeatable contracts from templates, keyed by zone difficulty ([E4.M1](E4_M1_ZoneGraphAndTravelRules.md)), encounter templates ([E5.M3](E5_M3_EncounterAndRewardTables.md)), and faction state ([E7.M3](E7_M3_FactionReputationLedger.md)).

## Responsibilities

- Emit validated `ContractTemplate` instances from `ContractSeed`; record `ContractOutcome`.

## Key contracts

| Contract | Role |
|----------|------|
| `ContractTemplate` | Parameterized mission skeleton. |
| `ContractSeed` | RNG or daily seed inputs. |
| `ContractOutcome` | Completion and reward linkage. |

## Module dependencies

- **E4.M1** — ZoneGraphAndTravelRules (live zone read deferred; content band in Slice 4 v1).
- **E5.M3** — EncounterAndRewardTables.
- **E7.M3** — FactionReputationLedger.

## Dependents (by design)

- Live ops and content pipelines; validate against economy/parity rules per epic.

## Related implementation slices

Epic 7 **Slice 4** — `contract_issued`, `contract_complete`, reward anomalies. Backlog: [E7M4-pre-production-backlog.md](../../plans/E7M4-pre-production-backlog.md).

## Prototype Slice 4 freeze (E7M4-01)

**One** frozen template; objective **`encounter_clear`** on **`prototype_combat_pocket`**; repeat payout via **`completionRewardBundle`** (separate idempotency from quest + first-time encounter loot).

| `ContractTemplate.id` | `zoneDifficultyBand` | `encounterTemplateId` | `minFactionStanding` | `completionRewardBundle` |
|-----------------------|----------------------|------------------------|----------------------|---------------------------|
| **`prototype_contract_clear_combat_pocket`** | **1** | **`prototype_combat_pocket`** | **`prototype_faction_grid_operators`** **0** | **`scrap_metal_bulk` ×5**; **`salvage`** **15** (`mission_reward`) |

**Band policy (E7M4-07):** band **1** caps — max **10** per item grant, **25** skill XP per grant, **10** rep per grant.

**Idempotency:** `{playerId}:contract_complete:{contractInstanceId}`. **Active cap:** one active contract per player (prototype).

**CI (NEO-144):** `content/contracts/prototype_contract_templates.json` validated by `scripts/validate_content.py` — schema, single-template roster, freeze table, encounter/item/skill/faction cross-refs, band-1 economy caps. Schemas: [`contract-template.schema.json`](../../../content/schemas/contract-template.schema.json), [`contract-seed.schema.json`](../../../content/schemas/contract-seed.schema.json).

**Server load (NEO-145):** host fail-fast load of `content/contracts/*_contract_templates.json` via `ContractTemplateCatalogLoader` + **`IContractTemplateRegistry`** — same E7M4 gates as CI at startup; [server README — Contract template catalog](../../../server/README.md#contract-template-catalog-contentcontracts-neo-145).

**Runtime stores (NEO-146):** per-player **`IContractInstanceStore`** (one active instance) + append-only **`IContractOutcomeStore`**; [server README — Contract instance store](../../../server/README.md#contract-instance-store-neo-146).

**Generator operations (NEO-147):** **`ContractGeneratorOperations.TryIssue`** — template selection, deterministic instance ids, structured deny codes; [server README — Contract generator operations](../../../server/README.md#contract-generator-operations-neo-147).

**Economy validation at issue (NEO-150):** **`ContractEconomyValidation.TryValidateTemplate`** — band caps + reward-bundle cross-refs before persist; deny **`economy_cap_exceeded`** / **`invalid_reward_bundle`**; [server README — Contract generator operations](../../../server/README.md#contract-generator-operations-neo-147).

**Reward parity stub:** prototype band caps enforce Slice 4 policy only. Full [E6.M4](E6_M4_RewardParityEnforcer.md) **`RewardParityMap`** and [E3.M5](E3_M5_EconomyBalancePolicy.md) balance dashboards are deferred.

**Contract reward router (NEO-148):** **`RewardRouterOperations.TryDeliverContractCompletion`** — idempotent contract **`completionRewardBundle`** apply with key **`{playerId}:contract_complete:{contractInstanceId}`**; [server README — Reward router](../../../server/README.md#reward-router-neo-127).

**Contract completion wiring (NEO-149):** **`ContractCompletionOperations.TryCompleteOnEncounterClear`** — encounter clear completes matching active instance + outcome audit; [server README — Contract completion operations](../../../server/README.md#contract-completion-operations-neo-149).

**Contract HTTP (NEO-151):** **`POST …/contracts/issue`** + **`GET …/contracts`** — issue envelope + per-player list with **`encounterTemplateId`** and **`completionRewardSummary`** on completed rows; Bruno `bruno/neon-sprawl-server/contracts/`; [server README — Contract issue HTTP (NEO-151)](../../../server/README.md#contract-issue-http-neo-151), [Per-player contract list HTTP (NEO-151)](../../../server/README.md#per-player-contract-list-http-neo-151); plan [NEO-151](../../plans/NEO-151-implementation-plan.md).

**Contract telemetry hooks (NEO-152):** comment-only **`contract_issued`**, **`contract_complete`**, and **`reward_anomaly`** anchor sites in generator/completion ops + shared reward router rollback; [server README — Contract telemetry hooks (NEO-152)](../../../server/README.md#contract-telemetry-hooks-neo-152); plan [NEO-152](../../plans/NEO-152-implementation-plan.md).

**Contract client HUD (NEO-153):** **`contract_client.gd`**, **`contract_hud_controller.gd`**, **`ContractActiveLabel`** / **`ContractIssueFeedbackLabel`** / **`ContractRewardDeliveryLabel`** — **Shift+C** prototype issue, encounter objective display, completion reward transition; [client README — Contract issue + progress HUD (NEO-153)](../../../client/README.md#contract-issue--progress-hud-neo-153); [`NEO-153` manual QA](../../manual-qa/NEO-153.md); plan [NEO-153](../../plans/NEO-153-implementation-plan.md).

## Source anchors

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