Skip to content

[docs] Rewrite Transparent install flow as shipped architecture, drop phase tags#606

Merged
bdraco merged 1 commit into
mainfrom
docs-strip-phase-tags-and-cert-refs
May 11, 2026
Merged

[docs] Rewrite Transparent install flow as shipped architecture, drop phase tags#606
bdraco merged 1 commit into
mainfrom
docs-strip-phase-tags-and-cert-refs

Conversation

@bdraco
Copy link
Copy Markdown
Member

@bdraco bdraco commented May 11, 2026

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_version handshake (#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

Net: +28 / −30 lines, 0 phase tags remaining in the doc.

Related issue or feature (if applicable):

  • documentation cleanup; no behavioural change.

Types of changes

  • Bugfix (non-breaking change which fixes an issue) — bugfix
  • New feature (non-breaking change which adds functionality) — new-feature
  • Enhancement to an existing feature — enhancement
  • Breaking change (fix or feature that would cause existing functionality to not work as expected) — breaking-change
  • Refactor (no behaviour change) — refactor
  • Documentation only — docs
  • Maintenance / chore — maintenance
  • CI / workflow change — ci
  • Dependencies bump — dependencies

Frontend coordination

  • No frontend change needed
  • Companion frontend PR: esphome/device-builder-dashboard-frontend#

Checklist

  • The code change is tested and works locally.
  • Pre-commit hooks pass (ruff, codespell, yaml/json/python checks).
  • Tests have been added or updated under tests/ where applicable.
  • components.json has not been hand-edited (regenerate via script/sync_components.py if a sync is needed).
  • Architecture-level changes are reflected in docs/ARCHITECTURE.md and/or docs/API.md.

…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.
Copilot AI review requested due to automatic review settings May 11, 2026 20:45
@github-actions github-actions Bot added the docs Documentation label May 11, 2026
@codspeed-hq
Copy link
Copy Markdown

codspeed-hq Bot commented May 11, 2026

Merging this PR will not alter performance

✅ 12 untouched benchmarks


Comparing docs-strip-phase-tags-and-cert-refs (cbef86d) with main (e459c2b)

Open in CodSpeed

@codecov-commenter
Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.21%. Comparing base (e459c2b) to head (cbef86d).

Additional details and impacted files

Impacted file tree graph

@@           Coverage Diff           @@
##             main     #606   +/-   ##
=======================================
  Coverage   99.21%   99.21%           
=======================================
  Files          83       83           
  Lines       10653    10653           
=======================================
  Hits        10569    10569           
  Misses         84       84           
Flag Coverage Δ
py3.12 99.18% <ø> (ø)
py3.14 99.21% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@bdraco bdraco merged commit ddf922e into main May 11, 2026
17 checks passed
@bdraco bdraco deleted the docs-strip-phase-tags-and-cert-refs branch May 11, 2026 20:48
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/ARCHITECTURE.md
* **`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 thread docs/ARCHITECTURE.md
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`) |
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants