Files
chenlin c32df70326
Checks / Layout, translation and Colab checks (push) Has been cancelled
Checks / Ruff (push) Has been cancelled
Checks / Framework tests (native backend, CPU) (push) Has been cancelled
Checks / Portable Rust controller (push) Has been cancelled
release: v0.1 generic robot training and application platform
2026-11-05 11:05:01 +08:00

838 lines
37 KiB
Python

"""The upload bundle: what a consumer receives, and whether it survives the trip.
A bundle carries a compiled controller, an FSM config and one policy per mode to
somebody who has none of this repository. Three failures are worth pinning and
all three produce a directory rather than an error:
- **an FSM nobody can load.** The bundler writes `controller.toml` and cannot itself
tell whether `FsmConfig::parse` accepts it -- Python cannot run it, and
re-implementing it here would be the second implementation this crate exists
to avoid. It asks the crate instead, and a bundle that fails is removed rather
than left for someone to find and upload.
- **modes and config that disagree.** A `[[fsm.state]]` naming a model with no
policy beside it loads, runs, and holds forever the first time the cascade
enters it.
- **a README that has stopped matching the thing it describes.** It is the only
part a consumer reads before writing code against the rest.
These build a real controller, which needs a Rust toolchain and the wasm target.
Skipped where there is none, because this repository's own suite must run on a
machine that only trains.
"""
from __future__ import annotations
import json
import shutil
import subprocess
import sys
import sysconfig
from pathlib import Path
import pytest
REPO = Path(__file__).resolve().parents[1]
SCRIPT = REPO / "scripts/deploy.py"
#: Where `docker-build.sh` leaves the board's controller; see `deploy.py`.
CROSS_BUILT = REPO / "out/deploy/controller-aarch64"
def _toolchain() -> str | None:
"""`cargo` plus the wasm target, or a reason to skip."""
if not shutil.which("cargo"):
return "cargo is not installed"
targets = subprocess.run(
["rustup", "target", "list", "--installed"], capture_output=True, text=True, check=False
)
if "wasm32-unknown-unknown" not in targets.stdout:
return "the wasm32-unknown-unknown target is not installed"
if not shutil.which("wasm-bindgen") and not (Path.home() / ".cargo/bin/wasm-bindgen").is_file():
return "wasm-bindgen is not installed"
return None
SKIP = _toolchain()
pytestmark = pytest.mark.skipif(SKIP is not None, reason=SKIP or "")
#: Two modes, one reachable only by a key. Written here rather than committed as
#: a fixture because what it pins is that the *bundler* checks it: a fixture that
#: drifted from the parser would make this pass while the check rotted.
TWO_MODES = """
[fsm]
initial_state = "walk"
warm_start_ref = "walk"
safe_state = "safe"
tilt_limit = 3.15
state_timeout_ms = 200
command_timeout_ms = 3600000
mode_switch_ramp_s = 0.0
pose_reach_tol = 0.10
warm_start_duration_s = 0.0
ramp_kp = 0.15
ramp_kd = 0.01
[[fsm.button]]
name = "slow"
key = "keypad_1"
on = "toggle"
[[fsm.state]]
name = "safe"
hold_current = true
kd = 0.01
[[fsm.state]]
name = "walk"
model = "walk.onnx"
[[fsm.state]]
name = "slow"
model = "slow.onnx"
[[fsm.rule]]
when = "feedback_stale"
enter = "safe"
[[fsm.rule]]
when = "in_state:safe"
enter = "@initial"
[[fsm.rule]]
when = "button:slow"
enter = "slow"
[[fsm.rule]]
when = "always"
enter = "walk"
"""
#: Where a build lands: `<dir>/<name>/`, and `<dir>/<name>.app` beside it.
#: `--mode` builds are named `bundle`, a manifest's by the manifest's name.
def built(out: Path, name: str = "bundle") -> Path:
return out / name
def run(*args: str, complete: bool = False) -> subprocess.CompletedProcess[str]:
"""A build, with `--allow-incomplete` unless `complete` asks for the default.
No flag for the tree: an uncommitted crate builds, and says so. The bundler
used to refuse one unless `--allow-dirty` was passed, which is right for a
published artifact and wrong for everything else: it made this suite red for
exactly as long as somebody was editing the controller, so "run the tests
before committing" and "the tests pass" could not both hold. That is not a
theory -- two commits went in on a red run because the failure looked like
cargo contention and was this. `--require-clean` is the opt-in now.
`--allow-incomplete` because the default cross-builds the board's controller
and converts every policy, in docker, which is minutes and a container this
suite must not need -- and what these pin is the assembly. Completeness is
`test_a_complete_app_is_read_off_what_was_written`'s and the two after it.
"""
builds = not any(a in ("--check-reference", "--translate") for a in args)
extra = ["--allow-incomplete"] if builds and not complete else []
return subprocess.run(
[sys.executable, str(SCRIPT), *args, *extra],
cwd=REPO, capture_output=True, text=True, check=False,
)
@pytest.fixture(scope="module")
def two_modes(tmp_path_factory, legacy_export) -> Path:
"""One build, one bundle, two modes on one export. Returns the bundle."""
out = tmp_path_factory.mktemp("bundles") / "two"
fsm = out.parent / "two.toml"
export = with_limits(legacy_export, out.parent / "export")
fsm.write_text(TWO_MODES, "utf-8")
result = run("--bundle", str(out), "--fsm", str(fsm),
f"--mode=walk={export}", f"--mode=slow={export}")
assert result.returncode == 0, result.stdout + result.stderr
return built(out)
def files(bundle: Path) -> set[str]:
return {p.relative_to(bundle).as_posix() for p in bundle.rglob("*") if p.is_file()}
def test_one_bundle_carries_every_host(two_modes: Path) -> None:
"""One directory, and each host's part of it named in `bundle.json`.
It was three directories, one per host, that had to be hashed against each
other to show they agreed about the FSM, the contracts and the reference.
One directory has one copy of each, and what differs by host -- the model
format, the build of the controller -- is under `models/` and `runtime/`,
with `runtimes` saying which host takes which. A host with somebody else's
runtime beside its own now carries it; what it must never do is *load* it,
which is `runtimes`' job.
"""
platform = sysconfig.get_platform()
present = files(two_modes)
shared = {"README.md", "bundle.json", "controller.toml", "reference.json",
"manual.en.json", "walk.json", "slow.json"}
assert shared <= present
assert {"runtime/web/controller.js", "runtime/web/controller.wasm",
f"runtime/mjlab/{platform}/controller.so"} <= present
# The board's controller, and play's for Windows and macOS, only when
# something has cross-built them, which a machine running this suite need
# not have. The `.rknn` likewise.
windows = "runtime/mjlab/win-amd64/controller.pyd"
macos = "runtime/mjlab/macosx-universal2/controller.so"
board = present - shared - {"runtime/web/controller.js", "runtime/web/controller.wasm",
f"runtime/mjlab/{platform}/controller.so"}
assert board - {"runtime/board/controller", windows, macos} == {"models/slow.onnx"}, board
# One file, for a consumer that is not a filesystem. Beside the directory,
# never instead of it: everything on this machine reads the directory.
assert (two_modes.parent / "bundle.app").is_file()
manifest = json.loads((two_modes / "bundle.json").read_text("utf-8"))
assert manifest["schema"] == "kk-policy-bundle/1"
assert "target" not in manifest, "a bundle is no longer packed for one host"
assert sorted(manifest["modes"]) == ["slow", "walk"]
web = manifest["runtimes"]["web"]
assert (web["model"], web["wasm"]) == ("onnx", "runtime/web/controller.wasm")
# Said out loud, because the consumer is the only one who can say it to the
# person who uploaded the bundle.
assert "held against" in web["unverifiedByTheConsumer"]
# The native build, keyed by the machine it was built on. Without it `play
# --app` runs whatever `mjrl_fsm` happens to be installed -- a different
# build of the same source, of any age.
mjlab = manifest["runtimes"]["mjlab"]
assert mjlab["model"] == "onnx"
assert mjlab["extensions"][platform]["file"] == f"runtime/mjlab/{platform}/controller.so"
# Windows imports an extension by `.pyd` and no other suffix; macOS is keyed
# without the version every Mac's platform string carries.
if windows in present:
assert mjlab["extensions"]["win-amd64"]["file"] == windows
if macos in present:
assert mjlab["extensions"]["macosx-universal2"]["file"] == macos
def test_every_bundle_carries_its_manual_and_is_what_the_schema_says(two_modes: Path) -> None:
"""The manual is written by every build, from the controller's own account
of its pad -- so the key a mode binds is the key the manual names. And the
build is held to `deploy/app.schema` before it is packed; this holds the
result to it again, from outside the script."""
import importlib.util
manifest = json.loads((two_modes / "bundle.json").read_text("utf-8"))
assert manifest["manuals"] == {"en": "manual.en.json"}
manual = json.loads((two_modes / "manual.en.json").read_text("utf-8"))
assert manual["modes"][0]["mode"] == "walk", "the default comes first"
# `slow` is on keypad_1 in TWO_MODES: the keyboard's switch, and the manual
# lists it as the keyboard's.
assert any(s["device"] == "keyboard" and s["keys"] == ["Num 1"] and "slow" in s["does"]
for s in manual["switches"])
walk = next(m for m in manual["modes"] if m["mode"] == "walk")
# The sign that has no second chance: W, and the stick pushed forward, are
# forward -- each on its own list, the pad's and the keyboard's.
keys = {k["key"]: k["does"] for k in walk["keys"]}
assert (keys["W"], keys["S"]) == ("walk forward", "walk back"), keys
ly = next(c for c in walk["controls"] if c["control"] == "Ly")
assert ly["does"] == "up: walk forward; down: walk back", ly
spec = importlib.util.spec_from_file_location("deploy_for_bundle", SCRIPT)
deploy = importlib.util.module_from_spec(spec)
spec.loader.exec_module(deploy)
deploy.validate_app(two_modes)
def test_two_modes_on_one_export_carry_one_model(two_modes: Path) -> None:
"""`claw_left` and `claw_right` are one export carried on two sides; the
three per-host bundles shipped its model twice each.
The control group is the contracts, which stay one per mode: a mode's
contract is what its hook and its observation history are keyed by.
"""
modes = json.loads((two_modes / "bundle.json").read_text("utf-8"))["modes"]
assert modes["walk"]["models"] == modes["slow"]["models"] == {"onnx": "models/slow.onnx"}
assert modes["walk"]["contract"] != modes["slow"]["contract"]
def test_every_file_it_names_is_there_and_hashes(two_modes: Path) -> None:
import hashlib
manifest = json.loads((two_modes / "bundle.json").read_text("utf-8"))
assert set(manifest["files"]) == files(two_modes) - {"bundle.json"}
for name, entry in manifest["files"].items():
raw = (two_modes / name).read_bytes()
assert len(raw) == entry["bytes"], name
assert hashlib.sha256(raw).hexdigest() == entry["sha256"], name
def test_the_glue_and_the_wasm_agree_on_each_others_names(two_modes: Path) -> None:
"""wasm-bindgen writes `<name>_bg.wasm` and points the glue at that name.
Renaming without rewriting the reference leaves two files that disagree --
invisible to a consumer that passes bytes, a 404 for one that does not."""
glue = (two_modes / "runtime/web/controller.js").read_text("utf-8")
assert "controller_bg.wasm" not in glue
assert glue.count("controller.wasm") == 1
def test_a_config_the_controller_cannot_load_is_not_written(tmp_path, legacy_export) -> None:
"""The control group.
Every assertion above passes against a bundler that writes files and checks
nothing -- which is what it did until this existed. A cascade whose last rule
is not `always` is refused by `FsmConfig::parse`, and that is the only thing
that can say so.
"""
fsm = tmp_path / "broken.toml"
fsm.write_text(TWO_MODES.replace('when = "always"', 'when = "gripper_active"'), "utf-8")
out = tmp_path / "broken"
result = run("--bundle", str(out), "--fsm", str(fsm),
f"--mode=walk={legacy_export}", f"--mode=slow={legacy_export}")
assert result.returncode != 0
assert "not `always`" in result.stdout + result.stderr
assert not built(out).exists(), "a bundle that exists is a bundle somebody will try"
assert not (out / "bundle.app").exists()
def test_modes_and_config_have_to_agree(tmp_path, legacy_export) -> None:
fsm = tmp_path / "two.toml"
fsm.write_text(TWO_MODES, "utf-8")
result = run("--bundle", str(tmp_path / "half"), "--fsm", str(fsm),
f"--mode=walk={legacy_export}")
assert result.returncode != 0
assert "no --mode slow" in result.stdout + result.stderr
# ...and the other way: a mode the config never declares.
result = run("--bundle", str(tmp_path / "extra"), "--fsm", str(fsm),
f"--mode=walk={legacy_export}", f"--mode=slow={legacy_export}", f"--mode=fly={legacy_export}")
assert result.returncode != 0
assert "--mode fly is not a" in result.stdout + result.stderr
def test_more_than_one_mode_needs_a_config(tmp_path, legacy_export) -> None:
"""One mode is synthesised; a priority order is a decision, and there is no
default for it that would not be somebody's silent choice."""
result = run("--bundle", str(tmp_path / "two"),
f"--mode=a={legacy_export}", f"--mode=b={legacy_export}")
assert result.returncode != 0
assert "need an FSM" in result.stdout + result.stderr
single = tmp_path / "one"
export = with_limits(legacy_export, tmp_path / "export")
result = run("--bundle", str(single), f"--mode=walk={export}")
assert result.returncode == 0, result.stdout + result.stderr
written = (built(single) / "controller.toml").read_text("utf-8")
assert 'model = "walk.onnx"' in written
assert 'when = "always"' in written
#: The locomotion tasks' controls block as `controls.py` writes it (schema 3,
#: 2026-09-29): the walk on the left stick and on W A S D, the turn on the right
#: stick and on J L. The fixture predates controller blocks altogether.
WALK_CONTROLS = {
"schema": "operator_controller/2",
"command": [{"term": "twist", "feeds": "velocity_commands", "frame": "body",
"axes": [{"name": "lin_vel_x", "index": 0, "unit": "m/s", "positive": "forward"},
{"name": "lin_vel_y", "index": 1, "unit": "m/s", "positive": "left"},
{"name": "ang_vel_z", "index": 2, "unit": "rad/s",
"positive": "counter-clockwise"}]}],
"task": {},
"devices": {
"gamepad": {"scheme": "absolute", "layout": "xbox",
"axes": {"lin_vel_x": {"source": "Ly", "sign": -1},
"lin_vel_y": {"source": "Lx", "sign": -1},
"ang_vel_z": {"source": "Rx", "sign": -1}},
"deadzone": "device_reported_rescaled", "release_button": "B"},
"keyboard": {"scheme": "keys", "full_after_s": 2.0,
"axes": {"lin_vel_x": {"+": ["key_w"], "-": ["key_s"]},
"lin_vel_y": {"+": ["key_a"], "-": ["key_d"]},
"ang_vel_z": {"+": ["key_j"], "-": ["key_l"]}},
"release": ["key_b"]},
},
}
def with_limits(source: Path, into: Path) -> Path:
"""A copy of the fixture export, with joint limits and the walk's controls
in its contract.
The synthetic input omits both fields so it can exercise the legacy
loader and its joint-limit requirement as separate cases.
"""
shutil.copytree(source, into)
layout = into / "layout.json"
contract = json.loads(layout.read_text("utf-8"))
contract["joint_limits"] = {
j: [contract["default_joint_pos"][j] - 1.0, contract["default_joint_pos"][j] + 1.0]
for j in contract["wire_joint_order"]
}
contract["controller"] = WALK_CONTROLS
layout.write_text(json.dumps(contract) + "\n", "utf-8")
return into
@pytest.fixture(scope="module")
def deploy():
"""`scripts/deploy.py` as a module, by path; see `test_bundle_archive.py`."""
import importlib.util
spec = importlib.util.spec_from_file_location("deploy_for_completeness", SCRIPT)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
def convert_by_pretending(export: Path) -> None:
"""What `onnx2rknn.py` leaves beside an export, minus a real model."""
import hashlib
(export / "actor.rknn").write_bytes(b"RKNN\x00 not a real model, only its name")
digest = hashlib.sha256((export / "actor.onnx").read_bytes()).hexdigest()
(export / "actor.rknn.json").write_text(json.dumps({"onnx_sha256": digest}), "utf-8")
def test_a_complete_app_is_read_off_what_was_written(deploy, two_modes: Path) -> None:
"""The default refuses an app that lacks the board's controller, `play`'s
Windows or macOS one, a `.rknn` or the reference vectors, and it reads that off
`bundle.json` -- what a consumer receives -- rather than off the steps that
should have made them.
`two_modes` was built with `--allow-incomplete` from an export with no
`.rknn`, so both modes must be named. The control group is the same
manifest with the parts filled in: a check that named every bundle there is
would pass the first half.
"""
manifest = json.loads((two_modes / "bundle.json").read_text("utf-8"))
lacking = deploy.gaps(manifest)
assert "slow: no .rknn" in lacking and "walk: no .rknn" in lacking, lacking
assert "no reference vectors" not in lacking, "two_modes carries one"
assert ("no board controller" in lacking) == ("board" not in manifest["runtimes"])
extensions = manifest["runtimes"]["mjlab"]["extensions"]
assert ("no Windows controller for play" in lacking) == ("win-amd64" not in extensions)
assert ("no macOS controller for play" in lacking) == ("macosx-universal2" not in extensions)
manifest["runtimes"]["board"] = {"model": "rknn"}
extensions["win-amd64"] = {"file": "runtime/mjlab/win-amd64/controller.pyd"}
extensions["macosx-universal2"] = {"file": "runtime/mjlab/macosx-universal2/controller.so"}
for entry in manifest["modes"].values():
entry["models"]["rknn"] = "models/slow.rknn"
assert deploy.gaps(manifest) == []
manifest["reference"] = None
assert deploy.gaps(manifest) == ["no reference vectors"]
def test_an_rknn_counts_only_beside_the_onnx_it_was_made_from(deploy, tmp_path, legacy_export) -> None:
"""A policy exported again into the same directory leaves the old `.rknn`
beside it, looking finished. The converter records the ONNX's digest, and
only a matching one counts -- otherwise the default converts again."""
export = with_limits(legacy_export, tmp_path / "export")
assert not deploy.converted(export)
(export / "actor.rknn").write_bytes(b"RKNN\x00 made by something that kept no record")
assert not deploy.converted(export), "an .rknn with no record of its ONNX"
convert_by_pretending(export)
assert deploy.converted(export), "the control: the record matches"
(export / "actor.onnx").write_bytes((export / "actor.onnx").read_bytes() + b"\0")
assert not deploy.converted(export), "the ONNX changed under the .rknn"
def test_the_default_says_what_it_cannot_make_before_it_makes_anything(
deploy, tmp_path, legacy_export) -> None:
"""The board's half takes minutes -- a cross build, a conversion per policy
-- so what would stop it is asked first, and a refusal writes nothing.
The case that can be arranged on any machine: an export outside the
repository, which the converter's container cannot see. The control is the
same export already converted, which has nothing left to convert.
"""
export = with_limits(legacy_export, tmp_path / "export")
assert not export.resolve().is_relative_to(REPO), "the case needs an export outside"
problems = deploy.preflight({"walk": export})
assert any(str(export.resolve()) in p and "outside the repository" in p
for p in problems), problems
out = tmp_path / "strict"
result = run("--bundle", str(out), f"--mode=walk={export}", complete=True)
said = result.stdout + result.stderr
assert result.returncode != 0, said
assert "outside the repository" in said and "--allow-incomplete" in said
assert "cross-building" not in said, "it refused only after starting the board's half"
assert not out.exists(), "a refused app leaves nothing behind"
convert_by_pretending(export)
assert not any(str(export.resolve()) in p for p in deploy.preflight({"walk": export}))
def test_a_bundle_says_what_the_board_is_missing(tmp_path, legacy_export) -> None:
"""With `--allow-incomplete`: a bundle whose models are still ONNX cannot
run on a board, so it says which modes and gives the command rather than
shipping something that looks ready; and a bundle with no cross-built
controller says that too.
"""
out = tmp_path / "board"
fsm = tmp_path / "one.toml"
fsm.write_text(TWO_MODES, "utf-8")
export = with_limits(legacy_export, tmp_path / "export")
result = run("--bundle", str(out), "--fsm", str(fsm),
f"--mode=walk={export}", f"--mode=slow={export}")
assert result.returncode == 0, result.stdout + result.stderr
bundle = built(out)
manifest = json.loads((bundle / "bundle.json").read_text("utf-8"))
# No `.rknn` beside those exports, so the modes carry ONNX alone and the
# bundle refuses to look ready. The command it prints is the one that fixes it.
assert any("not ready for the board" in n for n in manifest["notes"])
assert any("onnx2rknn.py" in n for n in manifest["notes"])
assert manifest["modes"]["walk"]["models"] == {"onnx": "models/slow.onnx"}
# The invariant, in whichever state this machine is: the board's runtime is
# either **in** the bundle or **named** in the notes. Never neither -- a
# bundle that looks complete is one somebody copies to a robot.
#
# Asserted as an either/or because both states are normal. It used to assert
# the note, which was right until somebody ran `docker-build.sh` for the
# first time and the binary started being there.
has_binary = (bundle / "runtime/board/controller").is_file()
says_missing = any("no board runtime" in n for n in manifest["notes"])
assert has_binary != says_missing, (
f"controller present={has_binary}, notes={manifest['notes']}"
)
assert has_binary == ("board" in manifest["runtimes"])
if says_missing:
assert any("docker-build.sh" in n for n in manifest["notes"])
else:
board = manifest["runtimes"]["board"]
assert (board["model"], board["platform"]) == ("rknn", "aarch64-unknown-linux-gnu")
assert "runtime/board/controller" in (bundle / "README.md").read_text("utf-8")
def test_a_converted_policy_ships_as_rknn_beside_the_onnx(tmp_path, legacy_export) -> None:
"""The other half of the same check: given a `.rknn`, it travels with the
ONNX -- the board takes one, the browser the other -- and the bundle stops
warning."""
export = with_limits(legacy_export, tmp_path / "export")
(export / "actor.rknn").write_bytes(b"RKNN\x00 not a real model, only its name")
out = tmp_path / "ready"
result = run("--bundle", str(out), f"--mode=walk={export}")
assert result.returncode == 0, result.stdout + result.stderr
bundle = built(out)
assert {"models/walk.rknn", "models/walk.onnx"} <= files(bundle)
manifest = json.loads((bundle / "bundle.json").read_text("utf-8"))
assert manifest["modes"]["walk"]["models"] == {
"onnx": "models/walk.onnx", "rknn": "models/walk.rknn"}
assert not any("not ready" in n for n in manifest["notes"])
def test_a_board_is_not_given_a_policy_with_no_joint_limits(tmp_path, legacy_export) -> None:
"""The reason `joint_limits` exists at all.
Both simulators read the hard stops off the model they loaded and clamp
every commanded target to them. The board has no model, so before this it
clamped to a pair in its own config -- and the pair it held was the
placeholder range from the test configuration. A range wider than the
physical stops cannot prevent a target from reaching them.
One bundle carries the board whenever a controller has been cross-built
for it, so an export predating the field refuses the whole bundle then:
loading in a browser and not on the board is a broken bundle. The
fixture omits the field, and the copy with limits is the control group.
"""
if not CROSS_BUILT.is_file():
pytest.skip("no board runtime is cross-built here, so no board to refuse it")
assert "joint_limits" not in json.loads((legacy_export / "layout.json").read_text("utf-8"))
result = run("--bundle", str(tmp_path / "board"), f"--mode=walk={legacy_export}")
assert result.returncode != 0
assert "no joint limits" in result.stdout + result.stderr
assert "Re-export" in result.stdout + result.stderr
export = with_limits(legacy_export, tmp_path / "export")
result = run("--bundle", str(tmp_path / "limited"), f"--mode=walk={export}")
assert result.returncode == 0, result.stdout + result.stderr
MANIFEST = {
"schema": "kk-deploy-manifests/1",
"bundles": {
"two": {
"description": "two gaits",
"fsm": "cascade.toml",
"modes": {
"walk": {"task": "fixture.walk", "policy": None, "keys": {"key": ["keypad_1"]}},
"slow": {"task": "fixture.walk", "policy": None, "pad": {"button": "A"}},
},
}
},
}
#: The manifest's counterpart: the cascade, and nothing the manifest owns.
CASCADE = """
[fsm]
initial_state = "walk"
warm_start_ref = "walk"
safe_state = "safe"
tilt_limit = 3.15
state_timeout_ms = 200
command_timeout_ms = 3600000
mode_switch_ramp_s = 0.0
pose_reach_tol = 0.10
warm_start_duration_s = 0.0
ramp_kp = 0.15
ramp_kd = 0.01
[[fsm.state]]
name = "safe"
hold_current = true
kd = 0.01
[[fsm.rule]]
when = "feedback_stale"
enter = "safe"
[[fsm.rule]]
when = "in_state:safe"
enter = "@initial"
[[fsm.rule]]
when = "button:slow"
enter = "slow"
# `walk` is also where `always` lands, so this rule is what makes its key do
# something -- the crate refuses a binding no rule reacts to, on the grounds
# that a key that does nothing is indistinguishable from one that is broken.
[[fsm.rule]]
when = "button:walk"
enter = "walk"
[[fsm.rule]]
when = "always"
enter = "walk"
"""
def write_manifest(tmp_path: Path, export: Path) -> Path:
import copy
data = copy.deepcopy(MANIFEST)
where = str(export.relative_to(REPO)) if export.is_relative_to(REPO) else str(export)
for entry in data["bundles"]["two"]["modes"].values():
entry["policy"] = where
path = tmp_path / "manifests.json"
path.write_text(json.dumps(data), "utf-8")
(tmp_path / "cascade.toml").write_text(CASCADE, "utf-8")
return path
def test_a_manifest_records_where_every_mode_came_from(tmp_path, legacy_export) -> None:
"""The build's input, so a bundle records its ancestry and not only its
contents.
Which checkpoint a mode came from lived on somebody's command line. A
bundle rebuilt from a different run of the same task differs in nothing the
bundler looks at -- same mode names, same shapes, same joint order.
"""
export = with_limits(legacy_export, tmp_path / "export")
manifest = write_manifest(tmp_path, export)
out = tmp_path / "b"
result = run("--bundle", str(out), "--manifest", "two", "--manifests", str(manifest))
assert result.returncode == 0, result.stdout + result.stderr
ancestry = json.loads((built(out, "two") / "bundle.json").read_text("utf-8"))["built_from"]
assert sorted(ancestry) == ["slow", "walk"]
assert ancestry["walk"]["task"] == "fixture.walk"
assert ancestry["walk"]["keys"] == {"key": ["keypad_1"]}
assert ancestry["slow"]["pad"] == {"button": "A"}
# The bindings and the model states are composed in, so the file that
# travels is complete even though neither input file was.
written = (built(out, "two") / "controller.toml").read_text("utf-8")
assert 'key = "keypad_1"' in written and 'name = "walk"' in written
assert 'pad = "A"' in written and 'on = "toggle"' in written
assert 'model = "walk.onnx"' in written and 'model = "slow.onnx"' in written
def test_neither_file_may_say_the_others_half(tmp_path, legacy_export) -> None:
"""The control group, and the reason the split is worth having.
Two files naming the same key is how the two come to disagree, and nothing
reads both. So a cascade declaring a binding -- or a mode -- is refused
rather than merged over.
"""
export = with_limits(legacy_export, tmp_path / "export")
manifest = write_manifest(tmp_path, export)
args = ["--bundle", str(tmp_path / "b"), "--manifest", "two",
"--manifests", str(manifest)]
for extra, expect in (
('\n[fsm.key]\nkeypad_9 = "walk"\n', "[fsm.key]"),
('\n[[fsm.button]]\nname = "walk"\npad = "B"\non = "rise"\n', "[[fsm.button]]"),
('\n[[fsm.state]]\nname = "walk"\nmodel = "walk.onnx"\n', "a [[fsm.state]]"),
):
(tmp_path / "cascade.toml").write_text(CASCADE + extra, "utf-8")
result = run(*args)
assert result.returncode != 0, extra
assert expect in result.stdout + result.stderr, extra
assert "the manifest owns" in result.stdout + result.stderr
# Without the overlap it builds. Otherwise the three above would pass
# against a bundler that refuses every manifest there is.
(tmp_path / "cascade.toml").write_text(CASCADE, "utf-8")
assert run(*args).returncode == 0
def test_a_manifest_takes_an_export_and_not_a_checkpoint(tmp_path, legacy_export) -> None:
"""A checkpoint is not something a robot can run.
Exporting is where the contract is built and where the validations decide
whether it can run at all, so a manifest naming a checkpoint makes the
bundler pick an export on the reader's behalf. It did, briefly -- the newest
matching one -- which is a silent choice about what ships, made at build
time, from a field that looks like it names a thing.
The ancestry survives leaving it out: the export records its own checkpoint
and `built_from` reads it back, so there is no second copy to disagree.
"""
export = with_limits(legacy_export, tmp_path / "export")
manifest = write_manifest(tmp_path, export)
data = json.loads(manifest.read_text("utf-8"))
for entry in data["bundles"]["two"]["modes"].values():
entry.pop("policy")
entry["checkpoint"] = "logs/fixture_model/fixture.walk/whenever/model_5700.pt"
manifest.write_text(json.dumps(data), "utf-8")
result = run("--bundle", str(tmp_path / "b"), "--manifest", "two",
"--manifests", str(manifest))
assert result.returncode != 0
out = result.stdout + result.stderr
assert "names a checkpoint. This takes an export" in out
assert "scripts/export.py --task fixture.walk" in out, "it must say how to get one"
def test_the_checkpoint_in_a_bundle_comes_from_the_export(tmp_path, legacy_export) -> None:
"""`built_from` reads the ancestry out of the export, not out of the manifest.
The manifest names a directory; the directory says which checkpoint it came
from. Copying that into the manifest as well would be two statements about
one fact, and the failure would be a bundle whose recorded run is not the
run that produced it.
"""
export = with_limits(legacy_export, tmp_path / "export")
layout = export / "layout.json"
contract = json.loads(layout.read_text("utf-8"))
contract["_checkpoint"] = {
"path": "logs/fixture_model/fixture.walk/2026-01-01_00-00-00/model_42.pt",
"run": "logs/fixture_model/fixture.walk/2026-01-01_00-00-00",
"iteration": "model_42",
}
layout.write_text(json.dumps(contract), "utf-8")
out = tmp_path / "b"
manifest = write_manifest(tmp_path, export)
assert run("--bundle", str(out), "--manifest", "two",
"--manifests", str(manifest)).returncode == 0
ancestry = json.loads((built(out, "two") / "bundle.json").read_text("utf-8"))["built_from"]
assert ancestry["walk"]["from"] == "logs/fixture_model/fixture.walk/2026-01-01_00-00-00/model_42.pt"
# An export from before that record says so, rather than the bundle claiming
# a provenance it does not have.
del contract["_checkpoint"]
layout.write_text(json.dumps(contract), "utf-8")
out2 = tmp_path / "b2"
assert run("--bundle", str(out2), "--manifest", "two",
"--manifests", str(manifest)).returncode == 0
ancestry = json.loads((built(out2, "two") / "bundle.json").read_text("utf-8"))["built_from"]
assert "records no checkpoint" in ancestry["walk"]["from"]
def test_a_mode_whose_export_is_missing_names_the_command(tmp_path) -> None:
"""The manifest is right and the export has not been run. That is not an
error about the manifest, so it does not read like one."""
manifest = write_manifest(tmp_path, tmp_path / "never-exported")
result = run("--bundle", str(tmp_path / "b"), "--manifest", "two",
"--manifests", str(manifest))
assert result.returncode != 0
out = result.stdout + result.stderr
assert "names an export that is not there" in out
assert "scripts/export.py --task fixture.walk" in out
# Exports are timestamped and untracked, so this is the normal way a
# manifest arrives from another machine -- said, rather than left as a
# missing path.
assert "another machine" in out
def test_the_reference_is_replayable_and_can_fail(tmp_path, legacy_export) -> None:
"""The bundle records what its controller does, so three hosts can be held
against it rather than against each other.
They compile one source with three toolchains for two architectures and run
the policy on three inference backends. "Same source" survives all of that
and so would a divergence, which is why this is a recorded measurement and
not a comment.
The control group matters more than usual here: the host that *generates*
the reference will always match it, so a check that only ran there would be
green by construction. This perturbs the file and requires the check to go
red -- and the numbers it reports are the size of the perturbation, not a
vaguer complaint.
"""
parent = tmp_path / "ref"
export = with_limits(legacy_export, tmp_path / "export")
result = run("--bundle", str(parent), f"--mode=walk={export}")
assert result.returncode == 0, result.stdout + result.stderr
out = built(parent)
manifest = json.loads((out / "bundle.json").read_text("utf-8"))
assert manifest["reference"] == "reference.json", manifest.get("notes")
reference = json.loads((out / "reference.json").read_text("utf-8"))
assert reference["schema"] == "kk-policy-reference/1"
assert len(reference["frames"]) >= 8
# Term spans, so a host names the term rather than an index. Without them a
# difference in `joint_torque` -- the one term a robot sources differently
# by design -- is indistinguishable from a real bug at index 404.
assert [t["name"] for t in reference["terms"]], "the terms are not located"
assert sum(t["dim"] for t in reference["terms"]) == reference["frames"][0]["obs"].__len__()
clean = run("--check-reference", str(out))
assert clean.returncode == 0, clean.stdout + clean.stderr
assert "matches the reference" in clean.stdout
# One joint target off by a milliradian: what a changed decode produces and
# an eyeball does not catch.
reference["frames"][3]["target"][0] += 1e-3
(out / "reference.json").write_text(json.dumps(reference), "utf-8")
dirty = run("--check-reference", str(out))
assert dirty.returncode == 1, dirty.stdout
assert "does not match" in dirty.stdout
assert "1.000e-03" in dirty.stdout, dirty.stdout
def test_the_readme_describes_the_bundle_it_is_in(two_modes: Path) -> None:
"""It is the only part a consumer reads before writing code against the rest,
so a placeholder that failed to substitute is worse than a missing file --
and a README naming a file that is not here is worse still, because it
reads as a bundle that is missing something."""
import re
readme = (two_modes / "README.md").read_text("utf-8")
manifest = json.loads((two_modes / "bundle.json").read_text("utf-8"))
assert not re.search(r"\{[A-Z_]+\}", readme), "an unsubstituted placeholder"
# The fenced listing at the top, held against the directory. Checking the
# whole README instead would be both weaker and impossible: `controller` is
# a filename and also an English word in the first sentence.
listing = re.search(r"```\n(.*?)```", readme, re.DOTALL)
assert listing, "the README does not list its own files"
named = {line.split()[0] for line in listing.group(1).splitlines()
if line.split() and not line.startswith(" ")}
on_disk = files(two_modes)
assert named <= on_disk, f"the README lists {named - on_disk}, which is not here"
# Everything but the README itself, which does not list itself.
assert on_disk - named == {"README.md"}, f"unlisted files: {on_disk - named - {'README.md'}}"
assert manifest["runtimes"]["web"]["commit"] in readme
# The three that fail silently, and the isolation advice, are the reason
# this file exists rather than a link. "both edges" replaced "rising edge":
# a host that reports only presses can drive `toggle` and `rise` and
# silently nothing else.
for topic in ("wire order", "body frame", "opaque origin", "both edges"):
assert topic in readme, topic