<?xml version="1.0" encoding="UTF-8"?>
<spec xmlns="https://vibevm.org/spec/1">
  <title id="root">CARD: scaffold-h-simulators — Local Simulators / Reference Models (Go)</title>
  <status stage="spec" state="done"/>
  <p p="1"><fact id="status-line" status="impl/done">**Discipline v0.2 · BETA · T2 · Go**</fact></p>
  <section id="band-one-identity" title="Band 1 — Identity &amp; Recognition">
    <p p="2"><fact id="CLASSIFICATION" status="impl/done">Classification: layer=E (verification) + H (weak-reader); mechanism=scaffold H.</fact></p>
    <p p="3"><fact id="INTENT" status="impl/done">Intent: Ship a small runnable model of a subsystem's behavior the reader can EXECUTE to understand or predict — offloading the execution-prediction that weak models fail at, without running the whole system. Go's test culture already lives here: small interfaces make hand-rolled in-memory fakes one-screen literals, and `httptest` is a stdlib network simulator.</fact></p>
    <p p="4"><fact id="ALSO-KNOWN-AS" status="spec/done">Also Known As: reference implementation; in-memory fake; executable spec; oracle model; test double; `httptest` server; steppable model.</fact></p>
    <p p="5"><fact id="APPLICABILITY-RECOGNITION" status="impl/done">Applicability / Recognition: Apply when — a subsystem has non-obvious dynamics (a reconcile loop, a state machine, a retry/backoff protocol); understanding requires mentally simulating execution; an external dependency (HTTP, a store, a queue) must be reasoned about offline. *Detector seed:* a subsystem whose behavior is documented in prose-describing-execution, with no runnable model or fake → recognition fires (execution-prediction is weak models' weakest point — DR2-019, CRUXEval ~63% even for strong models).</fact></p>
  </section>
  <section id="band-two-justification" title="Band 2 — Justification &amp; Tradeoffs">
    <p p="6"><fact id="MOTIVATION" status="spec/done">Motivation: A weak agent must modify the reconciler's convergence loop (diff → actions → apply → re-diff). It cannot mentally simulate whether a partial apply converges or oscillates. A steppable in-memory world — `sim.World` with `Step()` returning the applied actions and the next state — replaces mental simulation with execution: feed a desired/actual pair, watch convergence, print the trace. The EsoLang library shipped exactly this idea (a local simulator) and it carried the weak-agent gain.</fact></p>
    <p p="7"><fact id="STRUCTURE-AND-PARTICIPANTS" status="impl/done">Structure &amp; Participants: *Reference model* (runnable, small, steppable — `Step()`/`State()` inspection surface) · *In-memory fake* (a literal implementation of the seam's narrow interface — Go's native double) · *`httptest` server* (the stdlib simulator for HTTP boundaries) · *Conformance test* (model vs production agree on representative inputs).</fact></p>
    <p p="8"><fact id="COLLABORATIONS" status="impl/done">Collaborations: Provides the comparator for Class D oracles (the model IS the expected-behavior source); backs Class C contracts; pairs with Class G (the model's usage is Example-demonstrated). Capability injection (§2) is what makes fakes drop-in — a cell taking `seams.Store` accepts the ten-line map-backed fake with no mocking framework.</fact></p>
    <p p="9"><fact id="GOALS-AND-NON-GOALS" status="impl/done">Goals / Non-Goals: *Goals:* make non-obvious dynamics executable, not just described. *Non-Goals:* NOT a second production implementation (a reference model, kept simple); NOT for trivially-obvious subsystems; NOT reflection-based mock generation (gomock-class module-graph interception is the §7 posture — literal fakes are cheaper and honest).</fact></p>
    <p p="10"><fact id="CONSEQUENCES" status="spec/done">Consequences: (+) the reader runs instead of simulates; (+) doubles as a Class D comparator and the test fixture; (+) zero third-party cost — interfaces + httptest are stdlib culture. (−) a model is code to keep in sync — conformance-test it against production; (−) over-modeling wastes effort — only non-obvious dynamics.</fact></p>
    <p p="11"><fact id="ALTERNATIVES" status="spec/done">Alternatives: prose describing behavior (weak readers can't execute prose); reading the production code directly (the thing too complex to simulate). The model is the offload.</fact></p>
    <p p="12"><fact id="RISKS-AND-ASSUMPTIONS" status="spec/done">Risks &amp; Assumptions: assumes the subsystem's behavior is modelable simply; a model that drifts from production misleads — conformance-test it. *Sunset:* if the production code becomes simple enough to read directly, the model retires.</fact></p>
    <p p="13"><fact id="EVIDENCE-AND-TRANSFER-STRENGTH" status="spec/done">Evidence &amp; Transfer-strength: R2C-008 (simulator in the transformative library, benchmark), DR2-019 (execution-prediction weakness, benchmark). Class: benchmark. Tag: **[E-strong]**.</fact></p>
  </section>
  <section id="band-three-operation" title="Band 3 — Operation">
    <fence lang="card-ops" p="14">trigger: WHEN a subsystem with non-obvious dynamics has no runnable reference model or fake THEN apply
mode: gate
routine:
  1. Identify the dynamics a reader must predict (states, transitions, convergence).
  2. Write a small steppable reference model (Step()/State() inspection surface).
  3. Provide literal in-memory fakes for the seam's capabilities (map-backed store, fixed clock); use httptest for HTTP boundaries.
  4. Add a conformance test: model vs production agree on representative inputs.
  5. Demonstrate the model's usage with an Example (Class G).
checker: conform `nonobvious-subsystem-has-model` + model-vs-production conformance test (go test)
raid_role: layer=cells; order=after:contracts; batch=cell
budget: active_rules=1; first_signal=conformance test (&lt;60s)</fence>
  </section>
</spec>
