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 FacadeCalls; 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.

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.