magicka-vm/README.md

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.

Compliance model

No gate may pass from configuration, naming, shared implementation, smoke-scale runs, regenerated expectations, proxy metrics, a default profile, or a locally-runnable binary. A gate passes only from persisted, independently reproducible, full-scale adversarial evidence enforced at merge. Every acceptance obligation has all four of: a measured artifact, a provenance chain to the run that produced it, a merge-blocking enforcement point, and a failure condition if the artifact or provenance is absent.

• The merge-blocking enforcement point is .github/workflows/merge-gates.yml, whose merge-gates job runs MAGICKA_PROFILE=merge (full gates) and must be a required status check on the protected branch / merge queue. It is not a local binary, and the fast profile is advisory only — it can never stand in for acceptance.
• compliance_report.json enumerates every obligation, its artifact, its floor, the actual measured value, and whether the artifact is present. A missing required report fails acceptance.
• The merge floors (50k worlds, 250k programs, 1,000,000 executions, 10 perturbations/exec, 100% reference/runtime comparison over base and perturbations, 500 mutants, 10,000 replay cases) cannot be lowered by environment overrides: a lowering override is recorded as a provenance failure and the floor is kept.

Every gate is built to be able to fail, and a negative-control test proves it does:

Gate	How it is made unbypassable	Negative control proving it can fail
runtime_equivalence	Compares two independent implementations (the reference engine vs. runtime_under_test::native, which never calls the reference engine)	buggy_runtime_is_rejected — a runtime with one dropped causal edge is caught
compression_resistance	Attacks operate on the real serialized trace (causal influence, info-flow, access, temporal, deltas), not a hash proxy; info loss is genuine unexplained variance	single_factor_corpus_is_rejected — a rank-1 universe is rejected
mutation_survivor	Each mutant must fail the named gate it targets, not merely differ from the reference	reference_passes_every_named_gate + no_mutant_survives_its_named_gate
replay	Expectations are loaded from a committed file, not regenerated in the same run	corrupted_expectation_is_detected
domain_participation	Decorative/redundant domains are flagged directly	decorative_domain_is_rejected
merge scale floor	Env overrides may only raise merge counts; a lowering attempt is recorded and the floor kept; executions actually performed are counted	merge_floor_cannot_be_lowered_by_override, merge_profile_at_smoke_scale_is_rejected
100% comparison	Reference vs. runtime-under-test compared for every execution — base and all perturbations, never base only	runtime_equivalence gate fails unless equiv_total == base + perturbations
provenance	A Merkle root over per-execution records, plus independent engine identities, binds reported numbers to executed work	merkle_root_binds_to_leaves

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 over real trace structure + collapse gates
5	semantic_mutation	Structurally generated mutant runtimes; proves every one fails its named gate
6	replay_corpus	Permanent, bit-exact replay cases persisted to corpus/replay_corpus.tsv
7	reference_runtime	The executable spec engine (Runtime trait, resolve)
8	runtime_under_test	An independent interpreter (native) proven equivalent to the reference
–	ci_reports	Orchestrator + ci binary; emits 8 gate reports + a provenance report

The runtime under test does not call the reference engine. It re-derives the canonical behavior from the spec in a different code organization, so 100% agreement is evidence the spec is implemented correctly rather than a tautology. (native_matches_reference_bit_for_bit checks this over a 2000-seed sweep.)

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.

Running CI

cargo test                                          # unit tests + negative controls
MAGICKA_PROFILE=fast  cargo run --release -p ci_reports --bin ci   # advisory PR slice
MAGICKA_PROFILE=merge cargo run --release -p ci_reports --bin ci   # acceptance (full gates)

Reports are written to the output dir (8 gate reports + provenance_report.json

• compliance_report.json + ci_summary.md). The binary exits non-zero if any gate fails or any required artifact is absent.

Profiles

MAGICKA_PROFILE (or MAGICKA_SCALE) selects the run profile.

Profile	executions	replay	mutants	role
fast (default)	600	10,000 (committed)	520	advisory only — never acceptance
tiny	120	10,000	520	smoke
merge (MAGICKA_SCALE=full)	1,000,000	10,000	600	acceptance — hard floors

The fast/tiny profiles print ADVISORY … NOT a merge-blocking acceptance run and are labelled non-acceptance in compliance_report.json. Acceptance comes only from the merge profile, run by the merge-gates workflow. The merge floors cannot be lowered by environment overrides (a lowering override is recorded as a provenance failure and the floor kept).

Merge-blocking enforcement (required check)

.github/workflows/merge-gates.yml defines the enforcement point. Configure branch protection / the merge queue to require the merge-gates job. That job runs the full merge profile, verifies the committed corpus has ≥10,000 cases, and fails if any required artifact is missing. The full run executes ~1M base executions × (1 base + 10 perturbations) with 100% reference/runtime comparison; it completes in minutes on a CI runner.

Replay corpus

The replay corpus is committed at crates/replay_corpus/corpus/replay_corpus.tsv (10,000 cases). Replay loads those expectations and re-executes the reference, so any engine change that alters a hash makes the committed file and the fresh run disagree and CI fails. Regenerate it only as a deliberate, reviewed migration:

cargo run --release -p replay_corpus --bin freeze -- 10000

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.