D2 JSON MACHINE MODE
The macOS driver starts the forked asahi-installer with --json. The two
sides then send newline-delimited JSON. This repository owns this contract.
The implementation and its unit tests are in the backend revision that
scripts/test-backend-contract.sh pins.
Framing and routing
- Installer output is one JSON object per line on stdout. Blank lines are harmless. Stderr is for diagnostics only.
- The driver sends exactly one JSON answer for the most recent
askevent:{ "id": "...", "value": ... }. - Only one ask is outstanding. The driver must match the answer by
id, not by the order of arrival. It must not answer an old request after a retry. - The backend validates each answer. The driver must show the messages from the backend. It must not have a second parser for APFS or size values.
Events
Progress and output for the user:
{"event":"message","level":"progress","text":"..."}
Questions use these kind values: input, password, continue, yesno,
choice, and size. Each question has an id and a prompt. A choice
question also has options and an optional default. A size question has
the min, max, and total bounds in bytes. A size answer uses the backend
grammar (for example 50%, 20GB, or max). Thus the bounds have one owner.
The last protocol event is exactly one result. The backend sends no JSON
event after it:
{"event":"result","status":"success","efiPartUuid":"..."}
{"event":"result","status":"failure","kind":"process","reason":"..."}
{"event":"result","status":"aborted","reason":"..."}
The driver reports success only when the last status is success and the
subprocess exits zero. A missing result, a non-zero exit, or a different last
status is a failed install. aborted means that the user stopped the install.
It is never a success. The EFI PARTUUID is the stable handoff to the
first-boot agent. A macOS device name must not cross this boundary.
A CI check at the process boundary causes a failure in the constructor. Then it makes sure that the backend sends one failure result and no stdout that is not JSON. The result must be the last event, and the exit code must not be zero. This check finds a driver race or a backend exception handler that can make a partial run look complete.
Compatibility and safety
The default TTY mode does not change. The backend does these steps: APFS resize, partition creation, firmware extraction, m1n1 preparation, and bless. The driver only shows events, collects answers, and reads the last result. CI pins and checks the contract. If an event field or result rule changes and the driver does not, the UI can show "installed" for an install that failed.
The full diskutil/bless/bputil path still needs a real Mac with Apple Silicon. Linux CI proves the protocol layer and the behavior of the last result after an injected failure. It does not prove a hardware install.