@mhome/app-facade-protocol 1.49.2 → 1.57.0

package/README.md

@@ -17,6 +17,57 @@ 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.
+Other targets currently 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 +100,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 +162,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/fixtures/presentation/cases.json

@@ -0,0 +1,508 @@
+[
+  {
+    "name": "dashboard-detail",
+    "target": "/app/dashboard/card/detail/get",
+    "data": {
+      "scopeId": "space-1",
+      "items": [
+        {
+          "cardId": "card-1",
+          "status": "found",
+          "card": {
+            "cardId": "card-1",
+            "type": "widget",
+            "title": "Power",
+            "layouts": {
+              "sm": {
+                "x": 0,
+                "y": 0,
+                "width": 2,
+                "height": 2
+              }
+            },
+            "views": [
+              {
+                "id": "power",
+                "name": "Power",
+                "source": {
+                  "type": "widget",
+                  "baseId": "automation-1",
+                  "widgetId": "widget-1"
+                },
+                "pattern": "default"
+              }
+            ],
+            "primaryViewId": "power",
+            "widgets": [
+              {
+                "widgetId": "widget-1",
+                "name": "Power",
+                "widgetType": "DATA",
+                "dataType": "NUMBER"
+              }
+            ]
+          },
+          "canvasId": "canvas-1"
+        },
+        {
+          "cardId": "gone",
+          "status": "not_found"
+        }
+      ]
+    },
+    "status": "success",
+    "essential": {
+      "scopeId": "space-1",
+      "items": [
+        {
+          "cardId": "card-1",
+          "status": "found",
+          "card": {
+            "cardId": "card-1",
+            "type": "widget",
+            "title": "Power",
+            "layouts": {
+              "sm": {
+                "x": 0,
+                "y": 0,
+                "width": 2,
+                "height": 2
+              }
+            },
+            "primaryViewId": "power",
+            "views": [
+              {
+                "id": "power",
+                "name": "Power"
+              }
+            ],
+            "viewCount": 1
+          },
+          "canvasId": "canvas-1"
+        },
+        {
+          "cardId": "gone",
+          "status": "not_found"
+        }
+      ]
+    }
+  },
+  {
+    "name": "brief-does-not-invent-view-count",
+    "target": "/app/dashboard/card/list",
+    "data": {
+      "cards": [
+        {
+          "cardId": "card-1",
+          "type": "entity",
+          "title": "Lamp"
+        }
+      ]
+    },
+    "status": "success",
+    "essential": {
+      "cards": [
+        {
+          "cardId": "card-1",
+          "type": "entity",
+          "title": "Lamp"
+        }
+      ]
+    }
+  },
+  {
+    "name": "room-partial",
+    "target": "/app/room/devices/move",
+    "data": {
+      "moved": [
+        "a"
+      ],
+      "notMoved": [
+        {
+          "deviceId": "b",
+          "reason": "offline"
+        }
+      ]
+    },
+    "status": "partial",
+    "essential": {
+      "moved": [
+        "a"
+      ],
+      "notMoved": [
+        {
+          "deviceId": "b",
+          "reason": "offline"
+        }
+      ]
+    }
+  },
+  {
+    "name": "query-resource-failed",
+    "target": "/app/plugin/enable/status",
+    "data": {
+      "status": "failed",
+      "success": false,
+      "reason": "download failed"
+    },
+    "status": "success",
+    "essential": {
+      "status": "failed",
+      "success": false,
+      "reason": "download failed"
+    }
+  },
+  {
+    "name": "explicit-mutation-failed",
+    "target": "/app/room/delete",
+    "data": {
+      "success": false,
+      "message": "Room changed"
+    },
+    "status": "error",
+    "code": "OPERATION_FAILED"
+  },
+  {
+    "name": "camera-plugin-failed",
+    "target": "/app/plugin/camera/connection/disconnect",
+    "data": {
+      "data": {
+        "ok": false,
+        "reason": "CONNECTION_CHANGED"
+      }
+    },
+    "status": "error",
+    "code": "PLUGIN_OPERATION_FAILED"
+  },
+  {
+    "name": "null-is-a-valid-full-value",
+    "target": "/app/test/read",
+    "data": null,
+    "status": "success",
+    "essential": null
+  },
+  {
+    "name": "automation-list",
+    "target": "/app/automation/list",
+    "status": "success",
+    "data": {
+      "automations": [
+        {
+          "id": "a1",
+          "name": "Morning",
+          "description": "Turn on light",
+          "type": "TASK_FLOW",
+          "enabled": true,
+          "singleUse": false,
+          "createdAt": 1,
+          "tags": [
+            "internal"
+          ]
+        }
+      ]
+    },
+    "essential": {
+      "automations": [
+        {
+          "id": "a1",
+          "name": "Morning",
+          "description": "Turn on light",
+          "type": "TASK_FLOW",
+          "enabled": true,
+          "singleUse": false
+        }
+      ]
+    }
+  },
+  {
+    "name": "automation-detail",
+    "target": "/app/automation/detail/get",
+    "status": "success",
+    "data": {
+      "automations": [
+        {
+          "id": "a1",
+          "name": "Morning",
+          "description": "Turn on light",
+          "type": "TASK_FLOW",
+          "enabled": true,
+          "singleUse": false,
+          "hasExpire": false,
+          "usedCapabilities": [
+            "light.command.on"
+          ],
+          "memberIds": [],
+          "inputVars": [
+            {
+              "name": "$room",
+              "type": "String",
+              "description": "Room"
+            }
+          ],
+          "scriptHash": "source-hash",
+          "script": {
+            "script": "private source",
+            "scripts": {
+              "function": "private"
+            }
+          },
+          "updatedAt": 2,
+          "descriptionTemplate": "Turn on {! $room !}"
+        }
+      ]
+    },
+    "essential": {
+      "automations": [
+        {
+          "id": "a1",
+          "name": "Morning",
+          "description": "Turn on light",
+          "type": "TASK_FLOW",
+          "enabled": true,
+          "singleUse": false,
+          "hasExpire": false,
+          "usedCapabilities": [
+            "light.command.on"
+          ],
+          "memberIds": [],
+          "inputVars": [
+            {
+              "name": "$room",
+              "type": "String",
+              "description": "Room"
+            }
+          ],
+          "scriptHash": "source-hash",
+          "descriptionTemplate": "Turn on {! $room !}"
+        }
+      ]
+    }
+  },
+  {
+    "name": "automation-now",
+    "target": "/app/automation/activity/now/list",
+    "status": "success",
+    "data": {
+      "automations": [
+        {
+          "automationId": "a1",
+          "automationName": "Morning",
+          "automationType": "TASK_FLOW",
+          "origin": "RECURRING",
+          "description": "duplicate"
+        }
+      ]
+    },
+    "essential": {
+      "automations": [
+        {
+          "automationId": "a1",
+          "automationName": "Morning",
+          "automationType": "TASK_FLOW",
+          "origin": "RECURRING"
+        }
+      ]
+    }
+  },
+  {
+    "name": "automation-recent",
+    "target": "/app/automation/activity/recent/list",
+    "status": "success",
+    "data": {
+      "since": "10min",
+      "from": 0,
+      "until": 100,
+      "activities": [
+        {
+          "automationId": "a1",
+          "automationName": "Morning",
+          "automationType": "TASK_FLOW",
+          "origin": "RECURRING",
+          "activityType": "RUN_FAILED",
+          "timestamp": 100,
+          "instanceId": "run",
+          "threadId": 0,
+          "error": true,
+          "panic": false,
+          "actorUserId": "user",
+          "clientId": "client",
+          "description": "duplicate"
+        }
+      ]
+    },
+    "essential": {
+      "since": "10min",
+      "from": 0,
+      "until": 100,
+      "activities": [
+        {
+          "automationId": "a1",
+          "automationName": "Morning",
+          "automationType": "TASK_FLOW",
+          "origin": "RECURRING",
+          "activityType": "RUN_FAILED",
+          "timestamp": 100,
+          "instanceId": "run",
+          "threadId": 0,
+          "error": true,
+          "panic": false
+        }
+      ]
+    }
+  },
+  {
+    "name": "automation-diagnostic-list",
+    "target": "/app/automation/diagnostic/list",
+    "status": "success",
+    "data": {
+      "diagnostics": [
+        {
+          "automationId": "a1",
+          "name": "Morning",
+          "threadId": 0,
+          "instanceId": "run",
+          "timestamp": 100,
+          "status": "failed",
+          "reportMode": "STD",
+          "logCount": 2,
+          "omittedLogs": 1,
+          "truncated": true,
+          "logsMissing": false,
+          "failure": {
+            "message": "device unavailable",
+            "code": "TIMEOUT"
+          },
+          "revision": 3,
+          "startedAt": 90,
+          "finishedAt": 100
+        }
+      ]
+    },
+    "essential": {
+      "diagnostics": [
+        {
+          "automationId": "a1",
+          "name": "Morning",
+          "threadId": 0,
+          "instanceId": "run",
+          "timestamp": 100,
+          "status": "failed",
+          "reportMode": "STD",
+          "logCount": 2,
+          "omittedLogs": 1,
+          "truncated": true,
+          "logsMissing": false,
+          "failure": {
+            "message": "device unavailable",
+            "code": "TIMEOUT"
+          }
+        }
+      ]
+    }
+  },
+  {
+    "name": "automation-diagnostic-detail",
+    "target": "/app/automation/diagnostic/detail",
+    "status": "success",
+    "data": {
+      "diagnostic": {
+        "automationId": "a1",
+        "name": "Morning",
+        "threadId": 0,
+        "instanceId": "run",
+        "timestamp": 100,
+        "status": "failed",
+        "reportMode": "STD",
+        "logCount": 2,
+        "omittedLogs": 1,
+        "truncated": true,
+        "logsMissing": false,
+        "failure": {
+          "message": "device unavailable",
+          "code": "TIMEOUT"
+        },
+        "revision": 3,
+        "startedAt": 90,
+        "finishedAt": 100
+      },
+      "logs": [
+        {
+          "level": "INFO",
+          "message": "Invoked device",
+          "context": {
+            "id": "light"
+          }
+        },
+        {
+          "level": "ERROR",
+          "message": "Timed out"
+        }
+      ]
+    },
+    "essential": {
+      "diagnostic": {
+        "automationId": "a1",
+        "name": "Morning",
+        "threadId": 0,
+        "instanceId": "run",
+        "timestamp": 100,
+        "status": "failed",
+        "reportMode": "STD",
+        "logCount": 2,
+        "omittedLogs": 1,
+        "truncated": true,
+        "logsMissing": false,
+        "failure": {
+          "message": "device unavailable",
+          "code": "TIMEOUT"
+        },
+        "revision": 3,
+        "startedAt": 90,
+        "finishedAt": 100
+      },
+      "logs": [
+        {
+          "level": "INFO",
+          "message": "Invoked device",
+          "context": {
+            "id": "light"
+          }
+        },
+        {
+          "level": "ERROR",
+          "message": "Timed out"
+        }
+      ]
+    }
+  },
+  {
+    "name": "automation-snapshot-list",
+    "target": "/app/automation/snapshot/list",
+    "status": "success",
+    "data": {
+      "automationId": "a1",
+      "snapshots": [
+        {
+          "snapshotId": "v1",
+          "createdAt": 90,
+          "description": "Prior behavior",
+          "type": "TASK_FLOW",
+          "script": {
+            "script": "private"
+          }
+        }
+      ]
+    },
+    "essential": {
+      "automationId": "a1",
+      "snapshots": [
+        {
+          "snapshotId": "v1",
+          "createdAt": 90,
+          "description": "Prior behavior",
+          "type": "TASK_FLOW"
+        }
+      ]
+    }
+  }
+]

