# Magical-Law Progression Tasks v0.2

## M1: Prototype portal matter exchange

**Description:** Build a headless and minimal visual toy where 100 mass units form a seeded result bag, outputs arrive in shuffled order, anchors bias the distribution, and throughput raises entropy.

**Acceptance criteria:**

- [ ] The UI shows expected output ranges before a batch starts.
- [ ] Stable, anchored, and high-entropy modes create different useful tradeoffs.
- [ ] Every residue/anomaly has a recovery route; no required item relies on a sub-5% roll.

**Verification:**

- [ ] Same seed/input/calibration produces the same bag and state hash.
- [ ] Save/load mid-bag preserves remaining outputs and cannot reroll.
- [ ] One million simulated batches stay inside configured mass and probability bounds.

**Dependencies:** None

**Files likely touched:**

- `src/simulation/result_bag.gd`
- `src/simulation/portal_exchange.gd`
- `tests/portal_exchange_smoke.gd`
- `scenes/labs/portal_exchange_lab.tscn`

**Estimated scope:** Medium

## M2: Define biome laws and boundaries

**Description:** Add data contracts for zone membership, boundary nodes, law state, failure/recovery, and law-specific machine modifiers without coupling them to rendered terrain.

**Acceptance criteria:**

- [ ] Forest balance, undead decay, ember temperature, mirror entropy, and rift instability use the same lifecycle interface.
- [ ] Boundary crossings are explicit graph edges that can be opened and closed deterministically.
- [ ] Existing entities outside a special zone retain current behavior.

**Verification:**

- [ ] Unit fixtures enter/leave each law and report exact state changes.
- [ ] Closing a crossing never deletes in-flight inventory.
- [ ] Sleeping entities do not wake every tick only because they occupy a special zone.

**Dependencies:** None

**Files likely touched:**

- `src/simulation/biome_law.gd`
- `src/simulation/biome_registry.gd`
- `src/simulation/boundary_network.gd`
- `tests/biome_law_smoke.gd`

**Estimated scope:** Medium

## M3: Encode and validate the v0.2 progression

**Description:** Turn `docs/tech-tree-nodes-v0.2.csv` into typed runtime data and validate prerequisites, roles, proof types, boundary unlocks, experiment requirements, and recovery paths.

**Acceptance criteria:**

- [ ] All 80 records load under stable IDs.
- [ ] M nodes never depend on C/POST/INFINITE nodes.
- [ ] Mainline totals equal K 10,780; L 9,580; D 9,580; E 8,150; S 6,200.

**Verification:**

- [ ] Invalid fixtures cover duplicate IDs, missing prerequisites, cycles, invalid proof types, and missing recovery.
- [ ] The computed G09 closure contains inscription, life, death, element, dimension, and portal tags.
- [ ] Existing simulation smoke tests remain green.

**Dependencies:** M2

**Files likely touched:**

- `src/data/technology_definition.gd`
- `src/data/technology_catalog.gd`
- `src/data/technology_catalog.tres`
- `tests/technology_catalog_smoke.gd`

**Estimated scope:** Medium

## M4: Implement experiment-driven research

**Description:** Consume physical proof items only after their experiment state sequence has completed, then support queues, parallel archives, progress inspection, and exact save/load.

**Acceptance criteria:**

- [ ] Each proof records which law experiment validated it.
- [ ] Archives consume exact proof sets and never duplicate the final unit under parallel completion.
- [ ] UI explains whether the bottleneck is proof validity, input, archive capacity, or prerequisite state.

**Verification:**

- [ ] Disconnect/reconnect preserves partial experiment and research progress.
- [ ] Save/load fingerprints match uninterrupted execution.
- [ ] Invalid hand-spawned blanks cannot satisfy a proof requirement.

**Dependencies:** M3

**Files likely touched:**

- `src/simulation/research_system.gd`
- `src/simulation/proof_experiment.gd`
- `src/ui/research_screen.gd`
- `tests/research_proof_smoke.gd`

**Estimated scope:** Medium

## M5: Deliver the runic opening

**Description:** Map the current prototype into B00–K11, then add ordered inscription, mana-frequency splitting, rune adjacency, clay constructs, and boundary surveying.

**Acceptance criteria:**

- [ ] A fresh run produces K automatically and discovers both external-zone crossings.
- [ ] A wrong inscription order returns a reusable blank with a readable diagnosis.
- [ ] Rune templates change at least one recipe and one efficiency property.

**Verification:**

- [ ] Automated flow reaches K11 without debug items.
- [ ] Existing belt/mana/bridge deterministic tests pass.
- [ ] A stripped-art test distinguishes ordinary routing from ordered inscription.

**Dependencies:** M4

**Files likely touched:**

- `src/data/era_runic_content.tres`
- `src/simulation/rune_array.gd`
- `src/simulation/objective_system.gd`
- `tests/era_runic_flow_smoke.gd`

**Estimated scope:** Medium

## M6: Deliver forest and undead zones

**Description:** Implement regenerative growth/ecology balance and timed decay/memory recovery as two order-independent vertical slices with their own crossings and proof lines.

**Acceptance criteria:**

- [ ] Either zone can be completed first from the same K11 save.
- [ ] Overharvest produces recoverable blight; mist decay produces recoverable bone dust.
- [ ] L and D proofs are continuously automatable through their actual law loops.

**Verification:**

