docs(k1): record connection mode acceptance

2026-07-19 09:52:33 +03:00
parent 57b2208cae
commit 75d2e5da4b
9 changed files with 131 additions and 22 deletions
@@ -0,0 +1,71 @@
+# ADR 0013: explicit K1 local connection matrix
+
+- Status: accepted for implementation; physical acceptance is mode-specific
+- Date: 2026-07-19
+- Extends: ADR 0004, ADR 0005 and ADR 0012
+
+## Context
+
+Mission Core v0.5.0 exposed only the already accepted shared-LAN path even
+though the product UI named the other XGRIDS connection directions. Retained
+owner-operated evidence establishes two different network ownership models:
+
+- the K1 joins a network whose credentials are sent in the reviewed 99-byte BLE
+  provisioning frame; and
+- the controller joins the K1 access point and then reaches the same local
+  MQTT/RTSP data plane at the observed AP address.
+
+Official workflow notes separately name Bridge, Direct Connect and Quick
+Connect. The names alone do not authorize another BLE command or an inferred
+credential decoder.
+
+## Decision
+
+Plugin v0.6.0 exposes three explicit, fail-closed choices under one exact
+firmware `3.0.2` compatibility profile:
+
+| UI mode | Topology | Device action | Host action | Acceptance |
+| --- | --- | --- | --- | --- |
+| Bridge | `direct-lan` | one reviewed BLE provisioning write | none | physically accepted in Mission Core |
+| Direct Connect | `controller-hotspot` | the same reviewed BLE provisioning write | operator prepares the hotspot and route | implementation complete; physical run pending |
+| Quick Connect | `device-ap` | none | one CoreWLAN scan and association | LixelGO data plane observed; Mission Core host run pending |
+
+Bridge remains the default. Every API request carries both `connection_mode`
+and its exact topology attestation; mismatched pairs are rejected before any
+network action. Acquisition and camera admission must match the active mode.
+The fixed K1 AP address is admitted only after a successful Quick Connect host
+association.
+
+Direct Connect does not introduce a new vendor payload. The operator first
+starts a hotspot on the controlling device and enters that hotspot's SSID and
+password. Mission Core performs the same single, physically reviewed BLE write
+used by Bridge and accepts only the non-AP private IPv4 returned by K1 status.
+
+Quick Connect does not write GATT. A short-lived macOS Swift/CoreWLAN helper
+receives the operator-entered AP SSID and password as bounded JSON on stdin.
+The credential never appears in argv, environment, stdout, stderr, manifests or
+browser persistence. The helper performs at most one scan and one association;
+Mission Core does not retry. The implementation intentionally does not infer or
+read the K1 AP password from an undocumented BLE structure. Until that read has
+its own captured characteristic, bounded decoder and review, the operator must
+enter the AP credentials shown for the owner-controlled scanner.
+
+No connection-verification button emits a probe. It validates only the admitted
+private address; the later canonical MQTT session supplies the real data-plane
+connection attempt. A failed or ambiguous network action remains terminal until
+the operator checks physical state and explicitly starts a new operation.
+
+## Consequences
+
+- The UI now represents all three intended directions instead of disabled
+  placeholders.
+- Quick Connect can temporarily remove the Mac from its previous Wi-Fi network.
+  macOS may require Wi-Fi/location permission for the process running Mission
+  Core.
+- Direct Connect requires an already-running hotspot and a controller route;
+  Mission Core does not create or manage that hotspot.
+- The application-control, START/STOP and raw-first acquisition protocol is
+  unchanged after a target address is admitted.
+- Direct Connect and Mission Core Quick Connect remain explicitly pending one
+  owner-operated physical acceptance cycle each. Offline tests cannot promote
+  those claims.