package/fixtures/routing/cases.json

@@ -446,5 +446,197 @@
     "hubReady": false,
     "cloudReady": false,
     "entry": "unavailable"
+  },
+  {
+    "target": "/app/pod/rename",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": true,
+    "entry": "cloud"
+  },
+  {
+    "target": "/app/pod/rename",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": false,
+    "entry": "unavailable"
+  },
+  {
+    "target": "/app/pod/rename",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": true,
+    "entry": "cloud"
+  },
+  {
+    "target": "/app/pod/rename",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": false,
+    "entry": "unavailable"
+  },
+  {
+    "target": "/app/pod/space/list",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": true,
+    "entry": "hub"
+  },
+  {
+    "target": "/app/pod/space/list",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": false,
+    "entry": "hub"
+  },
+  {
+    "target": "/app/pod/space/list",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": true,
+    "entry": "cloud"
+  },
+  {
+    "target": "/app/pod/space/list",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": false,
+    "entry": "unavailable"
+  },
+  {
+    "target": "/app/pod/list",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": true,
+    "entry": "hub"
+  },
+  {
+    "target": "/app/pod/list",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": false,
+    "entry": "hub"
+  },
+  {
+    "target": "/app/pod/list",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": true,
+    "entry": "cloud"
+  },
+  {
+    "target": "/app/pod/list",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": false,
+    "entry": "unavailable"
+  },
+  {
+    "target": "/app/host/list",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": true,
+    "entry": "hub"
+  },
+  {
+    "target": "/app/host/list",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": false,
+    "entry": "hub"
+  },
+  {
+    "target": "/app/host/list",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": true,
+    "entry": "cloud"
+  },
+  {
+    "target": "/app/host/list",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": false,
+    "entry": "unavailable"
+  },
+  {
+    "target": "/app/host/metrics",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": true,
+    "entry": "hub"
+  },
+  {
+    "target": "/app/host/metrics",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": false,
+    "entry": "hub"
+  },
+  {
+    "target": "/app/host/metrics",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": true,
+    "entry": "cloud"
+  },
+  {
+    "target": "/app/host/metrics",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": false,
+    "entry": "unavailable"
+  },
+  {
+    "target": "/app/host/service/restart",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": true,
+    "entry": "hub"
+  },
+  {
+    "target": "/app/host/service/restart",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": false,
+    "entry": "hub"
+  },
+  {
+    "target": "/app/host/service/restart",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": true,
+    "entry": "cloud"
+  },
+  {
+    "target": "/app/host/service/restart",
+    "execution": "scopeMode",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": false,
+    "entry": "unavailable"
   }
 ]

