# 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. Modeling telemetry
and the acquisition subset of DeviceStatus have bounded profile-scoped
decoders; heartbeat remains an observed raw channel. 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, action values, field layout,
literal `{device_id}:ModelingRequest` session relation, retained start settings
and numeric success code. Retained client/wire evidence identifies OpenAPI as
one private application-level value rather than a per-scanner profile. A fixed
read-only macOS Keychain loader, bounded shadow lease and dormant facade
orchestrator remain. Plugin v0.5.0 separately installs an interactive acceptance
transport implementing the retained MQTT session, exact response subscriptions
and poison-on-unknown one-shot behavior. The descriptive profile still cannot
enable writes by itself: active control exists only while the operator-opened
canonical session owns the socket. Physical acceptance, durable native save
completion and rollback evidence remain unresolved.
The standalone encoder models the recovered wire schema, including enum values
outside the retained request. It is not an authorization policy: any future
publisher must enforce the exact profile mapping (`2/1/0`, omitted
`pre_project_id`) in a separate reviewed gate.

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.