Engineering archive
These notes describe work at the date shown. See the usage reference for current behavior.
Protocol version 7 — typed task result checks
Date: 2026-09-10. Owner: FLOW (version-only change). Baseline was PROTOCOL_VERSION 6.
Decision
The integrated release uses PROTOCOL_VERSION 7. Typed TaskStatus.reported_checks are persisted and transported on the host status envelope. Client and helper must upgrade together.
v6 is an intentional mismatch, not a compatible reader. Do not claim serde(default) makes old v6 deny_unknown_fields readers accept nonempty reported_checks.
SUPERVISION_VERSION and HOST_LAYOUT_VERSION are unchanged.
Mixed versions
Not every live path is a fresh probe. New submits fail at worker preflight. A persisted task (already on disk, next status/close/lease/submit) is refused at the host request envelope (INCOMPATIBLE_PROTOCOL / decode validate) before task or lease writes. That request mismatch is sufficient; it does not need a second probe first.
| Direction | Behavior |
|---|---|
| New laptop (7) → old helper (6), new work | Probe PROTOCOL_MISMATCH; worker excluded; no subsequent host probe companions (task-status, task-close, lease, submit). |
| Old laptop (6) → new helper (7), new work | Old client’s probe preflight mismatches the same way. |
| Persisted task, mixed versions | Next TaskStatus / TaskClose / lease / submit request carrying version 6 is rejected in validate() before HostStore task or lease mutation. |
| New → new | TaskStatus may omit empty reported_checks; nonempty is valid v7. |
| New reader + old on-disk TaskStatus | Missing reported_checks defaults to empty. Do not rewrite the file for cosmetics. |
PERF combined status-logs uses this same PROTOCOL_VERSION. A fallback for “matching version, unknown optional command” is PERF’s; it must not treat a v6 helper as success.
Upgrade
Run worker setup so every helper advertises 7 before submitting new tasks from a v7 laptop. Existing tasks on mixed versions fail at the next host request, not by rewriting disk.
Persisted identity
JobMeta and RequestFingerprintMaterial store protocol_version inside hashed / durable records. Wire mutations stay strict (== 7) before job/lease/task writes. Stored identity may be 6 or 7; Deserialize/validate() on those types use the stored set and never rewrite fingerprint/protocol fields.
Baseline6 material hash at faf6eff: cb742b77e5c252a02510cc149e5bc7f7f73b51b4e521db373c1d5250227e4eac. Rewriting the same fields to protocol 7 changes the hash to 990f1f062a3423f154615f89d0754726ef9fdc8797434bdde5ca739b9716935d.
- Reconstruct with
RequestFingerprintMaterial::from_stored. - Non-terminal v6 jobs are not adopted (
INCOMPATIBLE_PROTOCOL); drain them on the previous helper. - Terminal v6 archives, including a genuine
JobDisposition::Acceptedindex, remain readable and are idle-upgrade success.
Helper promotion is HostStore::complete_protocol_upgrade (same construction lock through inspect, rename, layout and installation-identity refresh). See /private/tmp/mac-worker-roadmap-jn00iibh/upgrade-promotion-contract.md.
SUPERVISION_VERSION and HOST_LAYOUT_VERSION stay 3 / 2; this is not a layout migration.