package/manifest/app-facade.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.app-facade.v1",
-  "contractVersion": "1.49.2",
+  "contractVersion": "1.57.0",
   "callSchema": "schema/facade-call.v1.schema.json",
   "routing": "manifest/routing.v1.json",
   "routingSchema": "schema/routing.v1.schema.json",
@@ -32,7 +32,10 @@
       "enrollmentTargets": [
         "/app/pod/enrollment/get",
         "/app/pod/space/enrollment/get"
-      ]
+      ],
+      "renameTarget": "/app/pod/rename",
+      "spaceInventoryTarget": "/app/pod/space/list",
+      "directoryContract": "contract/pod-directory-v1.md"
     },
     "hostProvision": {
       "targets": "manifest/host-provision-targets.v1.json",
@@ -94,7 +97,8 @@
         "/app/system/instances/get",
         "/app/system/clients/get",
         "/app/system/hosts/get",
-        "/app/system/hosts/runtime"
+        "/app/system/hosts/runtime",
+        "/app/system/hosts/permissions"
       ]
     },
     "integration": {
@@ -156,7 +160,22 @@
       "firstClaimTransport": "directLanOnly",
       "authorizationTarget": "/app/host/authorization",
       "authorizationSchema": "schema/host-authorization.v1.schema.json",
-      "listTarget": "/app/host/list"
+      "listTarget": "/app/host/list",
+      "requestTargets": [
+        "/app/host/list",
+        "/app/host/metrics",
+        "/app/host/administrators/list",
+        "/app/host/administrator/request",
+        "/app/host/administrator/status",
+        "/app/host/administrator/cancel",
+        "/app/host/administrator/approve",
+        "/app/host/administrator/reject",
+        "/app/host/permissions/get",
+        "/app/host/service/install",
+        "/app/host/service/restart"
+      ],
+      "requestSchema": "schema/host-management.v1.schema.json",
+      "directoryTarget": "/app/host/directory/list"
     },
     "clientAppearance": {
       "schema": "schema/client-appearance.v1.schema.json",
@@ -214,5 +233,6 @@
     }
   },
   "authorization": "manifest/authorization.v1.json",
