# Evidence pipeline This package is the experiment/evidence layer. The pre-prototype executors in `experiments.executors` adapt immutable trial records to H1 retargeting, H2 synthetic sensitivity, and H3/H4 rigid-body simulation backends. ## Minimal workflow From the repository root with `PYTHONPATH=code`: ```bash python -m experiments.cli plan \ --spec code/config/experiments/h1_smoke.json \ --output /tmp/h1-plan.json python -m experiments.cli run \ --plan /tmp/h1-plan.json \ --batch-dir output/experiments/h1-smoke \ --executor experiments.executors:execute_h1_retargeting ``` Available executor/config pairs are: ```text execute_h1_retargeting h1_smoke.json / h1_calibration.json execute_h2_synthetic h2_smoke.json / h2_calibration.json execute_bilateral_simulation smoke.json / bilateral_calibration.json ``` Auditable second-stage calibration specifications are: ```text execute_h1_retargeting h1_calibration_v2.json execute_h2_synthetic h2_calibration_v2.json execute_bilateral_simulation bilateral_calibration_v2_energy.json execute_bilateral_simulation bilateral_calibration_v2_network.json ``` The v3 redesign separates branch-crossing evidence from contact/energy stress: ```text execute_h1_retargeting h1_calibration_v3.json execute_bilateral_simulation bilateral_calibration_v3_stable_contact.json execute_bilateral_simulation bilateral_calibration_v3_energy_challenge.json execute_bilateral_simulation bilateral_network_v3_screening.json ``` `h1_calibration_v3.json` is a deterministic branch-regression fixture, not statistical tail-latency evidence. The bilateral v3 stable grid uses three exogenous seed groups shared across haptic gains. The synthetic energy challenge shares the corresponding `k=3200 N/m` groups, is explicitly ineligible for H3, and must be analyzed only with its H4/challenge metric configuration. The v3 Stage-B network screen freezes the selected Stage-A mechanics and haptic settings. Within every trajectory/replicate block, it pairs nominal, symmetric-delay, asymmetric-delay, jitter, and packet-loss profiles with common random numbers. Its metrics distinguish packet availability from freshness and compare delayed control references with within-trial transport shadows. Those shadows retain the disturbed system state; the paired nominal trial remains the causal network baseline. Disjoint-root locked v3 specifications are: ```text execute_bilateral_simulation bilateral_locked_v3_stable_contact.json execute_bilateral_simulation bilateral_locked_v3_energy_challenge.json execute_bilateral_simulation bilateral_network_v3_locked.json ``` The network locked study contains only the proposed method. It can test bounded robustness under the registered emulator, but cannot establish superiority over mapping baselines. The older `bilateral_calibration_v2_network.json` remains a historical placeholder and must not be used as a confirmatory Stage-B protocol. An executor callable receives one immutable trial mapping and returns: ```python TrialPayload( samples={"time": time_array, "...": sample_array}, events=[{"sample_index": 10, "event": "contact"}], metadata={"backend": "simulation"}, ) ``` Every sample array must have the same first dimension. Object arrays are rejected. Successful trials are committed by one atomic directory rename; failures are retained separately and may be retried with `--resume`. Validate a completed batch: ```bash python -m experiments.cli validate \ --batch-dir output/experiments/h1-smoke ``` Recompute independent endpoints and paper source-data: ```bash python -m analysis.make_paper_artifacts \ --batch-dir output/experiments/h1-smoke \ --metric-config code/config/experiments/metrics_h1_calibration.json ``` Use the matching independent metric configuration: ```text h1_calibration.json metrics_h1_calibration.json h1_calibration_v2.json metrics_h1_calibration_v2.json h2_calibration*.json metrics_h2.json bilateral_calibration.json metrics_bilateral.json bilateral_calibration_v2_*.json metrics_bilateral_v2.json h1_calibration_v3.json metrics_h1_calibration_v3.json bilateral_calibration_v3_stable_contact.json metrics_bilateral_v3_stable_contact.json bilateral_calibration_v3_energy_challenge.json metrics_bilateral_v3_energy_challenge.json bilateral_network_v3_screening.json metrics_bilateral_network_v3_screening.json bilateral_network_v3_locked.json metrics_bilateral_network_v3_locked.json ``` The bilateral configurations derive H3 for every mapping/supervisor condition, but their H4 tables contain only tank-supervised methods; PO/PC and bypass conditions cannot be silently mixed into a tank audit. The declared minimal storage contract is JSON for manifests/plans, NPZ for numeric sample arrays, JSON Lines for events/trial metrics, and CSV for paper source-data. No Parquet dependency is required. ## Pairing and random numbers `pair_id` excludes the method and therefore identifies common inputs. `trial_id` includes the method. The trajectory, sensor, model, and network streams are derived independently with NumPy `SeedSequence`; their serialized states are identical across methods in the same pair. When `bilateral_pair_network_profiles=true`, `network_pair_group_id` excludes the network treatment while retaining the trajectory, mechanics, control settings, and replicate. This mode requires `network_common_random_numbers=true`; otherwise planning is rejected. Calibration, pilot, and locked studies must use separate specifications. A locked plan is immutable: changing a factor, method, trajectory, or seed invalidates its hashes. Files named `*_locked_template.json` are deliberately not confirmatory plans. Copy and freeze them only after calibration thresholds, safety limits, repeat counts, the source commit, and the analysis configuration have been approved.