@mhome/app-facade-protocol 1.49.2 → 1.59.0

package/README.md

@@ -17,6 +17,61 @@ 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.
 
+## App result contract
+
+`control.responseDetail` selects information depth: `full` (default) returns
+`data`, while `essential` returns YAML in `text`. It is independent of action
+`mode` and is never copied into business input, prepared snapshots or execution
+fingerprints. `responseFormat` and business `outputFormat` are rejected.
+
+Final responses use exactly one of these shapes:
+
+```json
+{"status":"success","data":{"items":[]}}
+{"status":"success","text":"items: []\n"}
+{"status":"partial","data":{"moved":["a"],"notMoved":[{"deviceId":"b","reason":"offline"}]}}
+{"status":"error","error":{"code":"PRECONDITION_FAIL","message":"The object changed"}}
+{"status":"cancelled"}
+```
+
+Success and partial carry exactly one of `data` or `text`. Error carries a
+`code`, `message`, and optional `details`; success, partial and cancellation may
+carry structured `warnings`. Resource state belongs inside data: successfully
+reading a failed job is still a successful invocation. Partial is not complete
+success and must remain visible to the caller. Transport admission failures keep
+their transport status and retry metadata.
+
+Prepare returns its fixed structured control DTO (`preparedActionId`,
+`approvalToken`, `target`, `status`, `preview`, `expiresAt`). Commit executes the
+stored snapshot and caches the full business result; presentation happens after
+execution or replay. Reject returns cancellation. Response detail never changes
+approval meaning or permission checks. Operation and HITL continuation protocols
+are separate from this result envelope.
+
+App UI requests full and unwraps the envelope at its transport boundary. Agent
+and MCP public results use essential; internal workflow reads use full. The CLI
+uses `--response-detail full|essential`, and the bundled external Skill requests
+essential. Dashboard essential projection keeps card identity, title, type,
+layouts and view choices, excluding renderer configuration and resource payloads.
+Device brief-list essential retains identity, room, capability IDs, Integration and
+availability, omitting `connectId`, `manufacturerId` and `manufacturerName`.
+Selected Device detail, history, recent activity and mutation outcomes keep their
+public business fields. Device bulk list remains a CLI-only surface.
+Targets without a dedicated projection retain their business fields in YAML;
+essential does not promise a smaller field set for every domain. Targets own that selection.
+
+The [response schema](schema/facade-response.v1.schema.json) and shared
+[presentation fixtures](fixtures/presentation/cases.json) define the wire
+invariants and cross-runtime projection checks. Domain schemas describe the
+inner `data` DTO. `/pod/deck/*`, `/pod/talk/*` and legacy Controllers retain their
+separate wire contracts.
+
+The npm protocol descriptor exports this response schema as `schemas.response`.
+Protocol verification compiles it and the Conversation execution envelope with
+strict AJV settings, checks their shared response definition, and validates the
+same positive/negative response fixtures used by Rust. Package staging tests
+verify that the schema is available through the published descriptor.
+
 `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.
@@ -49,9 +104,11 @@ 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`;
 User Pod enrollment uses a one-time login approval; activation is confirmed on the paired device.
 
-`/app/pod/list` reads registered Pod Clients in the active Space, including
-connections that are currently absent. `/app/host/list` reads historical Host
-registrations without granting management access; see the
+`/app/pod/list` combines the current User's personal registrations with the current
+Space's Space-owned Pods, including offline entries. `/app/pod/rename` updates a
+personal registration name. See [Pod directory](contract/pod-directory-v1.md). `/app/host/list` combines Host registrations with current observations and details.
+`/app/host/directory/list` is the historical registration input used by native
+list composition; it does not grant management access. See the
 [Host directory contract](contract/host-directory-v1.md). Native commissioning
 uses the existing device protocols; the Agent resumes only after verifying the
 resulting registration. Host completion identifies both `hostId` and `env`.
@@ -109,3 +166,9 @@ Client sessions. Host inventory and operations use `/app/system/hosts/get` and
 current Core. First claim is direct LAN only. See [SYSTEM.md](SYSTEM.md).
 
 Business operation permissions are declared once in [the authorization manifest](manifest/authorization.v1.json), consumed by Core and Lion. See [business authorization](contract/authorization-v1.md).
+
+## Matter management reads
+
+`/app/matter/device/list` is the management inventory, grouped by Fabric node. It is distinct from the Plugin's Integration enumeration `/matter/device/list`. Its `sourceDeviceId` values identify Plugin projections, not Twin entities. Nodes without projected devices remain visible; `membershipComplete`, `inventoryComplete`, per-node completeness and `errors` describe partial observations. Lists omit endpoints and attribute payloads.
+
+`/app/matter/fabric/node/detail` accepts 1–20 unique `matterNodeIds`, returning an ordered item result or error for each ID. The request uses string IDs without numeric coercion. See `schema/matter-management.v1.schema.json`. All `/app/matter/` operations execute through the Space's Hub irrespective of scope execution mode. Node removal is a manual UI/CLI capability, not a delegated Agent/MCP tool.

package/contract/pod-commissioning-v1.md

