feat(device-plugins): add profiled K1 lifecycle and canonical data plane

2026-07-16 19:44:06 +03:00
parent 19ab973110
commit e6f7648b84
45 changed files with 6401 additions and 440 deletions
@@ -0,0 +1,70 @@
+# XGRIDS K1 compatibility profiles
+
+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:
+
+- 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.
+
+It must not be applied to another firmware or treated as a vendor API claim.
+Unknown firmware fails closed.
+
+## Evidence flags
+
+Every transport, data channel, and semantic action uses five independent
+boolean flags:
+
+| Flag | Meaning |
+| --- | --- |
+| `observed` | Directly seen on the owner-controlled K1 |
+| `decoded` | A bounded semantic decoder exists for observed bytes |
+| `replay_verified` | Captured semantic data passed the replay-to-view path |
+| `physical_verified` | Correlated with a controlled physical state/action |
+| `write_enabled` | The profile grants emission of a state-changing request |
+
+`decoded` does not mean that MQTT framing alone was parsed. Status and heartbeat
+are therefore observed raw channels, not decoded status models. Camera preview
+transport is observed, but its media decoder/replay flags remain independent.
+
+The v1 loader rejects every `write_enabled: true`. Owner-operated LixelGO wire
+capture verifies the `ModelingRequest` topic and action values, but complete
+device/session/OpenAPI header construction, settings, save completion, timeout
+and rollback contracts remain unresolved. Acquisition therefore stays
+`operator-manual` through the verified physical double-click.
+
+The existing BLE Wi-Fi provisioning workflow has its own reviewed profile and
+operator confirmation. Merely loading this compatibility profile neither calls
+nor authorizes that legacy mutation path.
+
+## Validation
+
+The loader uses only the Python standard library and performs no device I/O:
+
+```bash
+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.
+
+## Evolution rules
+
+1. A different firmware or topology gets a new profile file and profile ID.
+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
+   shape alone.
+4. Breaking profile semantics require a new `schema_version` and validator.
+5. Sensitive packet captures, device identities, addresses and credentials stay
+   outside Git; redacted reports and hashes are the committed evidence links.
+6. A profile describes compatibility. Host authorization and transport writes
+   remain separate policy and execution concerns.