Raymond Ehizoba | The Software Track: A Contract Between Model and Machine

Part 4 of the build log — the software track opens: two tracks, one project, and the first draft of the plan contract. (Part 1: the vision · Part 2: how it works · Part 3: tightening the scope)

Two tracks, one project

Quick hardware status first, because it moved: the chassis is assembled — servo, dampers, and links all mounted, motor and integrated ESC in place. Wheels and driveshafts are in transit; radio and battery are the next order. A proper hardware entry with photos lands when the thing drives. But that is exactly the point of this post — the remaining boxes take weeks, and the research question never needed them this early.

So the build log forks into two tracks that ship independently. The hardware track ends in a machine that drives; the software track ends in the Phase 3 curve — grounding accuracy against cost across escalation policies. They meet at Phase 2, when plans built and tested against fixtures start running on a real robot. Until that merge, neither track is allowed to block the other.

flowchart LR
 classDef sw fill:#EEF2FF,stroke:#6366F1,color:#312E81;
 classDef hw fill:#FFFBEB,stroke:#F59E0B,color:#92400E;
 classDef merge fill:#ECFDF5,stroke:#10B981,color:#065F46;

 subgraph SW["Software track — ships on its own cadence"]
 S0["Phase 0: the contract<br/>mission → typed plan"] --> S1["Phase 1: decomposition scores<br/>+ failure catalogue"] --> S2["Replay harness<br/>fixtures + recorded traces"]
 end

 subgraph HW["Hardware track — ships when boxes land"]
 H0["Rolling chassis"] --> H1["Radio + battery"] --> H2["Phase −1: first drive<br/>+ logged teleop traces"]
 end

 S2 --> M["Phase 2: pre-authored plans<br/>run on the real crawler"]
 H2 --> M

 class S0,S1,S2 sw
 class H0,H1,H2 hw
 class M merge

Two tracks, one merge point. Everything on the software track is buildable today, robot or no robot; the tracks meet when pre-authored plans run on the real crawler.

The contract: what a mission is, what a plan is

The software track starts where Part 2 said it must: Phase 0, the contract. Before any autonomy code, the types get locked. A mission is one plain-language sentence — the thing you would actually say to the robot. A typed plan is a bounded sequence of behaviors drawn from a deliberately small vocabulary, and every behavior carries its own success criteria and its own pre-declared escalation conditions. The plan states, up front, what would make it doubt itself. If a plan does not validate against the schema, it does not run — there is no partially-legal plan.

Here is the shape of it — first draft, hand-authored, deliberately small:

json

{
  "mission": "Go to the blue barrel by the fence and wait there.",
  "scene": "yard-test-scene-v1",
  "plan": [
    {
      "behavior": "navigate_to",
      "target": { "label": "blue barrel", "prior_hint": "north fence line" },
      "success": { "pose_within_m": 0.5, "detector": "blue_barrel", "min_confidence": 0.6 },
      "escalate_if": [ "detector_silent_s > 20", "replans > 2" ],
      "timeout_s": 90
    },
    {
      "behavior": "hold_position",
      "success": { "held_for_s": 30 },
      "escalate_if": [ "displacement_m > 1.0" ],
      "timeout_s": 45
    }
  ],
  "escalate_always_if": [ "battery_pct < 20", "localization_lost_s > 10" ]
}

Three properties of that shape are the whole point. It is validatable — malformed or out-of-vocabulary plans are rejected before anything touches a motor. It is bounded — every behavior has a timeout, so no plan can run forever. And it is honest about doubt — escalation conditions are declared at planning time, not improvised at runtime; the cheap on-device layer only ever checks conditions the plan already named. The behavior vocabulary starts embarrassingly small — navigate_to, hold_position, and little else — and that is deliberate. Every behavior added later has to buy its way in with a mission template that needs it.

What ships next on this track

Immediate deliverables on this track, in order: a fixed set of mission templates and one controlled test scene with known ground-truth positions; a hand-authored mission → plan fixture set that doubles as the scoring truth; then Phase 1 — the expensive model decomposing those same missions, scored against the fixtures, with a catalogue of the ways it gets decomposition wrong. That catalogue is the first measurable result of the whole project, and nothing about it requires wheels.

The hardware track will interrupt with photos the moment the crawler rolls. Until then, this track has the floor.

More as it crawls.