@mhome/app-facade-protocol 1.62.0 → 1.66.0

package/README.md

@@ -41,7 +41,7 @@ Composition does not imply a distributed transaction or automatic rollback.
 ## App result contract
 
 `control.responseDetail` selects information depth: `full` (default) returns
-`data`, while `essential` returns YAML in `text`. It is independent of action
+`data`, while `essential` returns YAML in `data`. It is independent of action
 `mode` and is never copied into business input, prepared snapshots or execution
 fingerprints. `responseFormat` and business `outputFormat` are rejected.
 
@@ -49,14 +49,18 @@ Final responses use exactly one of these shapes:
 
 ```json
 {"status":"success","data":{"items":[]}}
-{"status":"success","text":"items: []\n"}
+{"status":"success","data":"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
+Success may omit `data` for an acknowledgement; partial always carries `data`.
+The request selects the representation: Full is the business value (which may itself
+be a string); Essential is a YAML string. Do not infer response detail from its type.
+Pure acknowledgements are identical in both modes: `{"status":"success"}`. Error carries a
+`code`, `message`, and optional Full `details`. Essential errors keep code/message
+and place their projected diagnostics in YAML `data`; 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
@@ -73,7 +77,10 @@ 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.
+view choices, excluding renderer configuration and resource payloads. Card list
+returns only ID/type/title; card detail essential omits layouts. Canvas layout get
+requires one sm/md/lg size and retains every card ID/title/layout in full and essential;
+uninitialized layouts or coordinates are null.
 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
@@ -96,6 +103,10 @@ asset manifests and renderer configuration schemas. Selected release detail keep
 Revisions, installation IDs, existing override config and supported patterns remain.
 Empty mutation acknowledgements remain empty; they do not invent a new revision.
 
+Room uses one `/app/room/list` read. Every Room has `roomId`, `roomName`,
+`index`, `deviceCount`, and `deviceIds`; full and essential keep all five fields.
+Membership IDs include Device groups without expanding their members or state.
+
 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.
 
@@ -211,3 +222,6 @@ Business operation permissions are declared once in [the authorization manifest]
 `/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.
+
+UI Integration metadata uses `/app/integration/presentation/get`; see
+[the presentation contract](contract/integration-presentation-v1.md).

package/contract/entity-presentation-v1.md

@@ -0,0 +1,22 @@
+# Entity UI presentation
+
+`/app/entity/presentation/get` is a read-only App Facade for the UI. Its direct
+input is `{entityType, entityId}`; tenant, Space and caller come from authenticated
+context. It requires Space read access. It is not an Agent or MCP catalog entry.
+
+The successful data object contains `entityEntry`, nullable `entityCard`, and
+`twinAutomations`. The entry and card reuse the existing UI renderer models;
+the schema owns this boundary without duplicating their nested widget/runtime
+contracts. A missing, deleted or differently typed Twin is not found. Device
+presentation reads reuse the device manager; other Twin entities reuse the general
+manager. Ordinary Entity business detail and Group detail retain their own APIs.
+
+Device card assembly is best effort. An absent card is `null`, with an empty
+association list. Association-read failures retain the existing execution policy:
+local Core returns an empty list; cloud propagates the error. No writes or repairs
+are performed. Current Twin states still have their separate read/subscription.
+
+UI uses `control: {mode: "direct", responseDetail: "full"}` and receives the shared
+`{status: "success", data: ...}` envelope. The generic essential projection returns
+`{status: "success", text: ...}` with the same business fields rendered as YAML;
+there is no domain field reduction. This is not the compact business detail API.

package/contract/integration-presentation-v1.md

