docs: record Mission Core K1 architecture milestone

README.md

@@ -8,16 +8,30 @@ extracted, and device plugins.
 
 The first proven hardware vertical is the XGRIDS/LixelKity K1 plugin. On firmware
 3.0.2 the host provisions the scanner onto an existing LAN without LixelGO,
-connects to its MQTT broker, durably captures the raw stream, decodes point cloud
-and pose, and renders the real cloud plus trajectory through an embedded
-self-hosted Rerun Web Viewer. The former Foxglove bridge remains only as a
-legacy regression module.
+connects to its MQTT broker, persists each raw frame before preview work, decodes
+point cloud and pose, and renders the real cloud plus trajectory through an
+embedded self-hosted Rerun Web Viewer. Capture files are `fsync`ed on clean
+close; per-frame power-loss durability is not claimed. The former Foxglove
+bridge remains only as a legacy regression module.
 
 The repository is intentionally migrating in stages. The current `src/k1link`
 package is the compatibility implementation of the first plugin path; vendor
 transport and codecs will move behind `plugins/xgrids-k1` and the Mission Core
 Plugin SDK without changing the verified wire protocol or raw evidence format.
 
+Plugin SDK v0alpha2 now provides executable, vendor-neutral identity, session,
+operation, stream, evidence and compatibility contracts. The meanings remain a
+local experimental vocabulary rather than a mutation of NODE.DC Platform
+Ontology. The current runtime is still transitional and in process: it uses an
+explicitly injected K1 normalizer to produce transport-neutral local consumer
+views; portable SDK stream envelopes, process isolation, durable operations,
+multi-device routing and the remote Edge split remain later gates.
+
+The current runtime cannot read K1 firmware automatically. It keeps the exact
+profile inactive until the operator explicitly attests firmware `3.0.2` and
+direct-LAN topology; state records that basis as `operator-attested`, not as
+device-derived evidence.
+
 The repository now contains one narrowly gated state-changing command:
 `ble wifi-configure`. It accepts only the reviewed firmware-3 provisioning
 profile and requires explicit `--confirm-write`; the Wi-Fi password is collected
@@ -29,7 +43,16 @@ Nothing changes router settings, firmware or global Python packages.
 - one XGRIDS/LixelKity K1;
 - one Apple Silicon MacBook running macOS;
 - one ordinary TP-Link Deco/mesh network used by other devices;
-- no LixelGO, phone, Linux host, dedicated AP, OpenWrt, or vendor SDK.
+- the proven baseline used no LixelGO, phone, Linux host, dedicated AP,
+  OpenWrt, or vendor SDK.
+
+An owner-controlled iPhone with LixelGO is now available for a separate,
+evidence-only observation stage. It does not invalidate the no-phone baseline
+and is not a runtime dependency. The decision and gated runbook are
+[`ADR 0005`](docs/adr/0005-owner-controlled-lixelgo-iphone-observation.md) and
+[`docs/08_LIXELGO_IPHONE_OBSERVATION.md`](docs/08_LIXELGO_IPHONE_OBSERVATION.md).
+The Mac capture environment is isolated under
+`plugins/xgrids-k1/lab/iphone-capture/` and does not require full Xcode.
 
 The ordinary router is sufficient for the first gates. We first observe the
 existing LAN without changing it. A Guest/IoT SSID is optional and may be
@@ -45,10 +68,11 @@ The project has three independent gates:
 3. Without LixelGO, K1 can be associated with Wi-Fi and a proprietary data
    session can be opened.
 
-All three gates are now proven on the tested unit. The external stream is plain
+All three gates are now proven on the tested unit. The spatial stream is plain
 MQTT 3.1.1 on TCP 1883. Firmware-3 `lio_pcl` is protobuf wrapped in a raw LZ4
-block, and `lio_pose` is an uncompressed protobuf. Raw panoramic camera access is
-still unproven and is not implied by point-cloud success.
+block, and `lio_pose` is an uncompressed protobuf. Owner-operated LixelGO capture
+also proved separate left/right RTSP/H.264 camera previews on TCP 8554. This is a
+compressed preview contract, not proof of full-resolution raw camera access.
 
 ## Local environment
 
