@mhome/app-facade-protocol 1.64.0 → 1.69.0

package/README.md

@@ -17,6 +17,9 @@ 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.
 
+See [resource definition, observation, history and relationship reads](contract/resource-read-v1.md)
+for shared business reads and the separate UI rendering boundary.
+
 ## Business DTO ownership
 
 A Facade owns the public business DTO for an operation. Native Agent tools, MCP,
@@ -41,7 +44,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 +52,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
@@ -69,8 +76,15 @@ 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
+App UI requests full and preserves the complete envelope through transport and SDK
+parsing. UI consumers explicitly read data and handle warnings and non-success outcomes.
+Essential YAML omits null-valued object fields recursively after domain projection.
+This shared rule also applies to error diagnostics and visible warning details.
+Full values, false, zero, strings (including empty strings), empty collections,
+array positions and a root null value are preserved. This is output-only; it
+never changes request semantics, stored data or prepared actions.
+
+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,
 view choices, excluding renderer configuration and resource payloads. Card list
@@ -218,3 +232,20 @@ 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).
+
+## Artifact delivery
+
+`/app/artifact/resolve` follows the Space execution route and can return a Host-local
+URL with its TLS identity. `/app/artifact/external/resolve` is an explicit cloud-only
+read using the same `ResolveArtifactRequest` and `ResolveArtifactResponse` contract.
+It returns a short-lived signed HTTPS URL through an externally reachable cloud
+origin. Its deadline is capped by the artifact's expiry at issuance. Issuing a URL
+does not renew retention; reading local temporary content retains the owner's
+normal idle-renewal behavior without extending an already issued URL's deadline.
+Cloud-owned content uses an object-store signed URL; local content is read from its
+owning Hub on demand. External resolution creates no cloud replica and cannot
+make an offline local owner readable. The current inline Hub bridge size limit
+still applies. Local file download remains a client workflow over ordinary resolve.

package/contract/entity-presentation-v1.md

@@ -18,5 +18,5 @@ 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;
+`{status: "success", data: ...}` 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/resource-read-v1.md

@@ -0,0 +1,75 @@
+# Resource read boundaries
+
+Business reads separate persisted definitions/configuration from current observations,
+chronological history, and one-hop resource relationships. Tenant and Space are taken
+from authenticated request context. All targets require Space read authority and
+follow the Space execution authority on both local Core and cloud.
+
+## Shared business reads
+
+| Target | Input | Business data |
+| --- | --- | --- |
+| `/app/device/detail/get` | `{ids}` | Existing ordered `items` with `device` definitions, capabilities, group membership, enabled/source metadata; no online or state fields |
+| `/app/device/state/get` | `{ids}` | Ordered `items` with `resource: {entityId, online?, onlineUpdatedAtSec?, latest}` |
+| `/app/widget/detail/get` | `{ids}` | Existing ordered `items` with `widget` configuration; no value, next or nextTimestamp |
+| `/app/widget/value/get` | `{ids}` | Ordered `items` with `resource: {widgetId, revision, value, next?, nextTimestamp?}` |
+| `/app/automation/status` | `{ids}` | Ordered `items` with `resource: {automationId, enabled, runnable, running, blocked, lastRunAt}` |
+| `/app/graph/relations/get` | `{resource: {kind, id}}` | `{resource, relations: [{from, relation, to, capabilityIds?}]}` |
+
+Observation batches accept 1–100 IDs, reject blanks, trim and deduplicate preserving
+request order. Every normalized ID gets `{requestedId, found, resource?}`; missing
+resources have `found: false, reason: "not_found"`. A known Device with no observations
+has `found: true` and `latest: []`. Unknown reachability omits `online`; it is not false.
+Device state supports visible physical devices and Device groups. Automation status
+accepts user program IDs, including retained one-time programs, not groups or internal
+Twin programs. Widget value supports Data, Button and Circadian resources. JSON null
+is a value, not a missing resource. Button values may be null.
+
+`latest` contains one record per capability: `capabilityId`, optional `state`, `event`,
+`log`. These preserve the decoded Twin observation objects and their second timestamps.
+They contain no persistence tenant/Space keys. Reads use stored latest snapshots and
+retain the existing history fallback on cache miss; they do not refresh providers.
+Definition reads do not load observations, history, related programs or visible Cards.
+
+Graph kinds are `device`, `entity`, `automation`, `widget`, `card`. Directional relations
+are Automation `uses` Device/Entity (with capability IDs), Automation `owns` Widget,
+visible Card `presents` a resource, and generated Automation `implements` Device.
+Generated program references are not editable user programs. Existing Managers and
+indexes own these relationships; this read introduces no graph database or traversal.
+It returns IDs, not recursively expanded definitions, scripts, names or runtime data.
+Hidden Device render anchors are not public Card references.
+
+Full uses the standard `{status, data}` result with structured business data. Essential
+uses the same envelope with YAML `data`; timestamps are presented in the Home timezone.
+Device list additionally omits connection/manufacturer metadata in Essential. New
+observation and graph reads preserve their bounded business fields in Essential.
+
+## UI-only reads
+
+- `/app/device/view/get`, `{deviceId}`: `{deviceId, primaryViewId, views, widgets}`.
+  Reads the unique hidden Device render definition, preserving exact Widget/Twin
+  bindings. Disabled devices can have empty definitions. Multiple anchors fail rather
+  than choosing an arbitrary visible Card. Widgets contain configuration, never values.
+- `/app/device/history/series/get`, `{deviceId, capabilityIds?: []}`:
+  `{deviceId, series}` with per-capability decoded `states`, `events`, `logs`. Empty
+  capability selection reads all series. This preserves chart structure; the shared
+  Device history Facade remains a bounded, merged business timeline.
+- `/app/dashboard/canvas/content/get`, `{canvasId}`: Canvas metadata plus Cards' static
+  titles, view bindings, layouts, settings, metadata and selected Widget definitions.
+  No observations, history, related automations or suggestions are loaded.
+
+The frontend batches selected observations after reading definitions. Automation Cards
+also read selected Automation definitions for their name and type. Canvas IDs are
+split into bounded batches and deduplicated across Cards. History is requested by an
+open detail renderer; relationships by the view that displays them. Pushes received
+during a snapshot request are applied after it lands. Switching scopes or disposing
+controllers prevents late responses from landing in another Space.
+
+House continues to use `/app/entity/presentation/get` and legacy Twin reads as its
+separate development boundary. Pod Deck retains its existing complete Card content
+reader. These consumers are not silently migrated to static Canvas responses.
+
+Generated Twin program inspection retains its internal `/automation/get`,
+`/automation/status` and `/automation/info` UI readers. These IDs are not accepted
+by the shared user-program Automation detail/status contract. User program detail
+pages use the shared definition, status and graph readers.

