[docs] Rewrite Transparent install flow as shipped architecture, drop phase tags#606
Merged
Merged
Conversation
…tags
The Transparent install flow section read as a roadmap: every
subsection was framed as an in-flight implementation slice
("Slice 7a-1 — landed", "Slice 7a-2a — open", "Implementation
slice 7b — this slice"). Every slice in the plan has shipped
(BuildScheduler #553, esphome_version handshake #557,
FirmwareJob.source #556, synthetic-job framing reversal #558,
source-routed runner #560, install-handler integration #568,
e2e coverage #573, offloader settings backend toggles #574,
compile->upload seam progress reset #580); issue #106 is
closeable. Convert the section to present-tense architecture
prose describing what runs, keep PR refs for traceability,
and replace the "Not yet implemented" subsection with a
one-line note that force-fallback + allow-major-version-
mismatch land through normal bug-fix process.
Strip phase-prefix annotations (5b / 5c-2a / 5c-2b / 5c-3 /
5d / 6a / 4a-r1 / 4a-o / 7a-N / 7b / 8a / 8b / phase 3a) from
the wider Remote build section's receiver and offloader
dispatch paragraphs, the endpoint-rebind subsection, the
listener-internals identity bullets, and the cert/key state.
The function and shape descriptions stay; only the planning-
doc shorthand goes. PR refs (#539, #548) remain.
Drop the cert + key entries from the persisted-state table.
The cert files are gone in code — tests explicitly assert
`(tmp_path / ".device-builder-cert.pem").exists()` is False
and the same for `-key.pem` (test_dashboard_identity.py:242,
test_remote_build_controller.py:1678). Update the backup-
tools paragraph to reference `.device-builder-peer-link-key
.bin` + `rotate_identity` instead of the cert key +
`rotate_certificate`.
Net: +28 / -30 lines, 0 phase tags remaining in the doc.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #606 +/- ##
=======================================
Coverage 99.21% 99.21%
=======================================
Files 83 83
Lines 10653 10653
=======================================
Hits 10569 10569
Misses 84 84
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
Contributor
There was a problem hiding this comment.
Pull request overview
Updates docs/ARCHITECTURE.md to describe the shipped remote-build / transparent-install architecture (rather than a phased roadmap), removing phase-tag annotations and reflecting the current persisted identity/state layout.
Changes:
- Rewrites the “Transparent install flow” section into present-tense architecture prose and removes “in-flight”/phase-slice framing.
- Removes phase-tag parentheticals across the remote-build section and simplifies some historical context.
- Updates identity + persisted-state documentation to drop the legacy cert/key files and focus on the X25519 peer-link identity.
| * **`dashboard_id`**: a stable random identifier under `_remote_build.dashboard_id` in the metadata sidecar. Load-bearing as the offloader-presented identity on every Noise pair_request / peer_link / pair_status frame; the receiver pins against `pin_sha256` (below) and uses `dashboard_id` as the bookkeeping key. | ||
| * **Peer-link X25519 keypair**: a 32-byte raw X25519 secret persisted at `<config_dir>/.device-builder-peer-link-key.bin` (0o600). This is the keypair the Noise XX handshake exchanges; `pin_sha256` advertised in mDNS TXT is the lowercase-hex SHA-256 of the static pubkey. Loaded once at handler-factory time and captured in the Noise dispatch closure for the listener's lifetime; rotation rebuilds the listener. | ||
|
|
||
| The TXT contract — `pin_sha256` + `remote_build_port` appear together iff the listener is currently bound — holds across rotation. When the listener isn't bound, rotation only writes new keys to disk; mDNS isn't updated because there's no listener for peers to connect to. |
Comment on lines
439
to
440
| | `.receiver_peers.json` | Receiver-side pinned offloaders (`StoredPeer` rows: `(dashboard_id, pin_sha256, static_x25519_pub, label, paired_at)`). Owned by `helpers.storage.Store` with debounced writes; only APPROVED rows ever reach disk (PENDING lives in `_pending_peers` and is bounded by the pairing window). A reader can enumerate which `dashboard_id`s have paired with this receiver, but neither pin nor pubkey is secret on its own. | 0o600 enforced at write time (default for `Store`) | | ||
| | `.offloader_pairings.json` | Offloader-side pinned receivers (`StoredPairing` rows: `(receiver_hostname, receiver_port, pin_sha256, static_x25519_pub, label, paired_at, status)`). Owned by `helpers.storage.Store` with debounced writes; only APPROVED rows ever reach disk (PENDING is filtered out at serialise time). Same secret-equivalent shape as the receiver's `.receiver_peers.json`: a reader can enumerate which receivers this offloader has paired with, but neither pin nor pubkey is secret on its own. | 0o600 enforced at write time (default for `Store`) | |
This was referenced May 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this implement/fix?
Rewrites
docs/ARCHITECTURE.md's Transparent install flow section as shipped architecture rather than a roadmap, and strips planning-doc phase tags (5b, 5c-2a, 5c-2b, 5c-3, 5d, 6a, 4a-r1, 4a-o, 7a-N, 7b, 8a, 8b, phase 3a) from the wider Remote-build section. Also drops the now-removed cert + key files from the persisted-state table.Every slice in the original issue #106 plan has shipped —
BuildScheduler(#553),esphome_versionhandshake (#557),FirmwareJob.source(#556), synthetic-job framing reversal (#558), source-routed runner (#560), install-handler integration (#568), e2e coverage (#573), Settings backend toggles (#574), compile → upload seam reset (#580). Open follow-ups ("force fallback to local", "allow major-version mismatch") land through the normal bug-fix process from here. The doc should reflect that — readers don't need to decode planning-slice shorthand to understand how the code actually runs.Notable changes
### Transparent install flow— six "Slice 7a-N / 7b" prescriptive paragraphs collapsed to present-tense architecture prose. PR refs kept for traceability (Add BuildScheduler primitive (7a-1) #553, Add FirmwareJob.source / source_label fields (7a-2a) #556, Drop synthetic-job / event-stream-bridge framing for 7a-2+ #558, Source-route firmware runner on JobSource.REMOTE for compile (7a-2b) #560, Route firmware/install through pick_build_path + REMOTE upload chain (7a-3) #568, Add e2e tests for 7a-3 install scheduler routing + dual-flow round-trip #573, Add 7b backend: per-pairing enabled + master remote_builds_enabled toggles #574, Reset firmware-job progress at compile→upload seam on REMOTE installs #580). "Not yet implemented" subsection replaced with a one-line note on the deferred items.(5b — …),(5c-2a — …),(5c-2b — …),(5c-3 — …),(5d — …),(6a — …)annotations stripped from parentheticals; functional descriptions unchanged.(4a-o part 7, #539)→(#539),(8b, #548)→(#548), "8a re-auth wizard" → "re-auth wizard".dashboard_idbullet withdashboard_id+ X25519 peer-link keypair only. The cert is gone in code..device-builder-cert.pemand.device-builder-key.pemrows. The files aren't written anymore; tests attests/test_dashboard_identity.py:242-243andtests/test_remote_build_controller.py:1678-1679explicitly assert their absence. Backup-tools paragraph now references.device-builder-peer-link-key.bin+rotate_identity.Net: +28 / −30 lines, 0 phase tags remaining in the doc.
Related issue or feature (if applicable):
Types of changes
bugfixnew-featureenhancementbreaking-changerefactordocsmaintenancecidependenciesFrontend coordination
Checklist
ruff,codespell, yaml/json/python checks).tests/where applicable.components.jsonhas not been hand-edited (regenerate viascript/sync_components.pyif a sync is needed).docs/ARCHITECTURE.mdand/ordocs/API.md.