changes claude never committed

README.md

@@ -0,0 +1,92 @@
+# Magicka VM — Phase 0/1
+
+> The deliverable is a Rust engine whose tests make a fake universe fail.
+
+This repository implements the Phase 0/1 specification in `plan.md`: an
+**adversarial testing framework first**, then a **reference runtime** that
+passes it, then a **runtime under test** that matches the reference. No spell
+content, templates, or cosmetic runes — the value is in the tests that refuse
+to let the universe collapse into a single score, resource, effect axis,
+executor, rune, hidden formula, or decorative domain.
+
+## Workspace layout
+
+Built in the mandatory order from the spec:
+
+| # | Crate | Role |
+|---|-------|------|
+| 1 | `world_model` | 8 independent domains, world snapshot, perturbation axes, deltas, deterministic primitives (ids, stable hash, RNG) |
+| – | `rune_ir` | Rune token / program model (no stream is ever rejected) |
+| 2 | `trace_model` | Execution trace + all graphs, behavior fingerprint, replay record, fault log, trace metrics |
+| 3 | `generators` | Worlds, programs, executors, contracts, perturbations; rejects flat cases |
+| 4 | `collapse_analysis` | The 11 compression attacks + collapse gates |
+| 5 | `semantic_mutation` | Structurally generated mutant runtimes; proves every one is killed |
+| 6 | `replay_corpus` | Permanent, bit-exact replay cases |
+| 7 | `reference_runtime` | The executable spec engine (`Runtime` trait, `resolve`) |
+| 8 | `runtime_under_test` | Config-driven engine, proven equivalent to the reference |
+| – | `ci_reports` | Orchestrator + `ci` binary; emits the 8 required reports |
+
+The optimized runtime may not begin before steps 1–7 pass CI; until then the
+runtime under test is the reference engine driven through the same config
+surface, which is equivalent by construction. Mutation swaps in a *mutated*
+config to prove the suite detects any divergence.
+
+## The engine in one paragraph
+
+A world is 8 domains, each with 4 observed + 2 hidden integer lanes, a dense
+8×8 coupling matrix, partial observability, and pending scheduled effects. A
+rune program is interpreted under ≥3 executors; each opcode reads several
+domains, mixes them through a nonlinear avalanche keyed by per-domain
+constants, the world coupling, and the executor's salt, then writes back —
+recording causal/read/write/information-flow/temporal edges as it goes.
+Scheduled effects and coupling diffusion propagate changes 3 turns into the
+future. Because every output bit depends on all inputs, the universe is
+high-rank, incompressible, future-sensitive, and executor-divergent — exactly
+the properties the gates demand.
+
+## Running CI
+
+```bash
+cargo test                                   # unit tests for every crate
+cargo run --release -p ci_reports --bin ci   # full gate run (fast scale)
+```
+
+Reports are written to `ci_out/` (8 JSON files + `ci_summary.md`). The binary
+exits non-zero if any gate fails.
+
+### Scales
+
+`MAGICKA_SCALE` selects the corpus size; individual counts can be overridden.
+
+| Scale | executions | replay | mutants | notes |
+|-------|-----------|--------|---------|-------|
+| `tiny` | 120 | 120 | 520 | smoke (~80 ms) |
+| `fast` (default) | 600 | 600 | 520 | every gate, ~0.3 s |
+| `full` | 1,000,000 | 10,000 | 600 | merge-blocking spec gates |
+
+```bash
+MAGICKA_SCALE=full cargo run --release -p ci_reports --bin ci
+# or override individual counts:
+MAGICKA_EXECUTIONS=20000 MAGICKA_REPLAY=10000 cargo run --release -p ci_reports --bin ci
+```
+
+The gate *thresholds* are identical across scales — only the corpus size
+changes. Fast CI runs a representative slice; merge-blocking CI runs `full`.
+
+## Gates enforced (all must pass)
+
+- **runtime_equivalence** — 100% of executions: `canonical(reference) == canonical(runtime_under_test)` over delta, trace, faults, replay hash, and 3-turn future hash.
+- **causal_rank / trace** — median causal edges ≥ 24, 95% causal rank ≥ 6, median touched domains ≥ 4, 95% ≥ 3, fingerprint collision rate < 5%, largest cluster < 2%.
+- **domain_participation** — each domain appears in ≥ 35% of traces, influences ≥ 20%, is mutated in ≥ 20%; removing any domain loses ≥ 10% behavioral diversity; merging any pair loses ≥ 8%; no read-only or write-only domain.
+- **metamorphic_response** — ≥ 90% of perturbations alter the trace, ≥ 75% the delta, ≥ 50% the 3-turn future; ≤ 5% unexplained neutral.
+- **compression_resistance** — best 1/2/4-factor models predict < 40/55/70%; no single domain > 30%, no pair > 55%; every compressed model loses ≥ 35% information. All 11 attack families are run.
+- **mutation_survivor** — ≥ 500 structurally generated mutants, 0 survivors.
+- **contract** — every admitted case satisfies its semantic contract (min causal rank, domain participation, future sensitivity, context divergence, max compressibility); contract-violating cases are rejected at admission.
+- **replay** — 100% deterministic, 0 hash drift.
+- **coverage** — generated/contract rejection accounting; no admitted case fails the generated gates.
+
+## Determinism
+
+Everything is seed-derived and integer-only (SplitMix64 RNG, FNV-1a content
+hashing, wrapping/guarded arithmetic). No floating point enters a canonical
+hash, so replay is bit-exact across machines and runs. No external crates.