package/fixtures/group.conformance.json

@@ -0,0 +1,383 @@
+{
+  "valid": [
+    {
+      "definition": "ListGroupsInput",
+      "value": {}
+    },
+    {
+      "definition": "GetGroupsInput",
+      "value": {
+        "ids": [
+          "g:1",
+          "g:1",
+          "missing"
+        ]
+      }
+    },
+    {
+      "definition": "GroupPresentationInput",
+      "value": {
+        "groupId": "g:1"
+      }
+    },
+    {
+      "definition": "CreateGroupInput",
+      "value": {
+        "creationId": "11111111-1111-4111-8111-111111111111",
+        "name": "Lights",
+        "memberType": "basic.device.Device",
+        "memberIds": [
+          "lamp-a",
+          "lamp-b",
+          "lamp-a"
+        ]
+      }
+    },
+    {
+      "definition": "RenameGroupInput",
+      "value": {
+        "groupId": "g:1",
+        "name": "Renamed",
+        "expectedRevision": 3
+      }
+    },
+    {
+      "definition": "UpdateGroupMembersInput",
+      "value": {
+        "groupId": "g:1",
+        "memberIds": [
+          "lamp-b"
+        ],
+        "expectedRevision": 3
+      }
+    },
+    {
+      "definition": "DeleteGroupInput",
+      "value": {
+        "groupId": "g:1",
+        "expectedRevision": 3
+      }
+    },
+    {
+      "definition": "GroupSummary",
+      "value": {
+        "groupId": "g:11111111-1111-4111-8111-111111111111",
+        "name": "Lights",
+        "memberType": "basic.device.Device",
+        "memberCount": 2,
+        "revision": 3,
+        "applyState": "ready",
+        "createdAt": 1900000000000,
+        "updatedAt": 1900000001000
+      }
+    },
+    {
+      "definition": "GroupDetail",
+      "value": {
+        "groupId": "g:11111111-1111-4111-8111-111111111111",
+        "name": "Lights",
+        "memberType": "basic.device.Device",
+        "memberCount": 2,
+        "revision": 3,
+        "applyState": "ready",
+        "createdAt": 1900000000000,
+        "updatedAt": 1900000001000,
+        "memberIds": [
+          "lamp-a",
+          "lamp-b"
+        ],
+        "capabilities": [
+          {
+            "id": "basic.device.command.onOff",
+            "memberCount": 1
+          }
+        ],
+        "memberProblems": [
+          {
+            "memberId": "lamp-b",
+            "code": "MEMBER_UNAVAILABLE",
+            "message": "Member is unavailable"
+          }
+        ]
+      }
+    },
+    {
+      "definition": "GroupMutationOutput",
+      "value": {
+        "groupId": "g:1",
+        "revision": 4,
+        "applyState": "failed",
+        "applicationProblem": {
+          "code": "GROUP_APPLY_FAILED",
+          "message": "Retry application"
+        }
+      }
+    },
+    {
+      "definition": "DeleteGroupOutput",
+      "value": {
+        "groupId": "g:1",
+        "deleted": true
+      }
+    },
+    {
+      "definition": "ListGroupsOutput",
+      "value": {
+        "spaceId": "space",
+        "groups": [
+          {
+            "groupId": "g:11111111-1111-4111-8111-111111111111",
+            "name": "Lights",
+            "memberType": "basic.device.Device",
+            "memberCount": 2,
+            "revision": 3,
+            "applyState": "ready",
+            "createdAt": 1900000000000,
+            "updatedAt": 1900000001000
+          }
+        ]
+      }
+    },
+    {
+      "definition": "GetGroupsOutput",
+      "value": {
+        "spaceId": "space",
+        "items": [
+          {
+            "requestedId": "g:11111111-1111-4111-8111-111111111111",
+            "found": true,
+            "group": {
+              "groupId": "g:11111111-1111-4111-8111-111111111111",
+              "name": "Lights",
+              "memberType": "basic.device.Device",
+              "memberCount": 2,
+              "revision": 3,
+              "applyState": "ready",
+              "createdAt": 1900000000000,
+              "updatedAt": 1900000001000,
+              "memberIds": [
+                "lamp-a",
+                "lamp-b"
+              ],
+              "capabilities": [
+                {
+                  "id": "basic.device.command.onOff",
+                  "memberCount": 1
+                }
+              ],
+              "memberProblems": [
+                {
+                  "memberId": "lamp-b",
+                  "code": "MEMBER_UNAVAILABLE",
+                  "message": "Member is unavailable"
+                }
+              ]
+            }
+          },
+          {
+            "requestedId": "missing",
+            "found": false,
+            "reason": "not_found"
+          }
+        ]
+      }
+    }
+  ],
+  "invalid": [
+    {
+      "definition": "RenameGroupInput",
+      "value": {
+        "groupId": "g:1",
+        "name": "Renamed"
+      }
+    },
+    {
+      "definition": "UpdateGroupMembersInput",
+      "value": {
+        "groupId": "g:1",
+        "memberIds": [
+          "lamp-b"
+        ],
+        "expectedRevision": 3,
+        "name": "Unexpected"
+      }
+    },
+    {
+      "definition": "DeleteGroupInput",
+      "value": {
+        "groupId": "g:1",
+        "expectedRevision": 0
+      }
+    },
+    {
+      "definition": "CreateGroupInput",
+      "value": {
+        "creationId": "11111111-1111-4111-8111-111111111111",
+        "name": "Lights",
+        "memberType": "basic.device.Device",
+        "memberIds": [
+          "lamp-a",
+          "lamp-b",
+          "lamp-a"
+        ],
+        "members": [
+          {
+            "data": "internal"
+          }
+        ]
+      }
+    },
+    {
+      "definition": "GroupDetail",
+      "value": {
+        "groupId": "g:11111111-1111-4111-8111-111111111111",
+        "name": "Lights",
+        "memberType": "basic.device.Device",
+        "memberCount": 2,
+        "revision": 3,
+        "applyState": "ready",
+        "createdAt": 1900000000000,
+        "updatedAt": 1900000001000,
+        "memberIds": [
+          "lamp-a",
+          "lamp-b"
+        ],
+        "capabilities": [
+          {
+            "id": "basic.device.command.onOff",
+            "memberCount": 1
+          }
+        ],
+        "memberProblems": [
+          {
+            "memberId": "lamp-b",
+            "code": "MEMBER_UNAVAILABLE",
+            "message": "Member is unavailable"
+          }
+        ],
+        "twinSig": "internal"
+      }
+    },
+    {
+      "definition": "GetGroupsInput",
+      "value": {
+        "ids": [
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a",
+          "a"
+        ]
+      }
+    },
+    {
+      "definition": "GroupSummary",
+      "value": {
+        "groupId": "g:11111111-1111-4111-8111-111111111111",
+        "name": "Lights",
+        "memberType": "basic.device.Device",
+        "memberCount": 2,
+        "revision": 3,
+        "applyState": "unknown",
+        "createdAt": 1900000000000,
+        "updatedAt": 1900000001000
+      }
+    }
+  ]
+}