# 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 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 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.

## 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 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 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
   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.
