docs: document configuration and diagnostics contracts

docs/src/logs.md

@@ -0,0 +1,61 @@
+# Logs
+
+Normal host/SITL task code can use the standard facade:
+
+```rust
+log::debug!("estimator waiting for IMU");
+log::info!("configuration loaded");
+log::warn!("range aid stale");
+log::error!("sensor transfer failed"); // emitted as KAPTAN_ERROR
+```
+
+`kaptan-log` formats once into a fixed bounded buffer, queues locally, and
+never sends MAVLink, allocates, blocks, changes flight state, or touches DMA.
+The sole MAVLink worker drains admitted records. F722 deliberately does not
+link this facade in ISR, DMA, control, actuator, panic, hard-fault, or shutdown
+contexts; those paths use static fault mailboxes that the worker turns into
+messages later.
+
+## Receiver contract
+
+`definitions/kaptan/log.xml` separates ordinary logs from errors:
+
+```text
+KAPTAN_LOG { level, flags, message_length, message[160] }
+KAPTAN_ERROR { flags, message_length, message[160] }
+KAPTAN_SHUTDOWN { reason }
+```
+
+A receiver generated from the same `kaptan.xml` revision validates
+`message_length <= 160` and decodes exactly that UTF-8 prefix. `KAPTAN_LOG`
+displays its text at the MAVLink severity in `level`; `TRACE` is encoded as
+`DEBUG` plus the `TRACE` flag. `KAPTAN_ERROR` is error-only and accepts only
+`TRUNCATED` and `COALESCED`; a `TRACE` bit is never emitted there. Unknown
+future flag bits must be ignored.
+
+The derived error display text is intentionally not a numeric error catalog;
+renaming its Rust module/type/variant changes the display identity. Error
+details requiring machine action stay in their owning protocol, notably
+`KAPTAN_CONFIG_RESULT`. `KAPTAN_SHUTDOWN` has only its typed reason and is
+valid only after an orderly output-inhibited completion. Delivery is bounded
+and lossy under link pressure; heartbeat and safety telemetry use separate
+paths.
+
+## Filtering
+
+The SITL profile’s restart-only `observability.maximum_log_level` accepts
+MAVLink severities Error (3) through Debug (7). For example, selecting Warning
+permits warning records while suppressing info and debug records. Error-level
+records always use `KAPTAN_ERROR` and remain non-filterable. F722 uses its
+immutable board log threshold instead, because it has no active runtime
+profile.
+
+Cargo `log/max_level_*` features compile calls away before the facade sees
+them; they are not a supported filtering mechanism. The build policy keeps
+that decision out of workspace dependencies.
+
+The tested `SitlConfigRuntime` composition proves `log!` reaches a generated
+`KAPTAN_LOG` payload, and rejected configuration replies enqueue a generated
+`KAPTAN_ERROR` companion without replacing their authoritative result. `kaptan-sitl
+serve` does not yet attach a config/diagnostic MAVLink link, and F722 emits only
+outbound telemetry/diagnostic frames while rejecting all inbound authority.