The Dispatch Command API: A Safe Write Model

The write plane accepts bounded, idempotent commands that are validated, envelope-clamped, and staged into the L1 control plane rather than executed blindly.

Commands, not direct control

External parties do not drive actuators. They submit intents: a grid operator requests a power setpoint, an isotope customer requests a neutron-service window, a maintenance planner requests an outage slot. The dispatch command API receives these, validates them, and stages them into the L1 control plane where the twin and the safe operating envelope have final say. The separation means an external system can never bypass plant physics or safety.

Exactly-once, envelope-bounded

Every write carries an idempotency key so a retried or duplicated request executes at most once. Every write is checked against the certified envelope before staging. For the burner, a requested export above the direct-energy-conversion limit is clamped to the limit and the caller is told it was clamped; for the breeder, a neutron-service request that would perturb the breeding balance below the active TBR target under lever 1.1/1.5/1.8 is deferred, not forced.

def submit_dispatch(cmd):
    if seen(cmd.idempotency_key):
        return prior_result(cmd.idempotency_key)   # exactly-once
    target = clamp(cmd.setpoint, envelope(cmd.unit)) # never exceed certified limit
    ramp   = rate_limit_ramp(target, current_state())# respect slew limits
    ticket = L1.stage(cmd.unit, ramp)                # twin/failsafe authoritative
    record(cmd.idempotency_key, ticket)
    return {'accepted': True, 'clamped': target != cmd.setpoint,
            'ticket': ticket, 'eta_s': ramp.duration}

Commands are asynchronous and observable. The API returns a ticket; the caller polls or subscribes for progress as L1 ramps the machine and the twin confirms the new state through the read plane. This closes the loop honestly: the external party learns what actually happened, including partial fulfillment or a safety-driven abort.

Ramp rates matter as much as endpoints. A burner cannot step instantly between export levels; the API translates a setpoint into a rate-limited ramp the twin has certified as stable. Grid frequency-response commands, which must act in seconds, use a separate fast lane described in the grid-integration pages, still bounded by the same envelope.

All dispatch is twin-simulated until commissioning. The write path is validated end to end against KRONOS-CTRL so that, at FOAK ~2030, the same commands drive real hardware with no interface change.