# mhome-app-facade-api
Canonical public protocol shared by MeowLink clients, MeowCore, the CLI,
Agents, and cloud adapters.
The package also carries the explicitly private `/local/*` native-daemon
extension. `/app/*` is portable and may be routed according to the public
routing manifest. `/local/*` is an exact allowlist for the current MeowLink
native client process and must never be forwarded to cloud, Hub, or Host
connections. Hub `/app/*` calls are direct-only `FacadeCall`s; Hub `/local/*`
calls carry the domain input directly and never use the public envelope.
Every `/app/*` request uses the strict `FacadeCall` envelope. Invocation
metadata lives in `control`; the domain request lives in `input`. The crate
owns public targets, request/response/event schemas, and stable operation
identity. Core-to-Node routes and provider runtime models belong to
`mhome-core-api` instead.
`interaction_flow` exposes only the materialized current-step view and session
commands. Handler operations, the complete step graph, and Node routing
identity remain internal to MeowCore.
Core owns defaults, resolver results, and read-only values. Clients may write
only editable inputs. Password plaintext is accepted as input but is never
projected back; `hasValue` lets a client render back navigation without
recovering the secret. Each current-step resolver projection reports whether
its complete referenced value is available and which visible inputs can make
it stale, so clients can resolve it reactively without learning handlers or
the hidden graph.
`topology` exposes the Hub-owned Space network projection. Stable Host, Hub,
Node, AppClient, and Cloud identities are separate from current transport
sessions. Durable relations remain present while disconnected and carry an
explicit observation state so clients can distinguish expected topology from
the currently observed path.
`artifact` exposes the MeowLink-facing `/app/artifact/resolve` operation. Its
domain input and output reuse `mhome-artifact-api`; Node runtimes use the
separate transport-neutral `/artifact/*` targets and never enter the App
Facade.
`pod` (1.34.0) defines native-Client pod discovery and commissioning
(`/local/pod/*`), the shared BLE advertising format and the pod credential
protocol with Lion. Sessions are owned through a renewed lease, and rejected
requests carry a stable `details.reason`. See
[the contract](contract/pod-commissioning-v1.md). Targets, BLE constants, session
timings and request reasons are in `manifest/pod-targets.v1.json`; snapshots use
`schema/pod-discovery.v1.schema.json` and `schema/pod-commission.v1.schema.json`;
the owner's credential status is `schema/pod-credential-status.v1.schema.json`.
`host_provision` (1.34.0) defines BLE Wi-Fi provisioning of embedded Hosts
(`/local/host/provision/*`) on the same BLE layer; discovery candidates carry
`kind`. A completed session carries the one-time `claimToken` that the first
claim of that Host requires. See [the contract](contract/host-provisioning-v1.md), the targets in
`manifest/host-provision-targets.v1.json` and
`schema/host-provision.v1.schema.json`.
## Routing contract
`manifest/routing.v1.json` is the canonical client-side routing policy for the
new `/app/*` facade. Ordinary operations follow the active Space mode. Only
exceptional domains declare a fixed Cloud, Hub, or request-placement executor.
Relay permission is separate from execution authority so a client
cannot silently turn every Hub request into a cloud-proxied request.
The checked-in Rust table is generated from that manifest, and non-Rust clients
consume the same manifest from the npm protocol package. Local Spaces execute
Host inventory and management on the selected Hub through `/app/system/hosts/*`.
A native Client remains the path when no local Hub is selected. Lion's legacy
controller annotations and non-`/app/*` protocols are outside this contract.
### System plugin catalog
`/app/plugin/catalog/list` returns `manifest/plugin-catalog.v1.json` from Cloud,
without requiring a local Space or connected Hub. Authentication and Space
membership still apply. Core also serves this catalog for clients with an older
routing manifest. The response schema is `schema/plugin-catalog.v1.schema.json`.
The catalog describes supported types, not installed software or bindings.
`componentId` joins to Host runtime inspection; `nodeType` joins to existing
Plugin candidate and installed/binding queries. Platform installability and
versions come from the Host release catalog, not this directory.
Core and Cloud embed generated copies. After editing the catalog, run
`node scripts/sync-plugin-catalog.mjs --write <core-resource> <cloud-resource>`
from the Foundation root; omit `--write` to check conformance. Resource paths are
`src/application/plugin-catalog.v1.json` (Core) and
`src/main/resources/app/plugin-catalog.v1.json` (Cloud module-service).
## Shared messaging codes (1.10)
Code creation may omit bot/account and group/surface identifiers. The receiving authenticated provider determines the bot; shared candidates are confirmed in the App. The existing actor link claim status/confirm/event endpoints carry both kinds, distinguished by `kind` (`link` by default, or `bind`). Bind code responses include `challengeId`; completed bind claims omit `linkId`. Private link completes on receipt. A code is single-use within its provider and service deployment, never a cross-provider or cross-Hub credential.
## Space runtime observations
`/app/system/instances/get` reads Space instances; `/app/system/clients/get` reads
client sessions; `/app/system/hosts/get`, `/app/system/hosts/runtime`, and
`/app/system/hosts/claim` are Hub-vantage Host inventory, management, and
first-claim. These remain Hub-owned with cloud relay and Space membership. See
[SYSTEM.md](SYSTEM.md).