20260916 - Ask the owner how we can reach them

[Purple10101]

Collects the owner's contact details for PUT /v1/nodes/contact, which arrived in node ingest spec v1.2.0 and gained a phone country in v1.2.2. Nothing on a node holds any of it today, so retina-telemetry has nothing to send until this lands. Same ordering the consent records went through.

The retina-telemetry half is offworldlabs/retina-telemetry#18. They are independent: that side treats an absent contact document as a complete answer, so neither breaks the other whichever way round they merge. This one first is the sensible order, because the feature only does anything once this is deployed.

Two surfaces, one route

A wizard step straight after the agreements step, so it is asked while the owner is still answering questions about themselves rather than about the radar. Plus a block under Remote support on the Configuration page for adding or amending it later. Both post to /set-up/contact, because handing them separate handlers is how two surfaces start storing different shapes of the same thing.

Under Remote support rather than a section of its own: those settings are how support reaches the node, and this is how they reach the owner.

Optional throughout, and that is the steady state

The spec is explicit that a node with nothing to report never calls the endpoint at all. So Skip is a real button rather than an escape hatch, and an absent file is how the node says it has nothing.

Clearing works, by doing less rather than more

A blank box is simply not written, and a document with nothing left in it removes the file. Skipping the step and emptying every box converge on the same state. The Save button says Details removed rather than Saved in that case: claiming to hold details we have just deleted would be the one confusing outcome here.

The endpoint replaces its document wholesale, so this end replaces rather than merges and the two cannot disagree about what is held.

Storage

/data/retina-gui/telemetry-contact.json, a cross-repo contract like the consent file, and deliberately not inside it. Those are versioned acceptances neither end may invent, and retina-telemetry refuses to register without all three; a mutable optional document sharing that file would let a malformed contact stop a node registering.

The shape mirrors the wire's NodeContact one-for-one, so nothing is translated between what the owner typed and what the server is told.

Notes for review

• The caps are the spec's, commented as such beside TX_NAME_MAX_LENGTH's for the same reason: a value past one of them means retina-telemetry cannot build the payload, so the whole document is refused and the owner is never reachable.
• country is checked in the route, not the model. It is ISO 3166-1 alpha-2 and belongs to the phone number rather than to the owner, which is what the server asked for. The check sits in the route because regex= is pydantic v1 and pattern= is v2; nodes run v1 and CI runs v2, so a constraint spelled either way breaks one of them.

Verification

920 tests pass (24 new), ruff and vulture clean.

Verified end to end on owl-ded9 by deploying this branch to the node, posting through the real endpoint with a real CSRF token, and confirming the file landed at the real path with gb normalised to GB. retina-telemetry then read that file and sent all five fields. The node was restored to v0.8.0 afterwards.

🤖 Generated with Claude Code