Establish watch relay contracts and platform package wiring

2026-09-18 09:34:26 +04:00
parent a92698e1e6
commit 9b87299bf5
22 changed files with 778 additions and 159 deletions
@@ -21,6 +21,8 @@ The coordinating engineer is the integration owner. Agents implement focused bra

 Package paths in the table mean `Packages/WristivoKit/Sources/<module>` and `Tests/<module>Tests`. A new adapter needs tests in an adjacent Tests directory; integrator creates target membership before the implementation branch starts. QA may run acceptance planning immediately, but must not edit another agent's tests or report planned cases as passed.

+**B prerequisites are now established.** Follow [the Watch relay handoff](WATCH-RELAY-HANDOFF.md): frozen session DTOs/codec/actor protocol live in RemoteCore/WatchSession.swift; the adjacent WatchBridge package provides three source/test targets and its platform products are linked to the apps. B works in a separate worktree, uses a fake actor until A is integrated, and does not need to take over the integration role. Adapter Package.swift files, dependency changes and Xcode project wiring remain integrator-owned; new Swift source/test files within existing target paths are B-owned and automatically included.
+
 ## A — TV transport prompt

 > Implement an iPhone-only TV connection actor and pure bounded event parser. Use SamsungRemoteEncoder without copying a community implementation. Support explicit connect/pair/deny/timeout/revoke/disconnect, authorize before ready, serialize commands, consume admission once, recheck deadlines before sends, and cancel old-generation operations on TV/session changes. Integrate injected token/trust storage from E. No blanket TLS trust, arbitrary key API, silent plaintext fallback or replay on reconnect. Use synthetic redacted event fixtures for malformed/oversize/unknown/missing-token responses and fake socket tests for deadline, ordering and cancellation. Deliver a manual physical pairing script showing the name Wristivo, reconnect and revoke. Do not mark the TV compatible until the owner runs it. Begin with a hardware feasibility spike for the candidate endpoint and TLS policy before expanding UI dependencies.
@@ -0,0 +1,28 @@
+# Watch relay — integration prerequisites ready
+
+Scope: shared seams and compile/test membership. This is not a completed relay or a hardware verification.
+
+## Instructions for B
+
+Use the dedicated `feat/watch-relay` worktree prepared by the integrating engineer. Do not switch the original TV-transport checkout or edit shared contracts/project files. The integration commit in this worktree supplies all prerequisites below. A branch name alone does not isolate work: separate working directories are required when multiple agents run.
+
+1. Read RemoteCore/WatchSession.swift and docs/CONTRACTS.md for exact types and semantics. The historical proposal's method signatures have been superseded.
+2. Implement only Adapters/WatchBridge sources/tests. All three target memberships already exist and discover new Swift files automatically. The package manifest and Xcode generator remain integration-owned; ask only for an actual dependency/target change, not ordinary new source files.
+3. Use PhoneCommandCoordinating through a fake actor while A implements production conformance. B owns WCSession activation, facades, live delivery, bounded containers, routing, timeout and reply-once handling. A/integration owns the sole authorized session/admission/TV-dispatch actor.
+4. Use RelayJSON for all payloads; no default JSON date coders. Control DTO validation does not replace command admission. Match command receipt IDs and expected reply kinds. A timeout or an old-generation reply never retries an action or re-arms input.
+5. Establish and capture a fresh local WatchPeerGeneration for each phone bridge activation. Deliver lifecycle changes in order and await activation before forwarding requests. Pass that peer on every actor call. Never accept a peer ID from wire data or put it in application context.
+6. Keep OS APIs behind injectable facades and platform guards. Test fake behavior on macOS without subclassing WCSession; compile real delegates on each native SDK. Do not start WCSession or change the demo app behavior at module import.
+
+## Required B tests
+
+Exactly-once completion on success/error/timeout races; stale callback after deactivate/reactivate; ignored delayed begin grant/end acknowledgement; unreachable and unactivated session; wrong kind/version/types/extra keys; Bool-as-version rejection; 4096/4097-byte boundary; malformed/unknown payload; receipt ID mismatch; bounded pending requests; expiry while waiting; no replay after reconnect; application-context allowlist excludes tokens, raw motion and commands. Validate phone/watch counterpart replacement and reinstall recovery with fakes first.
+
+Run `bash Scripts/check.sh`. The integrator also runs both app builds before merge. Hardware testing of locked-phone wake, relaunch, actual reachability and detached-debugger lifecycle remains unperformed and mandatory before feature completion. Do not block fake-driven implementation on access to a TV.
+
+## Responsibilities for A/integration
+
+Implement PhoneCommandCoordinating on the single existing/new TV command actor, validate caller and peer lifecycle, require a ready selected TV for a grant, and make stale end/deactivation harmless. Test actor reentrancy and recheck all state before socket writes. Do not forward an admitted command into another consuming admission gate. The storage/TLS proposal from A is outside this relay-prerequisite patch and remains separate integration work.
+
+## Delivery
+
+Return a branch/commit, focused test evidence, explicit native compilation status, documented errors and remaining hardware gates. Do not push main. The user is handling remote pushes; this prerequisite change does not push anything.