@mhome/app-facade-protocol 1.66.0 → 1.71.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,
@@ -73,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
@@ -134,6 +144,15 @@ 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.
 
+Final completion can return `completed: false` with `submission.status: accepted`:
+the business owner has saved the input but installation has not finished. Clients
+retain the completion command ID and may query `/app/interaction-flow/submission/status`
+or explicitly call `/app/interaction-flow/submission/retry` with the original source
+and that ID. Neither call requires a live interactive session. Responses distinguish
+`notFound`, `accepted`, and `completed` with the original result. Clients cannot
+supply an owner or handler; current Node binding and Space access are checked again.
+Retry is explicit, and closing the interaction does not cancel accepted business data.
+
 `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
@@ -225,3 +244,17 @@ Business operation permissions are declared once in [the authorization manifest]
 
 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/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
+      }
+    }
+  ]
+}

package/fixtures/interaction-flow.conformance.json

@@ -70,9 +70,28 @@
     "completed": true,
     "result": {
       "providerConnectionId": "provider-1"
+    },
+    "submission": {
+      "status": "completed",
+      "result": {
+        "providerConnectionId": "provider-1"
+      }
     }
   },
   "cancelResponse": {
     "cancelled": true
+  },
+  "submissionRequest": {
+    "source": {
+      "kind": "plugin",
+      "nodeType": "camera",
+      "nodeId": "camera-1",
+      "flowId": "provider.connect",
+      "subjectId": "onvif"
+    },
+    "submissionId": "command-3"
+  },
+  "submissionResponse": {
+    "status": "accepted"
   }
 }