emulator

# Emulator ## Mission `$emulator` owns one content-addressed contract closure containing total synthetic worlds and partial session-derived charts. ```text source evidence or explicit design -> emulator-spec.yaml closure -> environment charts -> fresh actor runs -> hard oracles, state diffs, traces, and eligible datasets ``` A historical session is a partial transition witness, not a complete simulator, expert demonstration, or baseline arm. Historical evidence discovers what to challenge; fresh executions decide whether a harness candidate wins. Use `$grill-me` only when a material human judgment cannot be resolved from evidence. Do not introduce a native CLI, protocol service, or persistent store. ## Activation boundary Use `$emulator` to: ```text author a contract from a repository, spec, tests, traces, sessions, or design compile correction windows into normative decision charts reconstruct resettable tasks as executable episode charts preserve useful but non-selecting evidence as observational charts run total synthetic or honest partial environments compare fresh baseline and factor-local candidate harnesses export EER-v1, preference rows, fresh trajectories, or curriculum rows ``` Do not use it for: ```text physical session facts -> Seq owns discovery, identity, order, and tool facts material user choices -> $grill-me automatic target-skill or live-harness edits historical-trace imitation or private chain-of-thought reconstruction model-generated transitions presented as source-faithful history ``` ## Request Prefer: ```yaml emulator_request: mode: design | implement | run | mutate | compare | export source: kind: session | session_corpus | repository | specification | tests | traces | user_design | existing_contract | mixed session_id: session_path: root: repo: since: until: revision: fingerprint: evidence_refs: [] contract_path: target: name: kind: agentic_harness | skill | agent_loop | tool_loop | workflow | library_protocol atlas: atlas_id: root: chart_kinds: [normative_decision, executable_episode, observational] partitions: discovery: development: holdout: experiment: factor: baseline_harness: candidates: [] max_candidates: 3 authorized_files: allowed: [] forbidden: [] output: report: EER-v1 preferences: false trajectories: false curriculum: false ``` Session-derived atlases default to `${CODEX_HOME:-$HOME/.codex}/emulators/<atlas-id>/`; shareable designed environments may use `codex/emulators/<target>/`. Do not create empty scaffolding or commit session artifacts without explicit sanitization and authority. ## Modes Choose exactly one mode. ### design Compile or repair the root contract and its charts. Do not generate runtime files unless the requested artifact is itself an actor packet or evaluator. ### implement Materialize executable world, reset, tool, fixture, and evaluator assets already authorized by the contract. Do not edit source repositories or target skills without separate authority. ### run Execute one frozen harness against selected charts. Capture only fresh runtime observations, actions, effects, terminal state, cost, and trace. ### mutate Apply only chart-declared mutations. A mutation outside declared support creates a new designed chart; it never becomes a source-faithful transition. ### compare Run fresh baseline and candidate arms against the same chart boundary and emit a chart-aware comparison. The historical trajectory is never an arm. ### export Emit EER-v1 and only datasets whose fresh evidence, authority, partition, and visibility rules make them eligible. ## Contract ownership One normative content-addressed contract closure is rooted at `emulator-spec.yaml`. The root fingerprint is SHA-256 of its exact UTF-8 bytes. Each chart is bound by exact bytes, and each chart recursively binds every execution-relevant external source map, actor input, world/reset recipe, fixture, tool manifest, and evaluator asset by exact SHA-256. A referenced artifact that is missing or mismatched makes the environment invalid. The contract declares `source_faithful`, `designed`, or `mixed` origin. Every normative rule, permission, side-effect boundary, evaluator, terminal condition, reward, and mutation dimension cites its authority. Assumptions cannot define safety, authority, hidden truth, side effects, selection, or termination. Read `references/emulator-contract-profile.md` when authoring or validating a contract. Read `references/session-derived-atlas.md` whenever a session source is selected. ## Environment laws Every chart exposes semantic equivalents of: ```text reset(chart_id, harness_id, repeat_id) -> observation observe() -> current actor-visible observation support(action) -> executable | judgeable | denied | observed_only | unsupported evaluate(output_or_trace) -> oracle vector + state diff + residual judgment trace() -> fresh observable trace ``` `step(action)` exists only when `support(action) == executable`. Support classes are mutually exclusive. An overlap or unverifiable classification is `invalid_environment`; an attempted `observed_only` or `unsupported` transition is `unsupported_counterfactual`; a `denied` action is `hard_fail`. Never guess a next state. Actor-visible and evaluator-only projections are separate. Selection and training additionally require an actor-readable inventory and fingerprint plus tool-access evidence proving hidden roots were inaccessible. A combined file is not proof of separation. A failed hard oracle or trace invariant cannot be overridden by reward, cost, preference, prose quality, or model judgment. Executable charts judge required state and trace laws, not historical tool-sequence imitation. ## Session-derived execution Seq owns physical session discovery and exact source-event facts. `$emulator` owns source bundles, cuts, chart classification, support, evaluator authority, fresh comparison, claims, exports, and STOP decisions. CAS or the selected existing runner owns fresh actor execution facts; Git and task tools own reset and state assertions. For correction charts, cut immediately before the disputed historical action. Give the actor only facts legitimately available at that cut. Hide the action, later correction, recovery, tests, review, final answer, labels, and holdout evaluator details. Whole-harness executable comparisons cut before the first assistant action unless earlier influence is proved absent. All charts may support discovery. Only environment-valid fresh paired charts with sufficient attribution, transition support, evaluator authority, and untouched holdout status may select a candidate. Group all charts from the same root session, task, issue, PR, or worker lineage into one partition. Read `references/session-derived-atlas.md` for source extraction, correction and executable compilation, leakage checks, harness manifests, partitions, fresh execution, evaluation, exports, and stop reasons. ## Comparison and learning policy Freeze the baseline and each candidate as complete harness manifests. A candidate changes exactly one semantic owner and cannot change charts, source bundles, reset recipes, evaluators, comparison code, actor runner, or holdout partitioning. Candidate generation cannot inspect active holdout material. Evaluate in this order: ```text environment validity -> support -> hard oracles -> state diff -> trace laws -> protected dimensions -> cost/latency -> residual judgment ``` Recommendations are `adopt`, `reject`, or `insufficient_evidence`, but they grant no mutation authority. Export preference rows only from direct authority and a fresh passing chosen action. Export trajectories only from fresh valid executable runs. Active holdouts never enter training exports. Read `references/eer-v1.md` for run accounting and comparison artifacts. Read `references/synthetic-implementations.md` when generating designed worlds. ## Output ```text Emulated: - Source, origin, and limitations: - Contract closure and fingerprints: - Charts, groups, partitions, and support: - Baseline, candidate, factor, and fresh runs: Run summary: - Valid / passed / hard-failed / ambiguous: - Invalid environment / unsupported / runtime error / skipped: Findings: - Hard-oracle and state deltas: - Protected regressions: - Residual preference: - Recommendation: adopt | reject | insufficient_evidence Artifacts: - Source bundles, actors, worlds, traces, reports, and eligible datasets: Next route: - none | repair-contract | reconstruct-world | choose-factor | separately-authorize-adoption ``` ## Hard rules - Historical sessions are sources, never baseline arms or expert labels. - Preserve exact source provenance, content-addressed closure, and source order. - Keep actor and evaluator projections separate and prove actor-readable roots. - Keep support classes exclusive; never totalize an unknown transition. - `reset`, `observe`, `support`, `evaluate`, and `trace` are universal; `step` is not. - All charts may discover; only eligible fresh charts may select. - Use one semantic factor per candidate and freeze it before holdout execution. - Keep active holdouts out of candidate generation and training exports. - Hard oracles and protected dimensions dominate preferences and scalar scores. - Stop on leakage, drift, missing authority, unsupported transitions, or irreconstructable state. - Never mutate the live harness or publish private data without separate authority. - Do not add a native subsystem before repeated real charts prove a general capability gap.