[frahlg]

Step C6 of ADR 0008. FTW Cloud keeps the last 48 hours of 5-minute history for each home whose owner turned it on. The iPhone app can then draw a node's history while the box cannot answer.

Paired with srcfl/ftw-cloud#48 (the service) and srcfl/ftw-app#98 (the app). Merge this first. ftw-cloud pins go/protocol at this branch's b10a6939 and then moves the pin to the merge commit.

What changes

Wire: go/protocol/cloudwire and docs/protocol-cloud.md

• tiles is the app protocol's hist.chunk plus the common header, at 5 minutes and stride 1. It carries grid_w, pv_w, battery_w and load_w, in the order the app asks for them over Noise. A closed tile therefore has the same tile id, etag and bytes as the box serves over Noise.

• A tile has one of three shapes:

  • closed: the whole tile;
  • whole: the filling tile, with every point, missing from the first bucket still open;
  • append: only the buckets that closed since the last piece.

  Tiles.Check enforces the shapes, Piece cuts a piece and Lay puts pieces back together.

• A phone sends tiles.get {have}. The service answers with the box's envelopes the phone lacks, then tiles.end {n}.

• cloud-tile-vectors.json holds:

  • one tile of each shape, signed by the vector box key, and one forged tile;
  • five Lay results;
  • the tiles.get and tiles.end bytes.

  ftw-cloud and the app replay these vectors.

• docs/protocol-cloud.md now covers:

  • a field table under tiles, so TestFieldsMatchTheProtocolDocument checks it;
  • when the box sends tiles;
  • hello_ok.have;
  • resync {what: tiles};
  • that the snapshot carries no tiles;
  • that tiles outlive the hour of silence;
  • the service's bounds;
  • new rows in the numbers table.

• ADR 0008's store table gets a row for tiles.

Core: internal/cloudlink and cmd/ftw

• The link sends tiles only with ftw.history.read in the grant and NTP time. It counts a bucket closed 30 s after it ends, once the history writer has committed it.
• As each bucket closes, the link sends the filling tile as an append. It sends the tile whole instead the first time on a connection, and after 11 appends. When the tile's last bucket closes, the tile goes closed.
• At connect and after a resync, the filling tile goes whole. Every closed tile of the last 48 hours that hello_ok.have lacks goes too, newest first.
• Every hour the link packs the closed tiles again and sends any whose etag changed, so a gap the ledger repaired reaches the service.
• The link reads the ledger through the same appHistory.Window and protocol.PackTile as the Noise path.
• Tiles go last in a tick and count against the 20 MB copy budget, at about 100 KB a day. The 250 MB tunnel budget is separate and unchanged.
• hello.caps lists tiles when the grant allows them.

Decisions to look at

• Tiles outlive the hour of silence. The doc said the service serves no readings an hour after the box goes quiet. Tiles now stay 48 hours whatever the box does. They are dated history, and C6 exists for a box that is away. A phone still needs a roster in force to get in, which lasts 24 hours from the box's last roster.
• Assistants still read history from the box (open question). The protocol says an agent row never reads the readable copy, so every agent read is one the box audits and a revoke stops. That rule stays. While the box is away, MCP's history_query now says so and says when FTW Cloud last heard from it (feat: hold 48 hours of history tiles and answer tiles.get (C6) ftw-cloud#48). Should it instead answer from these tiles? That would change the rule, and the box would not see the read. It is not built; it is the owner's call.
• No ev_w or battery_soc. The box's history serves four series today. The old text said C2 adds the other two, but C2 did not.

Tests

• make verify passed: tests, vet and build.
• go test ./cloudwire covers the shapes, Noise equality, what Check refuses, Lay and the vectors.
• go test -race ./internal/cloudlink covers these cases:
  • at connect, the whole tile and the closed tiles go, each as Noise would serve it;
  • each closed bucket goes as an append until the tile goes whole again;
  • a tile goes closed when its last bucket closes;
  • have saves the service's tiles;
  • a resync sends tiles again, once in five minutes;
  • a reconnect sends what the service lacks;
  • the hourly pass resends a repaired tile;
  • no tiles go without the history scope, without NTP or past the budget;
  • a failing ledger holds tiles back and nothing else.
• End to end on a laptop: This branch's Core, built with a local endpoint and two simulated drivers, linked over QUIC to ftw-cloud's branch feat/c6-tiles. At connect the box sent the filling tile whole and the four closed tiles of the last 48 hours. They were empty, since that box's ledger was new. At 14:25:30 UTC it sent a one-point append for 14:20–14:25 with the measured values. A small checker read what the service held from /dev/held. Every tile verified with the box key and passed Check, and Lay rebuilt the filling tile through 14:25. Nothing touched the home box, the FTW Cloud host or AWS.

After review

• Check takes the four series and no other, derived from the registry's names. TileEnvelopeMax (4 KiB) bounds an envelope, so a box cannot pad its tiles.
• When ftw.history.read leaves the grant, the link forgets what it sent. When history comes back, every tile goes again on the same link (TestHistoryTakenOutAndPutBackSendsEveryTileAgain).
• The link reads the ledger at most once per tick, one closed tile at a time. It checks the grant again before each tile goes.
• A later closed tile replaces an earlier one in Lay.
• cloudlink.PackTile is the one packing path. TestACloudTileIsTheNoiseTile holds it to the Noise tile through appproto's real buildTile.
• The doc now says what a phone really gets. While the box is away, a phone can read tiles only until the roster runs out, 18 to 24 hours. Each tile is kept until 48 hours after it ends, so up to 60 hours of history. FTW Cloud sends resync for tiles when a roster gives history back or room frees.
• make verify passes again.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-23T14:28:19.479007Z	50bb116	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 50bb116904

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".