eSlider
2a6b50929c
Keep the 45-byte pose frame consistent across docs, simulator, and prototype, clarify MinIO is not peer sync, and state clearly that the repo is a from-scratch platform sketch with options rather than mandates.
2.3 KiB
ADR-0004: Read-only SQL-over-SSH as the peer query contract; no debug API
Status
Accepted (2026-07-08). Supersedes the earlier sketch of a bespoke query service.
Context
Beyond the 5 Hz broadcast, a peer (or an engineer on the bench) sometimes needs to ask a drone a richer question: "show me your detections in the last minute near this position". Inventing a service for this means a new port, a new protocol, an auth layer, and a second code path that only runs during debugging — the classic "works on the bench, untested in flight" trap.
Options
| Option | Pros | Cons |
|---|---|---|
| A — Custom query microservice + REST API | Flexible | New port/protocol/auth to secure; a debug-only path that never flies |
| B — Read-only DuckDB SQL over an SSH forced command | Reuses SSH trust + the query language already on both ends; identical path on bench and in flight | SQL must be gated to read-only |
Decision
Peer data access is read-only DuckDB SQL executed through an SSH forced
command. SQL is already the query language on both ends
(ADR-0002), and SSH already carries the trust
model (ADR-0005), so no new service, port,
or protocol is invented. A SQL gate rejects anything that writes
(COPY, INSERT, ATTACH, pragmas). There is no separate debug API: an
engineer debugging on the ground runs the identical query through the identical
wrapper, permissions, and output format a peer drone would use.
Consequences
- One access path is designed for flight and bench — "what you test is what flies".
- The statement gate in the PoC (
simulator/explorer/server.py, covered bysimulator/tests/test_sql_gate.py) is a first layer: keyword allow/deny over HTTP for the explorer. Production still needs the remaining layers in 04 — Swarm sync (forced-command key, read-only OS user, engine hardening, resource caps) and a real SQL parser rather than keywords alone. - The explorer and the prototype's live mode are stand-in consumers of the
same read-only contract over HTTP today; the proposed flight path is
SQL-over-SSH (
../04-swarm-sync.md). - Design principles 7 and 8 in
../../README.mdrestate this.