docs: record Mission Core K1 architecture milestone

This commit is contained in:
DCCONSTRUCTIONS
2026-07-16 19:44:16 +03:00
parent e6f7648b84
commit 05bdab24a5
8 changed files with 659 additions and 81 deletions
+30 -7
View File
@@ -1,25 +1,29 @@
# XGRIDS / LixelKity K1 plugin
This directory is the package boundary for the first Mission Core device
plugin. It now owns the canonical v1alpha manifest
plugin. It now owns the canonical v1alpha2 manifest
[`plugin.manifest.json`](plugin.manifest.json). The statically linked frontend
contribution lives in `apps/control-station/src/device-plugins/xgrids-k1/`; the
verified backend implementation remains temporarily in `src/k1link` so the
real-device path stays operational during extraction.
The v1alpha1 host deliberately assigns one model to one plugin runtime, so this
manifest exposes only `xgrids.lixelkity-k1`. Adding another device model means a
new plugin contribution until session/model routing lands in the next SDK.
The v1alpha2 catalog can describe one or more independently profiled models.
This manifest currently exposes only `xgrids.lixelkity-k1`, and the transitional
runtime still owns one active model/session at a time. Concurrent model/session
routing remains a later supervisor milestone.
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;
- K1 LAN status and private-address validation;
- subscribe-only MQTT transport and report-topic allowlist;
- native `.k1mqtt` capture;
- firmware-scoped protobuf/LZ4 and legacy codecs;
- normalization of K1 point cloud, pose, status, health, and artifacts;
- normalization of K1 point cloud and pose, plus raw-only preservation of the
still-undecoded status and heartbeat channels;
- K1-specific operator instructions and compatibility tests.
The plugin does not own:
@@ -45,7 +49,26 @@ legacy router; both paths delegate to the same proven
`XgridsK1CompatibilityService` methods. Synchronous capture/runtime operations
run outside the FastAPI event loop.
Model switching calls the plugin deactivation hook and must receive a successful
`stream.stop` before Mission Core removes this custom UI. BLE, MQTT, codec and
Model switching calls the plugin deactivation hook. An active acquisition uses
semantic `acquisition.stop` in `capture-only` mode; replay and pre-v1alpha2
sessions retain the legacy `stream.stop` shim. Neither path claims that the
physical K1 stopped without separate operator evidence. BLE, MQTT, codec and
evidence modules remain in `src/k1link` until replay parity and another physical
K1 regression are complete.
The compatibility profile is descriptive and cannot itself authorize a vendor
write. The current runtime cannot inspect K1 firmware: it keeps the profile
inactive until the operator explicitly attests firmware `3.0.2` and direct-LAN
topology, and records that basis as `operator-attested` rather than
device-derived evidence. Validate the current exact-match profile without
device I/O with:
```bash
uv run python plugins/xgrids-k1/profile_loader.py
```
The optional owner-controlled iPhone/LixelGO observation tool lives under
[`lab/iphone-capture/`](lab/iphone-capture/). It pins `pymobiledevice3` in a
separate `uv` environment, writes only ignored evidence sessions, and remains a
lab subprocess rather than a plugin/runtime dependency. The first capture is
gated by ADR 0004 and ADR 0005.