@@ -120,8 +120,13 @@ and responses are bounded to 64 KiB including encryption overhead.
 ```
 
 `env` must match the native Client runtime (`prod`, `dev`, `e2e`).
-`podId` is included when activation is in flight or durably completed, so a
-new session can observe completion without issuing another credential.
+`podId` and `clientMode` (`user` or `space`) are included together when activation
+is in flight or durably completed. A new session reads both from the secure
+device response before resuming; a missing or unknown mode fails the attempt.
+This observes completion without issuing another credential. Native completed
+enrollment sessions return both fields. HITL passes this receipt to its handler,
+which verifies exactly the corresponding personal or Space enrollment source;
+it never probes the other source or treats the mode itself as proof of success.
 `platform` is diagnostic only. `wifiConfigured` is true when the pod kept a
 working network across logout; the commissioner then skips the Wi-Fi steps after
 confirming connectivity with `prov-config` status. Inside a Wi-Fi change window
@@ -249,8 +254,8 @@ accepted.
 
 `podId` identifies a single approval attempt, not the durable device or authenticated
 User. The durable `registrationId` derives from the business User and the validated
-persistent device-key fingerprint. `POST /api/v1/pod/list` returns that ID;
-`/api/v1/pod/rename` accepts `{registrationId, name}` with ordinary User login.
+persistent device-key fingerprint. `/app/pod/list` returns that ID;
+`/app/pod/rename` accepts `{registrationId, name}` with authenticated User authority.
 Successful authentication atomically creates the registration if absent and records
 completion on the consumed approval. Retries preserve the initial registration and
 current display name. Unauthenticated attempts create no device-list entry.
@@ -472,19 +477,13 @@ independent and are never issued by this flow.
 
 ## Registered Pod list
 
-`/app/pod/list` takes empty input and lists persisted Pod Clients in the current
-Space, including disconnected registrations. A personal caller sees their own
-User Pods and Space-owned Pods. Rows contain `appClientId`, `clientMode`,
-`scopeId`, `registered`, `connected` and `observationSource` (`hub` or `cloud`);
-the envelope includes `observedAtMs`. Connection status is observed from that
-execution endpoint, not a statement about physical power or LAN reachability.
-Native clients combine this result with their own discovery observations.
-Never merge a Bluetooth short ID with a registered identity without proof.
-This read does not issue credentials or change Pod identity.
+The public `/app/pod/list` Facade combines all current-User personal registrations
+and current-Space Space-owned Pod registrations. UI and tools share this result.
+`registrationId` identifies the durable registration; it is not the enrollment
+`podId` used by native commissioning. Connection observations are separately
+scoped and may be unknown. See [Pod directory](pod-directory-v1.md) for fields,
+aggregation, failure handling and personal display-name updates.
 
-
-`appClientId` identifies a registered application client; it is not the enrollment
-`podId` used by native commissioning. The list does not invent that association.
 `/app/pod/enrollment/get` takes `{podId}` and returns `{podId, clientMode: "user",
 registered}` from the authenticated user's successful receipt for that exact attempt.
 An older registration for the same device cannot complete a different attempt.

package/contract/pod-directory-v1.md

@@ -0,0 +1,51 @@
+# Pod directory
+
+`/app/pod/list` is a Space-mode-routed, direct, read-only Facade call with empty
+input. It requires a personal User and read access to the current Space. It combines
+all completed personal Pod registrations owned by that User with registered
+Space-owned Pods in that Space. Another User's personal Pods and other Spaces'
+Pods are excluded. Offline registrations remain; incomplete commissioning attempts
+and nearby discovery candidates are not registrations.
+
+A local Space composes this result in Core, reading its own Space inventory and
+obtaining personal registrations through the authenticated private cloud control
+bridge. A cloud Space composes it in cloud. LLM placement does not change this
+owner. Cloud entrypoints forward local-Space business to Core; only an unavailable
+Hub transport permits the explicit read-only registration fallback below.
+
+The result contains `pods`, `scopeId`, `observedAtMs`, and `sourceErrors`.
+Every row contains `registrationId`, `clientMode` (`user` or `space`), `registered`
+(true), and `connection` with `scopeId`, `state` (`connected`, `disconnected`, or
+`unknown`), and `source` (`hub`, `cloud`, or `unavailable`). Space rows also contain
+`scopeId` and `appClientId`. Personal rows contain the saved `name`, `deviceId`,
+`model`, `platform`, `firmwareVersion`, `issuedAt`, and `activatedAt`.
+No tokens, enrollment grants, credential IDs or private keys are returned.
+
+Connection is an observation in the indicated Space, not global power state.
+Personal registration IDs are keyed by User and device public-key fingerprint;
+personal connection IDs do not carry that fingerprint. The directory does not
+join them by name or hardware ID. Personal connection state is therefore unknown.
+Space registration IDs are their authenticated appClientId and can be correlated.
+When a local Hub cannot be queried, the cloud's persisted Space registrations
+remain visible with unknown connection state and `sourceErrors.space`. The cache
+may omit registrations not yet synchronized; it must not imply a complete live
+snapshot. Cloud presence lookup failures likewise retain saved Space records
+as unknown, with an explicit source error. A successful empty presence lookup
+can establish disconnection. Registration read failures fail the call instead
+of fabricating an empty inventory; authorization and request failures remain errors.
+
+`/app/pod/space/list` is an internal composition target, not a separate Agent,
+MCP or CLI operation. Scope-mode routing reads the Hub for a local Space or cloud
+inventory for a cloud Space. It returns only Space-owned Pod registrations.
+UI, Agent, MCP and CLI all use `/app/pod/list`; UI groups by clientMode.
+
+`/app/pod/rename` is a direct, idempotent write with exactly `registrationId` and
+`name` (trimmed, 1–64 characters). The authenticated User is the owner; request
+input cannot select a User. It updates only that personal registration's display
+name and returns `{registrationId,name}`. It works while the Pod is offline and
+does not change credentials, ownership, networking or the Pod's local settings.
+It has no prepare/commit or HITL requirement. Space Pod rename is not provided.
+The CLI is `meow pod rename <registrationId> <name>`; Agent/MCP use `pod_rename`.
+
+Personal login approve/redeem and Space commissioning retain their existing
+protocols. Factory reset is available only on the Pod itself, not remotely.