Reference implementation and replication data for the paper "Bounded-Fidelity Sim-as-Demo-Stage: Mocap Handoff for Governance Benchmarks" (2026).
This repository extracts the three modules of the construction
(MocapAdapter, AuditChain, HandoffEnvelope), the two reference
harnesses (harness/envelope_precision.py, harness/multi_object.py),
and the canonical seed=12345 reference run summaries that back every
quantitative claim in §4 of the paper. The slim repo is intentionally
self-contained so a reviewer can clone, inspect, and verify the
hypothesis sign-checks in under a minute, without any access to the
closed-source governance runtime against which the paper's full trials
were collected.
| Path | What it is |
|---|---|
src/mocap_adapter.py |
The three-method interface (enter_handoff / update / exit_handoff) from paper §4.1, against the public MuJoCo Python API |
src/audit_chain.py |
Append-only structured-intent event stream + canonical SHA-256 from paper §4.2 |
src/handoff_envelope.py |
Phase-state contract object (Approach -> Grasp -> Carry -> Place -> Release) from paper §3.2; envelope set E = {carry} |
harness/envelope_precision.py |
Reference harness for the 7-jitter sweep of paper §4.5 (Table 2 / Figure 3a) |
harness/multi_object.py |
Reference harness for the K in {1,2,3} multi-object sweep of paper §4.6 (Table 3 / Figure 3b) |
scripts/sign_check.py |
Stdlib-only verifier: re-evaluates hypotheses H1-H4 against the shipped data (no MuJoCo required) |
data/task01-envelope-precision/ |
Reference summary.json + sign_check.json for the 1,400-trial envelope sweep |
data/task02-multi-object/ |
Reference summary.json + sign_check.json for the 1,500-trial multi-object sweep |
Dockerfile |
Reproducible container; docker build -t bounded-fidelity-mocap-handoff . then docker run runs scripts/sign_check.py in ~1 s |
pyproject.toml |
Python >= 3.11; stdlib-only for the sign-check path; [sim] extra pins mujoco==3.1.4 for the harnesses |
tests/ |
Unit tests for AuditChain, HandoffEnvelope, and MocapAdapter (the geometry math; the MuJoCo path is mocked) |
The fastest reviewer-friendly path is scripts/sign_check.py, which
re-evaluates every gated hypothesis against the shipped JSON summaries:
pip install -e .
python scripts/sign_check.pyExpected output:
Bounded-fidelity-pattern sign-check on shipped data
---------------------------------------------------
task01 (envelope-precision sweep, 7x200=1400 trials):
[PASS] H1 +/-1 byte-stable (distinct hashes = 1 at jitter -1/0/+1)
[PASS] H2 +/-5 divergence within 5 pp (baseline divergence = 0.000)
[PASS] H4 wall-clock p50 within +/-5 % (max drift = 0.0001)
[obs] H3 +/-10 divergence: {-10: 0.0, 10: 0.0}
task02 (multi-object scale sweep, 3x500=1500 trials):
[PASS] H1 byte-equal >= 99 % (min byte-equal = 1.0000)
[PASS] H2 per-PnP wall ratio <= 1.2 (observed ratio = 1.0001)
[PASS] H3 K=3 primary hash >= 95 % (observed share = 1.0000)
Overall verdict: PASS
The exit code is 0 on PASS, 1 on FAIL.
harness/envelope_precision.py and harness/multi_object.py are
reference harnesses showing how a governance bridge would call into
MocapAdapter and AuditChain. To actually re-run them you need:
- MuJoCo 3.1.4 (
pip install -e ".[sim]"). - A workshop scene XML declaring at least one body with
mocap="true"and a gripper site readable by the adapter (the production harness used a 220-LOC closed-source XML; constructing a minimal equivalent is a few-hour exercise).
A minimal example:
python harness/envelope_precision.py \
--scene-xml my_workshop.xml \
--boundary-jitter 0 \
--trials 200 \
--seed 12345 \
--output data/task01-envelope-precision/raw_jitter_0.jsonlThese reference harnesses do not try to reproduce the exact audit-chain SHA-256 of the shipped run; the shipped hash is keyed on the specific XML and bridge-runtime layout used to collect the paper's trials, which is not bundled here for single-blind reasons. The reviewer-relevant invariant the reference harnesses establish is the structure of the audit chain (event types, payload shape, hash function), not the exact hex digest.
| Paper section | Code in this repo |
|---|---|
| §3.1 mocap-body handoff | src/mocap_adapter.py (enter_handoff / update / exit_handoff) |
| §3.2 the handoff envelope | src/handoff_envelope.py (Phase, ENVELOPE, HandoffEnvelope) |
| §4.1 Implementation | src/mocap_adapter.py is a clean reference impl of the same three-method interface; the paper's production module is ~220 LOC including bridge plumbing not needed here |
| §4.2 audit-chain stability | src/audit_chain.py (AuditChain.sha256 and canonical_hash) |
| §4 Proposition 1 (determinism preservation) | Discharged by MocapAdapter.update: bound bodies' poses are pure functions of the gripper-tip pose via a captured rigid transform |
| §4 Proposition 2 (audit-chain stability under handoff) | Demonstrated empirically by the shipped sign-check passes |
| §4.3 / §4.4 / §4.5 / §4.6 quantitative results | data/ + scripts/sign_check.py (every gated hypothesis in §4.5 and §4.6 is re-checked) |
The 2,900 trials reported in the paper (1,400 envelope-precision +
1,500 multi-object) were collected against a closed-source governance
runtime. The reference implementation in this slim repo isolates the
pattern (the three-method adapter interface, the audit-chain
contract, the phase-state envelope) from the runtime in which the
shipped trials were collected. The shipped summary.json and
sign_check.json files in data/ are byte-equal copies of the
production run; scripts/sign_check.py verifies that those files
satisfy the hypothesis thresholds claimed in paper §4.5 and §4.6.
Apache License 2.0. See LICENSE and NOTICE.
If you build on this work, please cite the paper. The BibTeX entry will be added here once a DOI is assigned; until then, please cite as
Xue Qin, Simin Luan, Cong Yang, Zhijun Li. Bounded-Fidelity
Sim-as-Demo-Stage: Mocap Handoff for Governance Benchmarks. 2026.