exoskeleton/code/experiments/README.md

# 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.