# Oya Architecture Decision Log (§0.2 — plan §9 forks resolved)

Each entry resolves a fork from the master plan (`OYA_RUST_REWRITE_AND_COMPANION_PLAN.md`)
with a decision + rationale + what it drives downstream. Status: **resolved for v1**;
revisit at the gates noted.

## D1 — Hardware strategy: **dev-platform-first** (not custom airframe yet)
Build and prove the whole software stack (Rust engine, hive crates, services) against
**off-the-shelf dev platforms** — PX4/ArduPilot reference airframes + Jetson dev kits +
COTS rovers — before committing NRE to a custom airframe. **Rationale:** the risk in v1 is
software correctness (control/estimation/safety/autonomy), not airframe NRE; the
`oya-mavlink` PX4/ArduPilot adapters + SITL path already target this. **Drives:** §10.1 SITL
bring-up; defer custom-airframe ME/EE until the stack passes the readiness gates. **Revisit:**
after the §10.2 economic-viability gate + a validated indoor demo.

## D2 — Rust extent: **surgical hot-path port** (plan §3.2)
Port only the performance-critical / numeric / safety-critical modules to Rust (the 21
`oya-engine` + hive crates: math, estimation, control, navigation, swarm, mavlink,
perception-math, dsp, mapping, safety, …); keep orchestration, services, SDK, and product
glue in TypeScript. **Rationale:** maximize correctness/throughput where it matters (1 kHz
control, fusion, ISO/TS 15066 safety) while keeping service-tier velocity; bridged via
napi (`oya-node-bridge`) + wasm (`oya-wasm-bridge`), parity-verified bit-for-bit.
**Drives:** the entire repo structure already built. **Revisit:** if a TS service shows a
hot path, port that module surgically.

## D3 — Edge compute target: **NVIDIA Jetson Orin for v1, runtime behind an abstraction**
Target **Jetson Orin (NX/AGX)** for the on-edge perception/VLA runtime; design
`oya-perception`'s inference runtime behind a `Detector`/`VlmModel` seam (already built) so
**Qualcomm QRB** can swap in at scale. **Rationale:** CUDA + Isaac ROS + the broadest model
support de-risk the perception/VLA bring-up; QRB's better perf/W and cost win later once
models are frozen. **Drives:** `oya-perception` runtime, §10.1 Isaac harness. **Revisit:**
at volume, on the economic-viability gate (BOM).

## D4 — On-device LLM: **hybrid; safety always local**
Local small model for low-latency/offline interaction + privacy-sensitive cognition;
server/cloud for heavy System-2 reasoning (`svc-assistant`'s `IsisLLMClient` seam). **The
`oya-safety` governor + all reactive/safety loops are local and never depend on cloud**
(enforced by the §10.2 offline-degradation gate). **Rationale:** cognition can be elastic;
safety cannot. **Drives:** `svc-assistant` LLM seam, offline-degradation gate. **Revisit:**
as on-device model quality improves, shift more cognition local.

## D5 — Perch mechanism: **EPM (electropermanent magnet) + wall-plate** for v1
Use EPM + installed wall-plates for perch/charge contact. **Rationale:** deterministic,
near-zero-power hold, reliable engage/disengage, cheap passive wall-plates; gecko/suction is
higher-risk across varied home surfaces and harder to verify. **Drives:** `svc-dock` perch
guidance + the perch-approach geometry already built. **Revisit:** if wall-plate install
friction proves unacceptable, evaluate gecko adhesives.

## D6 — Privacy posture: **local-first, explicit cloud opt-in** (recommended)
All sensing/storage is local-first; cloud is explicit opt-in with retention limits and guest
mode. **Rationale:** matches the §9.2 privacy gates, the `ConsentPolicy`/`PrivacyZone`
contracts, and `svc-home-map`'s fail-closed no-record redaction. **Drives:** the
privacy-enforcement readiness gate, `@oya/database` retention, consent contracts.
**Non-negotiable for v1.**

## D7 — Scope: **indoor-first for v1; architecture indoor+outdoor-ready** (§15.1)
Ship indoor-first; keep the architecture outdoor-capable. **Rationale:** indoor de-risks
weather/IP-rating/GPS-handoff; the engine already carries both GPS (`oya-estimation::gps`)
and indoor UWB (`oya-estimation::positioning`), so outdoor is an unlock, not a rewrite.
**Drives:** weather/IP/GPS-handoff deferred; indoor geofence + UWB positioning prioritized.
**Revisit:** after indoor v1 ships.