-  "delegatedCallSchema": "schema/delegated-call.v1.schema.json"
+  "delegatedCallSchema": "schema/delegated-call.v1.schema.json",
+  "responseSchema": "schema/facade-response.v1.schema.json"
 }

package/manifest/host-provision-targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.host-provision.targets.v1",
-  "contractVersion": "1.49.2",
+  "contractVersion": "1.57.0",
   "contract": "contract/host-provisioning-v1.md",
   "localTargets": [
     "/local/host/provision/start",

package/manifest/hub-targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.hub.targets.v1",
-  "contractVersion": "1.49.2",
+  "contractVersion": "1.57.0",
   "appTargets": [
     "/app/hub/get",
     "/app/hub/remove",

package/manifest/pod-targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.pod.targets.v1",
-  "contractVersion": "1.49.2",
+  "contractVersion": "1.57.0",
   "contract": "contract/pod-commissioning-v1.md",
   "localTargets": [
     "/local/pod/discovery/start",

package/manifest/routing.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.app-facade.routing.v1",
-  "contractVersion": "1.49.2",
+  "contractVersion": "1.57.0",
   "targetPrefix": "/app/",
   "default": {
     "execution": "scopeMode"
@@ -32,8 +32,9 @@
       "/app/messaging/binding/list",
       "/app/messaging/bind/code/create",
       "/app/messaging/unbind",
-      "/app/host/list",
-      "/app/pod/enrollment/get"
+      "/app/pod/enrollment/get",
+      "/app/host/directory/list",
+      "/app/pod/rename"
     ],
     "scopeModeTargets": [
       "/app/artifact/resolve",
@@ -46,8 +47,20 @@
       "/app/artifact/upload/cancel",
       "/app/system/instances/get",
       "/app/system/clients/get",
-      "/app/pod/list",
-      "/app/pod/space/enrollment/get"
+      "/app/pod/space/enrollment/get",
+      "/app/pod/space/list",
+      "/app/host/list",
+      "/app/host/metrics",
+      "/app/host/administrators/list",
+      "/app/host/administrator/request",
+      "/app/host/administrator/status",
+      "/app/host/administrator/cancel",
+      "/app/host/administrator/approve",
+      "/app/host/administrator/reject",
+      "/app/host/permissions/get",
+      "/app/host/service/install",
+      "/app/host/service/restart",
+      "/app/pod/list"
     ],
     "hubPrefixes": [
       "/app/plugin/",
@@ -55,7 +68,8 @@
       "/app/object-storage/",
       "/app/runtime/",
       "/app/system/hosts/",
-      "/app/person/"
+      "/app/person/",
+      "/app/matter/"
     ],
     "requestPlacementPrefixes": [
       "/app/messaging/"

package/manifest/targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.messaging.targets.v1",
-  "contractVersion": "1.49.2",
+  "contractVersion": "1.57.0",
   "requestTargets": [
     "/app/messaging/provider/list",
     "/app/messaging/provider-account/list",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhome/app-facade-protocol",
-  "version": "1.49.2",
+  "version": "1.57.0",
   "description": "Build-time protocol artifacts for mhome.app-facade",
   "license": "MIT",
   "repository": {

package/protocol.json

@@ -1,6 +1,6 @@
 {
   "protocol": "mhome.app-facade",
-  "contractVersion": "1.49.2",
+  "contractVersion": "1.57.0",
   "manifest": "manifest/app-facade.v1.json",
   "schemas": {
     "hostAuthorization": "schema/host-authorization.v1.schema.json",
@@ -9,6 +9,7 @@
     "cardSkinPackage": "schema/card-skin-package.v1.schema.json",
     "cardSkins": "schema/card-skins.v1.schema.json",
     "call": "schema/facade-call.v1.schema.json",
+    "response": "schema/facade-response.v1.schema.json",
     "frame": "schema/messaging-frame.v3.schema.json",
     "interactionFlow": "schema/interaction-flow-app.v1.schema.json",
     "routing": "schema/routing.v1.schema.json",

package/schema/facade-call.v1.schema.json

@@ -14,7 +14,7 @@
         "mode": { "enum": ["direct", "prepare", "commit", "reject"] },
         "preparedActionId": { "type": "string", "minLength": 1, "pattern": ".*\\S.*" },
         "approvalToken": { "type": "string", "minLength": 1, "pattern": ".*\\S.*" },
-        "responseFormat": { "enum": ["json", "text"] }
+        "responseDetail": { "enum": ["full", "essential"] }
       },
       "allOf": [
         {

package/schema/facade-response.v1.schema.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "App Facade final response",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status"
+      ],
+      "properties": {
+        "status": {
+          "const": "success"
+        },
+        "data": true,
+        "text": {
+          "type": "string"
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/problem"
+          }
+        }
+      },
+      "oneOf": [
+        {
+          "required": [
+            "data"
+          ],
+          "properties": {
+            "data": true
+          }
+        },
+        {
+          "required": [
+            "text"
+          ],
+          "properties": {
+            "text": true
+          }
+        }
+      ]
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status"
+      ],
+      "properties": {
+        "status": {
+          "const": "partial"
+        },
+        "data": true,
+        "text": {
+          "type": "string"
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/problem"
+          }
+        }
+      },
+      "oneOf": [
+        {
+          "required": [
+            "data"
+          ],
+          "properties": {
+            "data": true
+          }
+        },
+        {
+          "required": [
+            "text"
+          ],
+          "properties": {
+            "text": true
+          }
+        }
+      ]
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "error"
+      ],
+      "properties": {
+        "status": {
+          "const": "error"
+        },
+        "error": {
+          "$ref": "#/$defs/problem"
+        }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status"
+      ],
+      "properties": {
+        "status": {
+          "const": "cancelled"
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/problem"
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "problem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        },
+        "details": true
+      }
+    }
+  }
+}

package/schema/pod-commission.v1.schema.json

@@ -195,6 +195,12 @@
           "type": "string"
         }
       }
+    },
+    "clientMode": {
+      "enum": [
+        "user",
+        "space"
+      ]
     }
   },
   "allOf": [
@@ -331,10 +337,12 @@
       },
       "then": {
         "properties": {
-          "podId": {}
+          "podId": {},
+          "clientMode": {}
         },
         "required": [
-          "podId"
+          "podId",
+          "clientMode"
         ]
       }
     },
@@ -365,6 +373,14 @@
               "required": [
                 "authorization"
               ]
+            },
+            {
+              "properties": {
+                "clientMode": {}
+              },
+              "required": [
+                "clientMode"
+              ]
             }
           ]
         }

package/schema/system-hosts.v1.schema.json

@@ -25,6 +25,7 @@
         "additionalProperties": false,
         "required": [
           "hostId",
+          "env",
           "hostName",
           "hostType",
           "source",
@@ -362,6 +363,13 @@
               "string",
               "null"
             ]
+          },
+          "env": {
+            "enum": [
+              "prod",
+              "dev",
+              "e2e"
+            ]
           }
         }
       }