feat(homecore-server): wire HAP runtime and registry APIs

v2/docs/homecore-capabilities.md

@@ -1,50 +1,73 @@
 # HOMECORE capability status
 
-This document describes the implemented runtime surface as of the current
-alpha. “Implemented” means wired into `homecore-server` and covered by tests;
-workspace libraries alone are not presented as server capabilities.
+This document describes the current alpha runtime. “Implemented” means the
+capability is wired into `homecore-server` or its public protocol crate and is
+covered by tests. It does not imply compatibility with every Home Assistant
+integration or every Apple Home controller.
 
-## Implemented
+## Runtime capabilities
 
-| Area | Runtime behavior |
+| Area | Current behavior |
 |---|---|
-| Core | Concurrent entity state machine, entity registry API, shared system/domain event bus, service registry, contexts |
-| Event flow | Committed state changes reach state subscribers and the shared event bus; service calls emit system events |
-| REST | API root, config, list/get/set/delete state, list/call service |
-| WebSocket | Auth handshake, ping, config/states/services queries, service calls, event subscribe/unsubscribe |
-| Backpressure | Per-connection WebSocket output is bounded to 256 messages; slow clients are disconnected from overflowing subscriptions |
-| Authentication | Token allowlist from `HOMECORE_TOKENS`; missing tokens fail startup unless insecure development mode is explicitly enabled |
-| Recorder | SQLite state history listener; broadcast lag is recovered by resynchronizing current state; optional ruvector semantic index |
+| Core | Concurrent entity state machine; entity and device registries; system/domain event buses; service registry; causal contexts |
+| Restore | Entity registry, device registry, and the most recent recorder state are restored in dependency order at startup; malformed rows are isolated and bounded |
+| Recorder | SQLite state history listener; deterministic latest-state queries; broadcast lag recovery; optional ruvector semantic index |
+| Migration | Entity/device registries and config entries are parsed with version checks, unknown forward-compatible fields are preserved, and output is written atomically without overwriting existing storage |
+| Plugins | Compiled-in native plugins use an explicit registry. Packaged Wasm plugins are discovered only in configured directories, bounded and path-checked, signature-verified against configured Ed25519 publishers, and run through Wasmtime when the `wasmtime` feature is enabled |
+| Plugin lifecycle | Plugin setup runs after restoration and built-in service registration; state changes are dispatched through a bounded queue; teardown runs during graceful shutdown |
 | Automation | State, numeric, event, and time triggers; optional YAML loading at server boot |
-| Assist | Authenticated `POST /api/intent/handle` with bounded regex recognition and five local handlers |
-| Built-in services | Real state mutation for `homeassistant`, `light`, and `switch` on/off/toggle; ping and state snapshot |
-| Migration | HA entity registry v1/minor 1–13 parsing and atomic, no-overwrite persistence into a HOMECORE storage directory |
+| Voice | Bounded PCM16 audio types, async STT/TTS provider contracts, an STT → intent → TTS pipeline, and an authenticated transport-independent satellite session protocol |
+| Assist | Authenticated local intent endpoint with bounded regex recognition and service-backed handlers |
+| HAP network | With `homecore-server --features hap-server`, an explicitly configured bounded TCP listener, persisted pairing records, live entity/accessory synchronization, and `_hap._tcp` mDNS lifecycle are wired into the server |
 | Dashboard/BFF | Static UI, calibration proxy, rooms, COG list, appliance metrics, and typed unavailable responses for absent upstreams |
 
-## Exact HA-style HTTP surface
+## Home Assistant-compatible REST surface
 
 - `GET /api/`
 - `GET /api/config`
+- `GET /api/components`
 - `GET /api/states`
 - `GET|POST|DELETE /api/states/:entity_id`
 - `GET /api/services`
 - `POST /api/services/:domain/:service`
+- `GET /api/events`
+- `POST /api/events/:event_type`
+- `POST /api/template`
+- `POST /api/config/core/check_config`
+- `GET /api/error_log`
 - `GET /api/websocket`
 - `POST /api/intent/handle`
+- `GET /api/homecore/compatibility`
 
-This is a compatible subset, not full Home Assistant parity.
+The WebSocket server implements authentication, feature negotiation, ping,
+configuration/state/service queries, service calls, event firing,
+subscribe/unsubscribe, template rendering, panels, and entity/device/area
+registry list commands. Per-connection output is bounded; lagging event
+subscribers resynchronize.
 
-## Explicitly deferred
+`GET /api/homecore/compatibility` is the machine-readable support matrix.
+HOMECORE implements the core contract above, not every endpoint contributed by
+Home Assistant integrations. History needs an attached recorder query surface;
+camera, calendar, media, and Lovelace behavior remain integration-dependent.
+Registry mutations require a persistent registry mutation backend. The area
+registry currently returns a valid empty list.
 
-- Loading native or Wasmtime plugins from `homecore-server`
-- A network HomeKit Accessory Protocol server, pairing, and mDNS advertisement
-- Device-registry persistence and full config-entry conversion
-- Full HA event/history/template/config/check endpoints
-- Restore-state on server startup
-- STT/TTS and satellite voice protocols
-- SEED/federation/witness/privacy upstream services when their daemons are absent
-- Claiming Home Assistant integration parity or production-scale performance
+## Security and deployment constraints
 
-Unavailable BFF upstreams return typed `503 upstream_unavailable`. Unsupported
-services are not registered. Synthetic biometric/demo entities are opt-in and
-must not be interpreted as live sensing data.
+- `HOMECORE_TOKENS` is required unless insecure development authentication is
+  explicitly enabled.
+- Unsigned Wasm packages are rejected unless the development-only override is
+  explicitly supplied. Arbitrary native dynamic libraries are never loaded;
+  native plugins must be linked into the binary and registered in code.
+- HAP is disabled by default. Enabling it requires an explicit bind address,
+  stable six-octet device identifier, advertised LAN address, hostname, and
+  durable pairing-store path.
+- The HAP listener fails closed for cryptographic phases that are unavailable
+  in the selected build. Do not claim Apple Home interoperability unless the
+  Pair-Setup, Pair-Verify, and encrypted transport conformance tests for that
+  build pass.
+- STT and TTS are provider contracts; a deployment must supply real providers.
+  The built-in disabled providers return typed errors rather than fabricated
+  speech results.
+- Synthetic biometric/demo entities are opt-in and must not be interpreted as
+  live sensing data.