- [ ] Life-first and death-first runs both reach L08+D08 with matching mainline totals.
- [ ] Ecology and identity conservation tests pass under backpressure.
- [ ] Starting-zone blueprints visibly fail until adapted to each local law.

**Dependencies:** M5

**Files likely touched:**

- `src/data/era_life_death_content.tres`
- `src/simulation/growth_cycle.gd`
- `src/simulation/decay_identity.gd`
- `tests/era_life_death_flow_smoke.gd`

**Estimated scope:** Medium

## M7: Deliver ember-state production

**Description:** Merge the two anchor laws, open a protected ember crossing, and automate temperature/state cycling through E08.

**Acceptance criteria:**

- [ ] Heat can accelerate production but unsafe heat only pauses and yields recoverable slag.
- [ ] One medium completes cold, molten, and charged states to produce E.
- [ ] Dragon glass requires the state loop rather than a conventional one-step furnace recipe.

**Verification:**

- [ ] Automated mandatory flow reaches E08 without optional fire spirits.
- [ ] Energy and material conservation hold across state transitions.
- [ ] Cooling loss and reheating wake only affected networks.

**Dependencies:** M6

**Files likely touched:**

- `src/data/era_ember_content.tres`
- `src/simulation/thermal_network.gd`
- `src/simulation/item_state.gd`
- `tests/era_ember_flow_smoke.gd`

**Estimated scope:** Medium

## M8: Deliver mirror folding and identity

**Description:** Add paired spatial endpoints, echo sampling, bounded probabilistic duplication, shadow-matter separation, and identity anchoring through S08.

**Acceptance criteria:**

- [ ] Unnamed paths loop or misroute predictably; named endpoint pairs are deterministic.
- [ ] Probability UI shows batch ranges before S05-dependent processes start.
- [ ] Real and echo items can be sorted and both have useful recovery recipes.

**Verification:**

- [ ] Automated flow reaches S08 without optional mirror multiplication.
- [ ] Seeded result bags reproduce exactly across frame rates and reloads.
- [ ] No mainline item depends on a rare random output.

**Dependencies:** M1, M7

**Files likely touched:**

- `src/data/era_mirror_content.tres`
- `src/simulation/fold_network.gd`
- `src/simulation/item_identity.gd`
- `tests/era_mirror_flow_smoke.gd`

**Estimated scope:** Medium

## M9: Deliver the first-warp victory

**Description:** Build the rift site, twelve ring stones, four anchors, beat-synchronized material batches, four-frequency power window, entropy safety, walker construct, and both time achievements.

**Acceptance criteria:**

- [ ] Researching G09 cannot win the game by itself.
- [ ] First warp succeeds deterministically once all displayed ritual conditions hold.
- [ ] The achievement timestamp is the simulation frame on which the walker crosses.

**Verification:**

- [ ] Boundary tests cover 07:59:59/08:00:00 and 23:59:59/24:00:00.
- [ ] Save/load during ring construction, batch ritual, power window, and crossing preserves exact state.
- [ ] A full mainline test contains all five law demonstrations and no C dependency.

**Dependencies:** M8

**Files likely touched:**

- `src/data/era_portal_content.tres`
- `src/simulation/grand_ritual.gd`
- `src/simulation/achievement_clock.gd`
- `tests/first_warp_flow_smoke.gd`

**Estimated scope:** Medium

## M10: Deliver the postgame portal economy

**Description:** Connect the proven exchange toy to the opened campaign gate, add paradox proofs, ecological tuning, destinations, causal locks, relics, exact targeting, multiple gates, and repeatable research.

**Acceptance criteria:**

- [ ] Basic random exchange is usable immediately after victory.
- [ ] The player can trade gathering pressure for sorting/entropy work but cannot outperform local basic-resource loops in every dimension.
- [ ] Entropy bands create recoverable opportunities rather than arbitrary destruction.

**Verification:**

- [ ] Reference factories demonstrate unfocused, ecological, and true-name strategies.
- [ ] Every X/I node calculates deterministic cost and survives save migration.
- [ ] A portal-only economy cannot remain self-sustaining without external mana/catalyst input.

**Dependencies:** M9

**Files likely touched:**

- `src/data/postgame_portal_content.tres`
- `src/simulation/portal_exchange.gd`
- `src/simulation/paradox_research.gd`
- `tests/postgame_portal_smoke.gd`

**Estimated scope:** Medium

## M11: Prove 8/24-hour pacing and magical identity

**Description:** Record progression and law-specific failure metrics, run structured expert and first-play tests, and tune without removing the mandatory magical demonstrations.

**Acceptance criteria:**

- [ ] Telemetry records first proof, zone entry, anchor, gate stage, failure/recovery, and warp timestamps.
- [ ] Target percentiles meet 8/24 hours on standard topology seeds.
- [ ] At least 80% of testers can explain why one machine stopped in each ecology zone.

**Verification:**

- [ ] Report includes at least three rehearsed expert runs and eight experienced first-play runs.
- [ ] Cost simulator matches actual consumed proofs and final inventories.
- [ ] Stripped-art test distinguishes every ecology zone by rules alone.

**Dependencies:** M9, M10

**Files likely touched:**

- `src/telemetry/progression_metrics.gd`
- `tools/progression_report.gd`
- `tests/progression_benchmark_smoke.gd`
- `artifacts/progression-benchmark-v0.2.md`

**Estimated scope:** Medium