Workload runtime contract
The workload runtime contract is the promise a workload may rely on: the process it is started as, the filesystem and network it is given, the bytes it exchanges on the frame bus, and the rules by which it is restarted or stopped. An OCaml binding over this contract ships with the Platform. A workload in C, C++, Python or Rust implements the contract directly.
The first section below is what the runtime does now, and it is verifiable from a running node. The second is the contract being built, and none of it is something a workload may depend on yet. Paths and environment-variable names become ABI the day the contract is published, so nothing here is safe to hard-code before then.
What holds today
These are the parts a workload already meets. Each is a property of the runner and the launch it performs.
A workload is one service in a partition. It is declared in
build.yaml, under a partition whose supervisor
starts it, and its runtime placement comes from
run.yaml. Those two pages are the field reference;
this one does not repeat them.
The isolation boundary follows the runtime. A unikernel needs a Solo5
tender, Firecracker, or QEMU. An OCI service needs runc. A host-native
executable runs directly or under runc. A build that pairs a runtime with an
isolation backend that cannot hold it is refused at build time. Host isolation
is the exception a node must opt into: it runs uncontained, so the runner
refuses to launch a host-isolated service and names the service unless it was
started with that posture enabled.
The process comes from the image, and the composition may override it. An OCI service takes its entrypoint, arguments, and working directory from the image and runs with them. Environment entries declared on the service override entries of the same name in the image’s configuration; entries the image declares and the service does not are kept.
Configuration keys beginning space. belong to the product. The
supervisor reads them and does not pass them to the process. They carry the
entrypoint and arguments, the working directory, the data paths the runner
backs with storage, credential bindings, and settings. A workload’s own keys
share the same map and must not use that prefix.
Each workload gets its own input and output root. They are two directories named by the workload, one for what it runs over and one for what it leaves. A workload name that is not a single path segment is refused, so one workload cannot be given another’s root.
Health is evaluated from outside the guest. The runner runs a healthcheck
declared on the service, and a workload does not have to serve anything to be
supervised.
Interfaces are declared, not discovered. A workload reaches the frame bus, an IP bridge, the node network, a high-rate data link, or the supervision page only when its service entry declares that interface. An undeclared interface is absent.
The contract being built
WIP Publishing the contract means fixing all of the following together and versioning them as one. Until that lands, each row is a thing the runtime does in some particular way that a workload must not assume will stay that way.
| Area | What the published contract will fix |
|---|---|
| Contract version | A version the release carries and the workload can read |
| Runtime | The container, unikernel, and host execution classes it covers |
| Process | Entrypoint, arguments, working directory, user, groups, and signals |
| Environment | Every reserved variable, its producer, and whether a workload may override it |
| Filesystem | Read-only and writable paths, mount types, ownership, modes, and lifetime |
| Network | Namespace, interfaces, socket types, peer identity, and failure behaviour |
| Frame ABI | Framing, byte order, field ranges, short-read handling, and version negotiation |
| Configuration | Grammar, required and optional values, provenance, and update rules |
| Credentials | Authorisation, source, mount path, ownership, mode, rotation, and cleanup |
| Resources | CPU, memory, process, storage, and traffic limits |
| Lifecycle | Start ordering, readiness, health, exit handling, restart limits, and shutdown |
| Compatibility | Which older and newer contract versions the runtime accepts |
A published contract is also a tested one. The release gate has to launch representative workloads against the installed release artifact and assert each row at the process boundary, including the refusals: no bus endpoint for a workload that did not ask for one, no access to another workload’s endpoint, malformed and unsupported frame versions refused, missing configuration or credentials refused before the process starts, authority outside the admitted policy refused, the isolation controls observed on the running process, exit and restart behaviour matching the declared lifecycle, and no secret in a log, a process argument, or release metadata.
What the controls do and do not prove
These distinctions hold now and will hold in the published contract. Each one is a control that is easy to read as a stronger guarantee than it is.
- A Unix socket path is routing information. It is not authentication and it does not encrypt traffic.
- A host-assigned endpoint can supply workload identity to a local policy check. That property holds only where another workload cannot acquire or address the endpoint. Test that condition.
- A read-only root filesystem limits writes after launch. It does not authenticate the filesystem bytes; that is what the image’s own signed evidence and its verified root are for.
- File mode
0400limits access by ordinary process credentials. It does not protect a file from the node kernel or a node administrator. - A user namespace, a seccomp filter, a capability set, and a cgroup are container controls. They are not a hardware virtual-machine boundary, which is what a Solo5 tender or Firecracker gives a unikernel.
- A network namespace isolates kernel network state. It does not authenticate or encrypt application traffic.
- Delivering a key file does not say where the key came from, how it was sealed, or whether plaintext copies were removed.
Local development execution is not a flight admission path, and this page will not read as though it were. What admits a workload to flight is the trust root and the admission check the released runtime performs, and the published contract will name both.