@@ -0,0 +1,27 @@
+# Integration UI presentation
+
+`/app/integration/presentation/get` is a read-only App Facade for UI consumers.
+Input is `{integrationId}` for one root Integration. Tenant, Space and caller
+come from authenticated context; Space read membership is required. Empty IDs,
+unknown fields and Provider IDs are rejected; missing Integrations are not found.
+This operation is not registered in Agent, MCP or CLI catalogs.
+
+The Space execution authority performs the complete read. Integration names and
+icons include the root and every Provider in its visible catalog, regardless of
+installation. `typeNames` labels entity types; `entityStandalone` indicates
+independent entity presentation; `groupSupported` indicates type-level group
+support. Neither boolean map describes an instance's active state. `twinNames`
+labels the root's applicable production Twin templates, not entity instances.
+Developer draft overrides belong to developer tooling, not ordinary App display.
+`capabilities` uses the shared CapabilityDescriptor, including full IDs and
+visibility. No scripts, entity instances, live states or connection data are read.
+
+Collections are always present and empty when the model has no corresponding
+metadata. Optional empty names/icons are omitted. Upstream failures propagate;
+existing metadata cache refresh policies remain in effect. No installation,
+entity synchronization or business writes are performed.
+
+UI sends `control: {mode: "direct", responseDetail: "full"}` and receives
+`{status: "success", data: ...}`. Essential retains the same business fields in
+YAML `data`; this interface has no separate field reduction. Mutating control
+modes are not supported. SDK indexes the capability array by full ID for UI use.

package/contract/pod-directory-v1.md

