NODEDC_MISSION_CORE/docs/adr/0013-k1-local-connection-matrix.md

# ADR 0013: explicit K1 local connection matrix

- Status: amended 2026-08-08; Bridge is the product path, Quick Connect retained as a prepared-host laboratory path
- 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` | one fixed reviewed 100-byte AP-enable write | preinstalled exact-firmware credential provider, bounded exact-SSID discovery and one association | physically accepted on one prepared Mac; not portable bootstrap |

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.

Bridge and Direct Connect do not have a fixed product IP. The address reported
by BLE characteristic `7f02` is a DHCP lease observation scoped to the current
connection, never device identity and never a durable configuration value.
Before a new application-control session, an implicit-host acquisition, or a
factory-calibration read, Mission Core performs one read-only `7f02` read for
the selected CoreBluetooth device and replaces the previous target. An address
change creates a new `device_session_id` and invalidates calibration captured
for the previous session. An active acquisition is never retargeted in place.
The later correlated MQTT `DeviceInfo` response supplies model, firmware,
serial and vendor identity; IP equality alone cannot identify a K1.

The 2026-08-08 physical Bridge trace corrected the earlier field model: the
first `7f02` text slot is `WIFI_AP` in AP state but contains the joined network
name in FW 3.0.2 station state. Mission Core therefore normalizes that station
response to `WIFI_CLIENT` internally and admits Bridge/Direct only when the raw
post-write name exactly matches the current explicit request plus a valid
non-AP private address. The raw name is not persisted in the secret-free
network audit or published through API state.

The limitation still applies when recording an interrupted attempt that has no
exact post-write network-name observation. A changed private DHCP address alone
cannot identify the selected network. An already AP-ready baseline likewise
cannot prove the outcome of an interrupted Quick-to-Quick attempt. Mission Core
therefore records that attempt as terminal `outcome-unknown` and never replays it automatically. The
historical uncertainty is not a permanent barrier: after the old active
operation and cleanup have ended, a later explicit operator scan, selection,
and connect is a distinct session with its own one reviewed write.

Product decision on 2026-07-20: Bridge/direct-LAN is the continuing route.
Quick Connect remains visible and executable on an already prepared host, but
is not a deployment dependency or portability claim.

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 accept a credential from the browser/API. The first
implementation incorrectly jumped from BLE discovery directly to host Wi-Fi
association. A physical negative run showed that the selected K1 was still on
the existing LAN and the expected AP was not visible. Re-review of the exact
LixelGO branch recovered the missing state transition: after BLE connection it
writes one 100-byte `7f01` frame, zero except for `0x01` at offset 99, and treats
the callback as the AP-launch result before invoking the OS Wi-Fi connector.

Mission Core now performs that bounded AP-enable write at most once. The first
physical run reached `WIFI_AP` at the reviewed AP address, and a targeted
CoreWLAN scan found the SSID matching the selected BLE advertised name. It also
disproved the earlier assumption that LixelGO carried one global Quick Connect
profile: retained client analysis exposes `WiFiAP_SSID` and `WiFiAP_Password` as
fields of each device record.

A subsequent run found that `7f02` may retain `WIFI_AP / 192.168.56.1` after the
SSID stops beaconing. Static review then recovered the missing discriminator:
LixelGO maps response byte 51 to its AP-ready flag and waits up to 15 seconds for
that flag. Mission Core therefore mirrors LixelGO: every new operator Quick
Connect action emits exactly one reviewed enable frame, including from a
`WIFI_AP` baseline, and admits host discovery only after byte 51 becomes
non-zero. This is not an automatic retry.

The same review proved that LixelGO does not close its BLE manager between the
AP-ready callback and native Wi-Fi connect. A failed Mission Core run had done
exactly that: byte 51 changed from zero to one, the Python BLE context exited,
and the following cold Swift/CoreWLAN process missed the beacon. The corrected
implementation holds the selected `BleakClient` open through bounded native
SSID discovery and the single association call.

One explicit six-second BLE discovery and the later Apply action form one
operator intent without a second discovery. A physical run proved that
immediately rediscovering the same K1 by its CoreBluetooth UUID can fail even
though the preceding scan exposed it. Mission Core retains the non-serializable
`BLEDevice` handle process-locally and uses that exact handle for Apply; it never
exposes the handle through API state or treats the macOS UUID as durable device
identity. UI row selection itself performs no GATT or backend I/O.

The operator-visible candidate list, local selected draft and admitted active
session are separate contracts. Every explicit scan replaces the candidate
set. Selection only binds a local form to one result from the latest admitted
generation. Wall-clock age does not remove that generation while the operator
completes the form. Apply admits only its exact retained handle and live GATT
validation may create the active session; a remembered UUID is never mutation
authority. Proven disconnect, explicit stop, app/backend restart, another
explicit Scan, or a committed mode transition revokes the applicable candidate
or live session. Rediscovery never auto-connects.

Quick Connect to Bridge is an explicit topology transition, not another scan
heuristic. Selecting Bridge — or choosing another K1 while Bridge is already
selected — sends one idempotent local `reset_scenario` CAS. It seals retained
receiver/camera/control ownership, invalidates candidates and credentials and
retires old physical lineage truthfully, while sending no device command, BLE,
host-network write or automatic Scan. The next explicit Scan starts the clean
discovery flow, while Apply remains the topology and device-mutation boundary.
The operator selects one discovered K1, sees the Bridge credentials immediately
and submits once. The new GATT
session reads internal baseline `7f02` and emits exactly one reviewed 99-byte
station write. A connect failure ends that attempt. An ambiguous post-write
failure is terminal `outcome-unknown` audit, not a permanent cross-session
fence. There is no automatic BLE or network-write retry.

Likewise, an exact REST `network_applied` result with unready/unknown control
spends that Apply and its credentials without making the read-model attempt a
permanent topology lock. Recommended Verify is pinned to the backend
current/configured target. A separately explicit new intent still requires
current server policy: Bridge prepares `select-device` before a later fresh
scan; Quick and Direct run an admitted fresh scan, select only its latest row
and create a new idempotency Apply; a mode or same-mode new-device transition
uses one idempotent local-only `reset_scenario` before that fresh scan. None of
these new-intent UI paths reuses the old
intent or runs as a hidden frontend/mutating continuation. The service-owned
same-intent read-only bootstrap declared below is the sole post-ACK exception.

The Apply REST call returns as soon as the exact durable
`network_applied` proof is available. The service may continue the same
intent's supervised control bootstrap read-only after that ACK. This performs
no BLE/host mutation or retry and creates no frontend Verify, Scan, Apply or
blocking Apply loader. While the exact child is accepted/running, the UI may
show only a passive **Сеть настроена · подтверждаем управление** indicator and
must keep every recovery action disabled. Later control state arrives only as
backend presentation convergence; terminal unready/unknown state then exposes
the explicit server-policy recovery choices.

Bridge and Quick Connect were physically accepted as separate paths before
this amendment. The combined Quick Connect to Bridge transition has automated
contract coverage but remains a distinct physical acceptance gate; it must not
be reported as field-accepted until one redacted live run records both sides of
the transition.

Quick Connect Apply is an exact idempotent ensure-target operation when the
selected K1 already reports the canonical AP-ready state. Mission Core accepts
that unchanged state only after the one reviewed write-with-response is
durably confirmed, then performs the normal exact device-SSID host association.
An unconfirmed or merely read-only unchanged observation remains fail-closed;
this rule neither retries the BLE write nor weakens Bridge admission.

The corrected host boundary derives a non-secret, device-scoped profile ID from
the selected SSID. The reviewed client contains per-device `WiFiAP_SSID` and
`WiFiAP_Password` fields, but the 2026-07-20 review of the exact official K1
`3.0.2` firmware recovered their upstream source: the scanner's bundled
NetworkManager AP script assigns one firmware-constant WPA2 material, while
`lixel_nman` constructs `XGR-` plus six device-identity characters with a MAC
fallback. It is neither an iPhone credential nor a per-device secret.

The laboratory implementation can install a firmware-scoped credential source from the
authenticated official archive. The offline importer validates the exact
SHA-256, streams the bounded application-partition range, requires one valid AP
declaration and writes the value to the OS secure store through helper stdin.
On macOS, the Keychain helper materializes the selected device profile from
that opaque source before any BLE write. A missing provider fails closed. The
browser, API, argv, logs, manifests and evidence never receive the secret; the
importer's short-lived mutable buffer is zeroized after the Keychain handoff.

The 2026-08-06 field regression established that process identity is part of
this prepared-host contract. Runtime `swiftc` compilation produced an ad-hoc
helper with an unstable designated identity. macOS then requested Keychain
authorization repeatedly and the same process context failed to expose the
exact K1 SSID through CoreWLAN even after K1 had acknowledged AP-ready. That
runtime-compiled route is rejected. The laboratory adapter uses the previously
physically accepted Apple-signed interpreter path,
`/usr/bin/xcrun swift <reviewed-source>`, and validates the source path before
launch. A portable product implementation still requires a packaged,
precompiled and properly signed helper with a stable bundle identifier,
designated requirement, Location/CoreWLAN authorization and Keychain ACL; the
current prepared-host path does not claim that packaging work is complete.

Before any BLE write, the helper's preflight is non-interactive. It first checks
Keychain item existence through metadata, then validates the selected profile's
SSID and `exact-firmware-profile` provenance inside the helper without returning
secret data. Provider material is also read with interaction disabled if a
missing device profile must be materialized. The association phase accepts only
that already materialized exact profile. It never
falls back to the system Wi-Fi Keychain, rewrites a profile opportunistically,
or opens a password/authorization dialog after K1 has changed network state.
An unavailable or unauthorized profile therefore fails closed with a precise
reason code and no automatic device retry.

The host-network boundary, rather than the XGRIDS frontend, owns platform
association. Browsers expose no Wi-Fi join API, and Apple's iOS
`NEHotspotConfiguration` consent flow is unavailable on macOS. The current
implementation therefore uses a short-lived Swift/CoreWLAN + macOS Keychain
helper; Windows Credential Manager and Linux Secret Service adapters remain
separate platform work. The helper performs repeated read-only exact-SSID scans
inside one 30-second discovery window and at most one association. The larger
window covers the physically observed 18.142-second beacon-discovery case;
AP-ready confirms K1 state but does not prove that macOS has already observed
the RF beacon. It never
repeats the BLE command, guesses a password or treats `7f01` as a credential-read
command. The credential-bearing 99-byte station-provisioning frame and fixed
100-byte AP-enable frame are separate reviewed payloads.

No reviewed BLE characteristic or response supplies the AP credential. That
does not prove a universal negative for every vendor build, but it means the
current plugin has no evidence-backed device-side credential acquisition path.
The owner also observed no explicit device/account pairing in the normal
LixelGo onboarding flow; this is consistent with a firmware-defined AP secret,
but does not establish account-wide authorization for arbitrary scanners.

Apply may read BLE baseline internally while establishing a new selected
session. Selection never does so, and the normal flow has no mandatory or hidden
"verify without write" recovery step. The baseline read does not re-provision
Wi-Fi, scan the subnet, change a host route, or touch VPN configuration. The
later canonical MQTT
session supplies the real data-plane connection and live `DeviceInfo` identity
check; BLE status alone is not a claim that MQTT/RTSP is reachable.

## Consequences

- The UI now represents all three intended directions instead of disabled
  placeholders.
- Quick Connect can temporarily remove the controlling host from its previous
  Wi-Fi network. The operating system may require Wi-Fi/location permission.
- A new host needs a separate exact-firmware provider installation. The current
  application does not obtain it from BLE and does not bootstrap it by itself.
- Automatic firmware download, iPhone extraction and hard-coded credential
  delivery are explicitly rejected product routes. Windows/Linux adapters are
  therefore not scheduled for this Quick Connect path.
- Direct Connect requires an already-running hotspot and a controller route;
  Mission Core does not create or manage that hotspot.
- Discovery never auto-connects devices. Mode, selection and input are local
  only. App restart, disconnect, explicit stop and mode transition require a
  fresh explicit scan-select-Apply session. Apply performs no hidden rescan or
  Verify and may cross at most one device-mutation boundary.
- The application-control, START/STOP and raw-first acquisition protocol is
  unchanged after a target address is admitted.
- Direct Connect remains explicitly pending one owner-operated physical
  acceptance cycle. Quick Connect AP activation and host association are
  physically accepted only on the prepared K1/FW 3.0.2 Mac stand. Bridge is the
  only accepted portable product path in this matrix.