# Implementation plan

This plan supersedes the app-dependent experiment order in the reference Bible.
Each gate produces evidence and an explicit GO, PAUSE or BLOCKED result.

## Live checkpoint — 2026-07-15

| Stage | Result |
| --- | --- |
| Stage 0 host/repository | GO — isolated Python 3.12 environment and private Git |
| Gate 1 physical operation | GO — autonomous double-click start/stop verified |
| Stage 1 BLE discovery | GO — repeatable advertisement and GATT profile |
| Stage 2 BLE provisioning | GO — reviewed 99-byte profile, LAN association confirmed |
| Stage 3 application session | GO — MQTT 3.1.1 on confirmed K1 TCP 1883 |
| Stage 4 artifacts/flows | GO — bounded capture, hashes and negative control |
| Stage 5 point cloud | GO — raw-LZ4 protobuf, 1,140 live frames decoded |
| Stage 5 pose | GO — 1,215 live frames decoded and motion-correlated |
| Stage 5 camera | PAUSE — no independent frame/video stream observed |

USB project copying remains optional ground truth rather than a blocker for the
now-verified network path. MQTT control publishing remains deliberately deferred
because the physical button is a known-safe start/stop mechanism.

## Stage 0 — repository and host baseline

Deliverables:

- local Python 3.12 `.venv` and lock-file;
- `k1link doctor` with no side effects;
- immutable reference documents and checksums;
- safety policy, artifact policy, session manifest schema;
- no Homebrew changes and no K1 interaction.

Acceptance:

- `uv sync --group dev` succeeds;
- `uv run k1link doctor` identifies a local `.venv`;
- tests, Ruff and mypy pass;
- repository contains no secrets or real captures.

## Gate 1 — physical and USB baseline

Code needed: none initially.

Actions:

1. Record masked device identity, LED boot sequence, battery and visible state.
2. Determine whether the unit is activated; solid-yellow or an activation prompt
   is treated as a distinct blocker.
3. Run one short autonomous button scan: start, keep still for at least 20 seconds,
   move through a simple scene, stop.
4. Enter USB mode using the documented physical shortcut if available.
5. Copy a project tree and selected metadata/logs into an ignored session path.
6. Hash every copied file and create a redacted manifest.

GO: the unit boots normally and records a usable autonomous project.

PAUSE: USB access is unavailable but the scan succeeds; continue BLE while
documenting the missing ground truth.

STOP: serious fault, overheating, activation lock, or destructive/ambiguous
device state.

## Stage 1 — BLE non-mutating discovery and metadata toolkit

Minimal dependencies: `bleak` plus the existing CLI stack. Add them only in the
repository-local environment.

Commands:

```text
k1link ble scan
k1link ble gatt-dump
k1link ble listen
```

Requirements:

- preserve advertisement snapshots, manufacturer/service data and RSSI;
- describe macOS scanning as active discovery: CoreBluetooth does not support
  passive scan mode, although discovery does not change K1 configuration;
- identify by observed name + macOS UUID + advertisement fingerprint;
- inspect standby, scanning and USB states separately;
- start with standard Device Information/Battery services;
- custom characteristic reads are opt-in because proprietary reads may have
  side effects;
- notifications are subscribed one characteristic at a time and logged to
  timestamped JSONL;
- no arbitrary characteristic or provisioning writes in this stage. Enabling a
  notification normally updates the standard CCCD descriptor; this temporary,
  reversible protocol write is disclosed and handled separately from device
  configuration.

GO: reproducible K1 advertisement and useful GATT map.

PAUSE: permission or pairing/authentication is required.

## Gate 2 — existing network behavior

Do not change Deco settings first.

Actions:

1. Save the Mac interface and route table.
2. Observe router client list and Mac ARP/neighbor state with K1 off.
3. Repeat after K1 boot, during standby, scanning and after one power cycle.
4. Check for new Wi-Fi SSIDs exposed by K1 without attempting to join unknown
   networks automatically.
5. Confirm any candidate by disappearance/reappearance with K1 power state.

GO-A: K1 joins a remembered LAN. Provisioning leaves the immediate critical
path and work moves to the application-session gate.

GO-B: K1 exposes its own AP. Document it as a separate topology and determine
whether Mac can join without modifying router configuration.

BLOCKED: neither association nor AP exists; provisioning becomes Stage 2.

## Stage 2 — no-app provisioning research

This stage answers whether SSID/PSK can be sent safely from Mac. A generic BLE
transport does not define the vendor payload.

Evidence sources allowed before a write:

- GATT UUIDs, properties and descriptors;
- standard service identification;
- read/notify state transitions correlated with network state;
- owned K1 project logs and metadata;
- public official firmware/documentation static evidence if separately reviewed;
- deterministic structure inferred without sending device mutations.

Before enabling any write profile, document:

- exact service/characteristic and required security mode;
- packet framing, encoding, ordering and length rules;
- SSID/PSK redaction and secure input path;
- checksum, nonce, token, certificate or signature fields;
- commit/connect command and status response;
- timeout, failure state, power-cycle behavior and rollback;
- one explicit confirmation flag in addition to a named reviewed profile.

GO: a deterministic provisioning profile exists with an explained expected
state transition and safe rollback.

HARD BLOCK: K1 knows no network, exposes only opaque vendor GATT, and no evidence
source reveals the protocol. Random writes are not an alternative.

## Stage 3 — application session and targeted capture

Prerequisite: confirmed K1 IP or direct AP topology.

Implementation order:

1. Passive ARP/mDNS/SSDP and K1-filtered `tcpdump` baseline.
2. Small targeted TCP connect check against the confirmed IP.
3. Service detection only where the prior step supplies evidence.
4. Parse K1 logs for daemon names, ports and protocol strings.
5. Add protocol-specific connection attempts only for demonstrated endpoints.
6. Model `WIFI_ASSOCIATED_BUT_NO_DATA_SESSION` explicitly.

`k1link net capture` must show the exact interface/filter, request privilege in
the foreground, handle Ctrl+C, and never configure persistent `sudo` or ChmodBPF.

GO: Mac becomes a K1 endpoint or receives a reproducible scan-correlated flow.

BLOCKED: application session requires an unavailable mutual-auth token,
certificate or undocumented handshake.

## Stage 4 — session artifacts and flow analysis

Implement only after real traffic exists:

- versioned session manifest;
- UTC and monotonic timeline events;
- SHA-256 inventory;
- TCP reassembly and UDP flow grouping;
- packet/byte rates, length histograms, entropy and first-byte fingerprints;
- idle versus scanning correlation;
- negative-control flows to reduce false positives.

GO: repeatable flows can be separated and ranked without losing raw evidence.

## Stage 5 — decoders by evidence priority

Priority:

1. device/scan status;
2. point-cloud preview;
3. pose/trajectory;
4. camera/panorama/video.

Add dependencies per decoder extra, not to the base environment. Point-cloud
and video signature probes operate on reassembled flows, not isolated packet
payloads. A candidate becomes a decoder only after a controlled physical test
confirms it.

MVP GO: K1-to-Mac scan-correlated data can be captured reliably and at least one
useful stream is decoded or structurally identified.

## Deferred work

- ROS2/MCAP bridge;
- onboard computer and drone integration;
- automated scan-button electronics;
- OpenWrt/monitor-mode infrastructure;
- firmware or internal-Linux analysis;
- camera branch if no external frame stream is evidenced.