@@ -13,11 +13,11 @@ 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`.
+The result contains `pods`, `spaceId`, `observedAtMs`, and `sourceErrors`.
 Every row contains `registrationId`, `clientMode` (`user` or `space`), `registered`
-(true), and `connection` with `scopeId`, `state` (`connected`, `disconnected`, or
+(true), and `connection` with `spaceId`, `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`,
+`spaceId` 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.
 

package/fixtures/binding-list.response.json

@@ -9,7 +9,7 @@
         "placement": "local",
         "accountId": "bot",
         "conversationId": "group",
-        "scopeId": "home",
+        "spaceId": "home",
         "displayName": "Family",
         "createdAtMs": 1
       }

package/fixtures/entity-presentation.conformance.json

@@ -0,0 +1,54 @@
+{
+  "input": {
+    "valid": [
+      {
+        "entityType": "basic.device.Device",
+        "entityId": "device-1"
+      }
+    ],
+    "invalid": [
+      {},
+      {
+        "entityType": " ",
+        "entityId": "device-1"
+      },
+      {
+        "entityType": "basic.device.Device",
+        "entityId": ""
+      },
+      {
+        "entityType": "basic.device.Device",
+        "entityId": "device-1",
+        "scopeId": "other"
+      }
+    ]
+  },
+  "output": {
+    "valid": [
+      {
+        "entityEntry": {
+          "uid": "device-1",
+          "type": "basic.device.Device",
+          "integration": "example.device",
+          "name": "Desk lamp",
+          "active": false,
+          "data": {},
+          "capabilities": [],
+          "twinTags": [],
+          "cardCount": 0,
+          "issue": false
+        },
+        "entityCard": null,
+        "twinAutomations": []
+      }
+    ],
+    "invalid": [
+      {},
+      {
+        "entityEntry": null,
+        "entityCard": null,
+        "twinAutomations": []
+      }
+    ]
+  }
+}

package/fixtures/hub-state.configured.json

@@ -1,5 +1,5 @@
 {
-  "scopeId": "scope-1",
+  "spaceId": "scope-1",
   "configured": true,
   "hub": {
     "id": "hub-1",

package/fixtures/hub-state.revoked.json

@@ -1,5 +1,5 @@
 {
-  "scopeId": "scope-1",
+  "spaceId": "scope-1",
   "configured": false,
   "operation": {
     "kind": "REMOVE",

package/fixtures/integration-presentation.conformance.json

@@ -0,0 +1,206 @@
+{
+  "input": {
+    "valid": [
+      {
+        "integrationId": "basic.device"
+      }
+    ],
+    "invalid": [
+      {},
+      {
+        "integration": "basic.device"
+      },
+      {
+        "integrationId": ""
+      },
+      {
+        "integrationId": "  "
+      },
+      {
+        "integrationId": "basic.device",
+        "scopeId": "other"
+      },
+      {
+        "integrationId": 7
+      }
+    ]
+  },
+  "model": {
+    "integrationId": "basic.device",
+    "displayName": "Devices",
+    "iconUrl": "https://example.invalid/device.png",
+    "entityNames": {
+      "basic.device.Device": "Device",
+      "basic.device.Component": "Component"
+    },
+    "standaloneEntityTypes": [
+      "basic.device.Device"
+    ],
+    "entityGroupEnabled": {
+      "basic.device.Device": true
+    },
+    "implIntegrations": [
+      {
+        "integration": "example.device",
+        "name": "Example Provider",
+        "iconUrl": "https://example.invalid/provider.png"
+      },
+      {
+        "integration": "other.device",
+        "name": "Other Provider",
+        "iconUrl": ""
+      }
+    ],
+    "capabilities": {
+      "command.onOff": {
+        "displayName": "Power",
+        "description": "Switch power.",
+        "visibility": "full",
+        "tag": "on/off"
+      }
+    }
+  },
+  "output": {
+    "valid": [
+      {
+        "integrationId": "basic.device",
+        "integrationNames": {
+          "basic.device": "Devices",
+          "example.device": "Example Provider",
+          "other.device": "Other Provider"
+        },
+        "integrationIconUrls": {
+          "basic.device": "https://example.invalid/device.png",
+          "example.device": "https://example.invalid/provider.png"
+        },
+        "typeNames": {
+          "basic.device.Device": "Device",
+          "basic.device.Component": "Component"
+        },
+        "twinNames": {
+          "basic.device.Light": "Light"
+        },
+        "entityStandalone": {
+          "basic.device.Device": true,
+          "basic.device.Component": false
+        },
+        "groupSupported": {
+          "basic.device.Device": true
+        },
+        "capabilities": [
+          {
+            "capabilityId": "basic.device.command.onOff",
+            "type": "COMMAND",
+            "displayName": "Power",
+            "description": "Switch power.",
+            "visibility": "full",
+            "tag": "on/off"
+          }
+        ]
+      }
+    ],
+    "invalid": [
+      {
+        "integrationId": "basic.device",
+        "integrationNames": {
+          "basic.device": "Devices",
+          "example.device": "Example Provider",
+          "other.device": "Other Provider"
+        },
+        "integrationIconUrls": {
+          "basic.device": "https://example.invalid/device.png",
+          "example.device": "https://example.invalid/provider.png"
+        },
+        "typeNames": {
+          "basic.device.Device": "Device",
+          "basic.device.Component": "Component"
+        },
+        "twinNames": {
+          "basic.device.Light": "Light"
+        },
+        "entityStandalone": {
+          "basic.device.Device": true,
+          "basic.device.Component": false
+        },
+        "groupSupported": {
+          "basic.device.Device": true
+        }
+      },
+      {
+        "integrationId": "basic.device",
+        "integrationNames": {
+          "basic.device": "Devices",
+          "example.device": "Example Provider",
+          "other.device": "Other Provider"
+        },
+        "integrationIconUrls": {
+          "basic.device": "https://example.invalid/device.png",
+          "example.device": "https://example.invalid/provider.png"
+        },
+        "typeNames": {
+          "basic.device.Device": "Device",
+          "basic.device.Component": "Component"
+        },
+        "twinNames": {
+          "basic.device.Light": "Light"
+        },
+        "entityStandalone": {
+          "basic.device.Device": true,
+          "basic.device.Component": false
+        },
+        "groupSupported": {
+          "basic.device.Device": true
+        },
+        "capabilities": [
+          {
+            "capabilityId": "basic.device.command.onOff",
+            "type": "COMMAND",
+            "displayName": "Power",
+            "description": "Switch power.",
+            "visibility": "full",
+            "tag": "on/off"
+          }
+        ],
+        "entityEnabled": {
+          "basic.device.Device": true
+        }
+      },
+      {
+        "integrationId": "basic.device",
+        "integrationNames": {
+          "basic.device": "Devices",
+          "example.device": "Example Provider",
+          "other.device": "Other Provider"
+        },
+        "integrationIconUrls": {
+          "basic.device": "https://example.invalid/device.png",
+          "example.device": "https://example.invalid/provider.png"
+        },
+        "typeNames": {
+          "basic.device.Device": "Device",
+          "basic.device.Component": "Component"
+        },
+        "twinNames": {
+          "basic.device.Light": "Light"
+        },
+        "entityStandalone": {
+          "basic.device.Device": true,
+          "basic.device.Component": false
+        },
+        "groupSupported": {
+          "basic.device.Device": "yes"
+        },
+        "capabilities": [
+          {
+            "capabilityId": "basic.device.command.onOff",
+            "type": "COMMAND",
+            "displayName": "Power",
+            "description": "Switch power.",
+            "visibility": "full",
+            "tag": "on/off"
+          }
+        ]
+      }
+    ]
+  }
+}