mhome-core-api

Canonical internal wire protocol for MeowCore, host services, Nodes, and provider runtimes. Public /app/* contracts belong to mhome-app-facade-api; this crate owns internal MWS, authentication, LLM, Messaging normalization, Node runtime, and Storage contracts.

MWS uses standard WebSocket Ping/Pong control frames for connection liveness. There are no application pi/po messages or auth heartbeatInterval field. The transport owns heartbeat timing and reports authenticated local connection activity through RefreshLocalAppClient; closing the transport removes that connection through CleanupLocalAppClient.

interaction_flow defines the serializable Core-to-Node flow definition and handler protocol. Definitions name logical operations only; MeowCore chooses and pins the Node instance and fixed transport routes for each session.

The Node owns the source session returned with a definition. Core closes that session through the fixed close route after completion, cancellation, expiry, or a failed start. Close is idempotent, and Nodes must also expire abandoned source sessions so a Core restart cannot leak them. Execute operations are idempotent within a source session: replaying the same operationId and request returns the original result, while reusing the ID for a different request is rejected.

Storage separates backing-filesystem capacity from Storage-owned logical usage. Namespace is an internal protocol term; user-facing clients present it as a Folder.

Lossless external boundaries (core-api 1.19.0)

External protocol 17 returns HttpPayloadResponse { statusCode, body } from all HTTP handler RPCs. A completed HTTP response (including 4xx/5xx) is an RPC success; RPC errors describe failures to execute the call, not HTTP status. Hosts preserve status and JSON body, never infer them from error messages. ExternalCoreError preserves domain code, message and optional details, with conversions to/from the shared client ErrorResponse.

The transport-neutral webhook module defines the common route, body limit and JSON-versus-UTF-8-text decoding. Hosts own network listeners and method admission; Core owns dispatch and execution. Upgrade service shell and Core together.

Host LAN observations (introduced in core-api 1.18.0)

The Host owns host::network::HostNetworkSnapshot, exposed through local IPC GET /internal/network. It samples eligible private IPv4 interfaces at startup and every 15 seconds, preferring 192.168/16, then 10/8, then 172.16/12. Within the best priority it retains a still-valid address, otherwise picks the numerically smallest address. This is a deterministic common LAN policy, not Ethernet/Wi-Fi classification or proof of reachability to every destination.

The response is { "lanIpv4": "192.168.1.2", "observedAtMs": 123456789 }; lanIpv4: null means unavailable. Consumers reject observations older than 45 seconds, future observations, and non-private IPv4. No loopback fallback. The query does not enumerate interfaces. Existing multicast discovery still uses its own complete interface inventory, not this single preferred address.

External protocol 16 changes UpdateCallbackBaseRequest to { network, port }. The service supplies the actual bound HTTP port and the unchanged Host observation. Core derives the origin instead of trusting an independent URL. Before the service reports, the sidecar has no callback origin. Freshness-only updates do not trigger subscription reconciliation. Shell and runtime must be upgraded together; local IPC is distinct from advertised callback URLs.

Playground Provider (core-api 1.10.0)

External protocol 15 removes the dedicated Playground webhook method and payload. Playground Provider delivers events through the standard subscription webhook, using GeneralWebhookPayload. Update the Core service shell and runtime together; mixed external protocol versions are not supported.

Stable recipients (core-api 1.8.0)

RecipientId provides canonical Messaging (m:p: / m:g:) and Node (n:) addresses. See the contract and the packaged cross-language conformance vectors. This is additive; the external Host transport protocol remains version 14. Consumers must explicitly migrate their identities after this release is available.

Host delivery (core-api 1.7.1)

Core resolves logical recipients; the Host executes a concrete App connection, Node connection or Messaging destination. Delivery responses distinguish queue or provider acceptance, intentional skips, definite failure and unknown completion. Acceptance is not a user-read receipt. Connection close has a separate typed control request.

External protocol 14 replaces effect notifications with request/completion events. ServiceCoreOutput contains only its response and rejects the old effects field. Messaging returns the same typed outcome, not a delivered boolean. Skipped means handled without a send and must not be reported as provider acceptance. There is no old-protocol compatibility path. Consumers must upgrade together; version 1.7.1 must be published before updating registry-backed consumer locks.

Host contracts (core-api 1.11.0)

core_api::host is the single owner of Host hardware information, installed service inventory, system/service metrics, and OS permission declarations and observations. It replaces the independent mhome-host-api crate. App Facade reuses these types and owns its public routing and observation envelopes. Importing this module does not require a running Core or a Space.

Host/Client producers and readers must use these DTOs rather than redeclare matching JSON structures. Platform collectors may keep private sampling structs; only the canonical DTOs cross HTTP/IPC boundaries. The permissions contract is in contract/host-permissions.md; runtime permission handlers remain a separate implementation step. The existing Core external runtime protocol stays at 15.

Offline Host authorization (core-api 1.15.0)

host::auth is the language-neutral Client–Host authorization payload contract. See contract/host-offline-auth.md. This crate does not implement signing, key storage, or transport.

Native Client Host management

host::management defines the generic runtime request/action and response envelope. Runtime implementations supply their component ID type. The matching language-neutral contract is contract/host-management-v1.json; request validation uses schema/host-management-request.v1.schema.json.

Desktop/CLI use Clientd IPC host.list and host.runtime; mobile Clients expose the same operations through hostList / hostRuntime. None accepts a Space ID. Clients discover _mhome-host._tcp, verify reply Host IDs, and unwrap the HTTP runtime envelope. Install/restart submissions are not automatically replayed after transport failure. Existing LAN access semantics remain; this release does not add a trust/pairing protocol.