From 75d2e5da4b997c12e4c518a3a004ebbe3294bd80 Mon Sep 17 00:00:00 2001 From: DCCONSTRUCTIONS Date: Sun, 19 Jul 2026 09:52:33 +0300 Subject: [PATCH] docs(k1): record connection mode acceptance --- README.md | 12 +++- apps/control-station/README.md | 6 +- docs/01_IMPLEMENTATION_PLAN.md | 3 +- .../0012-device-bound-k1-command-authority.md | 5 ++ docs/adr/0013-k1-local-connection-matrix.md | 71 +++++++++++++++++++ ...NICAL_CONTROL_ARCHIVE_20260719.redacted.md | 6 +- plugins/xgrids-k1/README.md | 19 ++++- plugins/xgrids-k1/frontend/README.md | 7 +- plugins/xgrids-k1/profiles/README.md | 24 ++++--- 9 files changed, 131 insertions(+), 22 deletions(-) create mode 100644 docs/adr/0013-k1-local-connection-matrix.md diff --git a/README.md b/README.md index be2402a..17d069c 100644 --- a/README.md +++ b/README.md @@ -130,7 +130,8 @@ uv run k1link serve Open `http://127.0.0.1:8000`. The static application, REST/WebSocket control plane and credential endpoint bind to loopback only. The current K1 adapter still provides real CoreBluetooth discovery, one operator-triggered reviewed -BLE Wi-Fi provisioning write, read-only MQTT live capture, native `.k1mqtt` and +BLE Wi-Fi provisioning write, a one-shot CoreWLAN K1-AP association path, +read-only MQTT live capture, native `.k1mqtt` and reviewed-TSV replay, raw-first evidence storage, device-reported scan time/distance/speed and measured preview metrics. Its frontend contribution now also owns an optional spatial-scene control block, including acquisition phase, @@ -138,6 +139,15 @@ telemetry and the stop action. Operator-manual acquisition still finalizes only local reception; plugin-commanded v0.5.0 acquisition uses the separately gated canonical K1 START/STOP dialogue. +Plugin v0.6.0 makes the local connection direction explicit. Bridge remains the +default; Direct Connect sends the same reviewed BLE frame with credentials for +an already-running controller hotspot; Quick Connect sends no BLE write and +instead associates this Mac with the K1 AP once. Each mode has a distinct +topology attestation and no automatic retry. The Bridge path is physically +accepted. Direct Connect and the Mission Core Quick Connect host adapter are +implemented and offline-verified but still require their own owner-operated +physical acceptance cycles; see [ADR 0013](docs/adr/0013-k1-local-connection-matrix.md). + The exact recovered `ModelingRequest` start/stop encoder, response correlator and device-status state machine are installed in the operator-gated interactive control path. diff --git a/apps/control-station/README.md b/apps/control-station/README.md index 736aa64..d6f287f 100644 --- a/apps/control-station/README.md +++ b/apps/control-station/README.md @@ -320,8 +320,10 @@ facts и старые presentation-поля `phase`, `message`, `devices`, активным между сессиями; для его закрытия нужно остановить `k1link serve`. - Пароль Wi-Fi находится только в React memory, передаётся в JSON POST body, очищается после успешного ответа и не сохраняется в URL/local storage. -- BLE-подключение выполняет только отдельно рассмотренную provisioning-запись; - случайные GATT writes и автоматические повторы запрещены. +- Bridge и Direct Connect выполняют только отдельно рассмотренную provisioning- + запись; Quick Connect не пишет в GATT и передаёт пароль короткоживущему + CoreWLAN helper только через stdin. Случайные GATT writes и автоматические + повторы запрещены. - MQTT data live/replay остаётся subscribe-only. Команды изолированы в plugin-owned canonical control session и доступны только через отдельные operator-present UI checkpoints. diff --git a/docs/01_IMPLEMENTATION_PLAN.md b/docs/01_IMPLEMENTATION_PLAN.md index 3e4b228..c21d9ef 100644 --- a/docs/01_IMPLEMENTATION_PLAN.md +++ b/docs/01_IMPLEMENTATION_PLAN.md @@ -3,7 +3,7 @@ This plan supersedes the app-dependent experiment order in the reference Bible. Each gate produces evidence and an explicit GO, PAUSE or BLOCKED result. -## Current checkpoint — 2026-07-18 +## Current checkpoint — 2026-07-19 | Stage | Result | | --- | --- | @@ -11,6 +11,7 @@ Each gate produces evidence and an explicit GO, PAUSE or BLOCKED result. | Gate 1 physical operation | GO — autonomous double-click start/stop verified | | Stage 1 BLE discovery | GO — repeatable advertisement and GATT profile | | Stage 2 BLE provisioning | GO — reviewed 99-byte profile, LAN association confirmed | +| Stage 2 local connection matrix | GO (implementation) — Bridge remains physically accepted; Direct Connect reuses the reviewed one-shot BLE frame; Quick Connect uses one CoreWLAN host association and no GATT write. Direct Connect and Mission Core Quick Connect still require separate physical acceptance | | Stage 3 application session | GO — MQTT 3.1.1 on confirmed K1 TCP 1883 | | Stage 4 artifacts/flows | GO — bounded capture, hashes and negative control | | Stage 5 point cloud | GO — raw-LZ4 protobuf, 1,140 live frames decoded | diff --git a/docs/adr/0012-device-bound-k1-command-authority.md b/docs/adr/0012-device-bound-k1-command-authority.md index 7f838c1..15f031b 100644 --- a/docs/adr/0012-device-bound-k1-command-authority.md +++ b/docs/adr/0012-device-bound-k1-command-authority.md @@ -13,6 +13,11 @@ that Mission Core reproduces all ten requests before START, plus START and STOP, byte-for-byte. This describes the current device dialogue but does not authorize writes to any K1. +The profile identifier above records the accepted v0.5.0 boundary. ADR 0013 +supersedes the active runtime selection with +`xgrids.lixelkity-k1.fw-3.0.2.local-network.v2`; it does not change the command +dialogue or retroactively broaden this acceptance evidence. + The protocol exposes identities with different ownership. Mission Core's inventory UUID and the macOS CoreBluetooth UUID are local transport identities. The vendor device ID and serial identify the live scanner. The OpenAPI value is diff --git a/docs/adr/0013-k1-local-connection-matrix.md b/docs/adr/0013-k1-local-connection-matrix.md new file mode 100644 index 0000000..d22df83 --- /dev/null +++ b/docs/adr/0013-k1-local-connection-matrix.md @@ -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. diff --git a/docs/lab/004_K1_CANONICAL_CONTROL_ARCHIVE_20260719.redacted.md b/docs/lab/004_K1_CANONICAL_CONTROL_ARCHIVE_20260719.redacted.md index 00633e0..f034837 100644 --- a/docs/lab/004_K1_CANONICAL_CONTROL_ARCHIVE_20260719.redacted.md +++ b/docs/lab/004_K1_CANONICAL_CONTROL_ARCHIVE_20260719.redacted.md @@ -84,8 +84,10 @@ to captured evidence. ## Current supported choices -- Connection: direct LAN is active; alternative connection modes remain disabled - UI anchors until independently accepted. +- Connection at the time of this acceptance: direct LAN only. ADR 0013 later + enabled Bridge, Quick Connect and Direct Connect as distinct v0.6.0 paths; + that later implementation does not retroactively add physical acceptance to + this archived run. - Mount/scan carrier: handheld is active. Ground UGV and aerial UAV choices are visible but disabled anchors. - GNSS: no RTK is the active default. RTK is visible but disabled and optional; diff --git a/plugins/xgrids-k1/README.md b/plugins/xgrids-k1/README.md index 0e9afe6..d3aa062 100644 --- a/plugins/xgrids-k1/README.md +++ b/plugins/xgrids-k1/README.md @@ -19,7 +19,8 @@ The plugin owns: - the exact firmware/topology compatibility profiles under [`profiles/`](profiles/), with strict evidence flags and a fail-closed loader; - BLE discovery hints and K1 GATT metadata; -- the reviewed firmware-3 Wi-Fi provisioning profile; +- Bridge and Direct Connect through the reviewed firmware-3 BLE Wi-Fi + provisioning frame, plus a one-shot macOS CoreWLAN Quick Connect adapter; - K1 LAN status and private-address validation; - subscribe-only data MQTT transport plus a separately bounded canonical application-control transport; @@ -74,7 +75,8 @@ in-process and its health is lifecycle-only; process isolation, crash/restart containment and signed deployment remain later supervisor gates. The compatibility profile is descriptive and cannot itself authorize a vendor -write. The UI selects the exact firmware `3.0.2` / direct-LAN profile; the +write. The UI selects the exact firmware `3.0.2` local-network profile and an +exact topology for Bridge, Quick Connect or Direct Connect; the canonical bootstrap then requires a correlated live `DeviceInfo` match for model `LixelKity K1`, platform type `A4`, activation and firmware before START. Validate the current exact-match profile without device I/O with: @@ -83,7 +85,18 @@ Validate the current exact-match profile without device I/O with: uv run python plugins/xgrids-k1/profile_loader.py ``` -Plugin v0.5.0 installs that reviewed transport behind explicit plugin actions. +Plugin v0.6.0 retains the physically accepted v0.5.0 control transport and adds +the connection matrix behind the existing explicit `network.provision` action. +Bridge remains the default. Direct Connect sends the same single reviewed +99-byte frame with credentials for an already-running controller hotspot. Quick +Connect sends no BLE write: a short-lived Swift/CoreWLAN helper receives the +operator-entered K1 AP credentials only over stdin, performs at most one scan +and one association, and never receives an automatic retry. Mission Core then +uses the observed K1 AP data-plane address. Automatic extraction of AP +credentials from undocumented BLE data is deliberately not implemented. + +Plugin v0.5.0 installed the reviewed application-control transport behind +explicit plugin actions. The normal UI accepts the project name and one explicit launch confirmation. It then performs operations 1–6, operation 7 and operations 8–10 only after the previous response barrier succeeds, prepares local reception, and emits one diff --git a/plugins/xgrids-k1/frontend/README.md b/plugins/xgrids-k1/frontend/README.md index 6b53013..8dc7c95 100644 --- a/plugins/xgrids-k1/frontend/README.md +++ b/plugins/xgrids-k1/frontend/README.md @@ -6,15 +6,16 @@ generic application source tree. The contribution contains: -- `K1ProvisioningPipeline` for power confirmation, BLE discovery and the - reviewed Wi-Fi provisioning write; +- `K1ProvisioningPipeline` for power confirmation, BLE discovery and the three + explicit local connection directions: Bridge, Quick Connect and Direct + Connect; - `K1AcquisitionPipeline` for explicit canonical connection/workspace/project/ START checkpoints, local receiver preparation and compatibility file replay; - `K1SpatialControls` for an explicit no-retry STOP followed by the separate READY plus steady-green completion gate; - plugin-local diagnostics, metrics, API state, lifecycle mapping, observation-source mapping and scoped styles; -- typed v0.5.0 interactive application-control state plus legacy shadow +- typed v0.6.0 local-network and interactive application-control state plus legacy shadow inspection contracts; - `plugin.ts`, which binds the manifest `device.connection` component key to the runtime provider and connection view. diff --git a/plugins/xgrids-k1/profiles/README.md b/plugins/xgrids-k1/profiles/README.md index 402ac8f..f8bab05 100644 --- a/plugins/xgrids-k1/profiles/README.md +++ b/plugins/xgrids-k1/profiles/README.md @@ -4,14 +4,17 @@ This directory is the plugin-local, versioned compatibility vocabulary for verified K1 wire behavior. It is deliberately **not** a platform ontology and does not add runtime dependencies on NODE.DC Ontology Core. -The first profile is -[`fw-3.0.2/direct-lan.v1.json`](fw-3.0.2/direct-lan.v1.json). It matches exactly: +The active profile is +[`fw-3.0.2/local-network.v2.json`](fw-3.0.2/local-network.v2.json). It matches exactly: - model: XGRIDS LixelKity K1; - firmware: `3.0.2`; -- topology: K1 and connector on the same owner-controlled LAN; -- evidence scope: one physical scanner across controlled direct-LAN and - owner-operated LixelGO/iPhone laboratory runs. +- topology matrix: Bridge (`direct-lan`), Quick Connect (`device-ap`) and + Direct Connect (`controller-hotspot`); +- evidence scope: one physical scanner across Mission Core Bridge and + owner-operated LixelGO/iPhone Quick Connect runs. The Direct Connect adapter + reuses the same physically accepted 99-byte BLE Wi-Fi frame, but its complete + Mission Core path still awaits a separate physical acceptance run. It must not be applied to another firmware or treated as a vendor API claim. Unknown firmware fails closed. @@ -63,14 +66,15 @@ The loader uses only the Python standard library and performs no device I/O: python plugins/xgrids-k1/profile_loader.py ``` -It verifies the exact firmware/topology scope, evidence vocabulary, source -references, GATT UUIDs, MQTT subscribe-only boundary, channel evidence, camera -RTSP/H.264 endpoints, operator-manual acquisition, and disabled vendor request -mappings. +It verifies the exact firmware/topology matrix, each mode's bounded network +actions, evidence vocabulary, source references, GATT UUIDs, local MQTT +boundary, channel evidence, camera RTSP/H.264 endpoints, operator-manual +acquisition, and disabled descriptive-profile vendor request mappings. ## Evolution rules -1. A different firmware or topology gets a new profile file and profile ID. +1. A different firmware or connection topology gets a new profile file and + profile ID unless it is added through another evidence-backed schema revision. 2. New evidence may only promote the flags supported by retained raw evidence, a documented decoder/replay check, or a physical lab report. 3. Unknown fields remain explicit; they are never filled from naming or payload