@@ -58,7 +82,7 @@ repositories.
 
 ```bash
 cd /Users/dcconstructions/Downloads/mnt/NODEDC/NODEDC_MISSION_CORE
-uv sync --group dev
+uv sync --frozen --group dev
 uv run k1link doctor
 uv run pytest
 ```
@@ -74,9 +98,10 @@ Install, type-check, build and serve the complete local application from the
 repository root:
 
 ```bash
-uv sync --group dev
+uv sync --frozen --group dev
 cd apps/control-station
-npm install
+npm ci
+npm run test:unit
 npm run typecheck
 npm run build
 cd ../..
@@ -89,7 +114,14 @@ still provides real CoreBluetooth discovery, one operator-triggered reviewed
 BLE Wi-Fi provisioning write, read-only MQTT live capture, native `.k1mqtt` and
 reviewed-TSV replay, raw-first evidence storage and measured preview metrics.
 Physical K1 scanning is still started and stopped by the verified double-click;
-the connector publishes no modeling command.
+the connector publishes no modeling command. The observed LixelGO action mapping
+remains descriptive and write-disabled.
+
+This locked bootstrap is repeatable in the current workspace, not yet a
+standalone release install. The frontend consumes sibling `file:` packages from
+`NODEDC_DESIGN_GUIDELINE`; `package-lock.json` does not pin that checkout's Git
+revision or content hash. Publishing/vendoring those packages or enforcing an
+immutable donor revision remains a packaging and CI prerequisite.
 
 The Observation spatial workspace embeds the open-source Rerun Web Viewer
 inside the Mission Core shell. It can open a compatible RRD file over HTTP(S) or a
@@ -102,9 +134,12 @@ the resulting URL through control-plane state. Later sessions reset their
 session-local scene and metrics and reuse that process-wide stream; this avoids
 restarting the native listener while the embedded browser remains connected.
 Unless an operator has entered a manual source, the React application assigns
-that URL to the embedded viewer. The complete runtime path is K1 MQTT → raw-first evidence
-capture → bounded latest-wins preview queue → reviewed protobuf/LZ4 decoders →
-Rerun `Points3D`, `Transform3D` and `LineStrips3D` → embedded Web Viewer.
+that URL to the embedded viewer. The complete runtime path is K1 MQTT → raw-first
+evidence capture → bounded latest-wins preview queue → explicitly injected K1
+protobuf/LZ4 normalizer → transport-neutral decoded local views → Rerun
+`Points3D`, `Transform3D` and `LineStrips3D` → embedded Web Viewer. Rerun does
+not inspect K1 topics or raw payloads. These local decoded views are not yet the
+portable Plugin SDK wire envelopes.
 
 The default Rerun blueprint shows a 12-second sliding accumulation of real point
 frames. Product controls are connected for point size, intensity/height/distance
@@ -115,9 +150,9 @@ point cloud, trajectory, camera frame or latency value is generated.
 
 A powered-device checkpoint passed 80 real MQTT messages through the current
 Rerun runtime: 38 point-cloud frames, 42 pose frames, 2,775 points in the last
-cloud and zero decode errors. Raw panoramic camera frames remain absent. Rerun
-`capture_time` is the Mac receive timestamp, not a proven K1 sensor timestamp or
-photon-to-screen measurement.
+cloud and zero decode errors. The later RTSP camera preview is not yet wired into
+the Rerun/runtime path. Rerun `capture_time` is the Mac receive timestamp, not a
+proven K1 sensor timestamp or photon-to-screen measurement.
 
 The old Foxglove implementation is retained only in
 `src/k1link/viewer/foxglove_bridge.py` and its regression tests. The current
@@ -179,6 +214,7 @@ present.
 - [Mission Core monorepo and plugin boundary](docs/07_MISSION_CORE_MONOREPO.md)
 - [Monorepo architecture decision](docs/adr/0002-mission-core-monorepo.md)
 - [Device plugin UI and runtime boundary](docs/adr/0003-device-plugin-ui-and-runtime-boundary.md)
+- [Plugin SDK v0alpha2 and experimental device lifecycle](docs/adr/0004-plugin-sdk-v0alpha2-and-experimental-device-lifecycle.md)
 - [Redacted live lab report](docs/lab/001_K1_LIVE_MQTT_20260715.redacted.md)
 - [Session manifest schema](schemas/session-manifest.schema.json)
 - [Reference input provenance](docs/reference/README.md)