@mhome/app-facade-protocol 1.118.4 → 1.125.0

package/README.md

@@ -22,6 +22,8 @@ identity. Core-to-Node routes and provider runtime models belong to
 
 See [resource definition, observation, history and relationship reads](contract/resource-read-v1.md)
 for shared business reads and the separate UI rendering boundary.
+Device-only rendering, online rows and chart series use the
+[Device UI presentation contract](contract/device-presentation-v1.md).
 
 See [Agent LLM settings](contract/agent-llm-v1.md) for active-mode reads,
 independent saved configuration and Provider Operation boundaries.
@@ -47,6 +49,25 @@ results and compose real Facade calls; they are not alternative DTOs for a singl
 Facade operation. A UI view model may derive display state after the SDK boundary.
 Composition does not imply a distributed transaction or automatic rollback.
 
+## Full values and Essential presentation
+
+Full preserves canonical typed values, numeric instants and source units. Business execution,
+caching, aggregation, media validation and UI consumers use Full. Only Essential replaces
+explicitly tagged runtime primitives with display text. Numeric timestamp fields use the
+shared `manifest/presentation-times.v1.json` paths and declared units; arbitrary numbers,
+field names and provider payloads are never guessed. Declared decimal-string Storage times
+are rendered at their explicit paths; Full keeps the Storage wire types.
+
+Timestamp text includes Home's IANA timezone, offset and millisecond precision when present.
+Missing or invalid Home timezone uses UTC. User/connection operations have no Space presentation context and use UTC/source units; an incidental Space ID never grants Home/preference reads. Scope temperature/length/weight preferences apply
+only to Essential unit display. Native Agent workflows extract typed facts and media from Full
+before rendering final model history with the same rules, using structured context facts tied
+to the user-scope generation. Prepared control objects are not business display data.
+
+Core and cloud direct calls resolve presentation context before executing an Essential write.
+MCP workflow projection preserves already settled outcomes if its optional context lookup fails:
+it adds a presentation warning, uses UTC and retains source units, without replaying the operation.
+
 ## App result contract
 
 `control.responseDetail` selects information depth: `full` (default) returns

package/contract/client-space-focus-v1.md

@@ -15,7 +15,7 @@ Both request-response (`arq`) and one-way state synchronization (`ad`) use this
 same envelope. Native switch orchestration retains its existing ACK and session
 fences. Background synchronization remains per physical connection and is not
 an additional user switch. It never replays an obsolete clear after reconnect.
-For Cloud clear, the existing envelope `scopeId`, when non-empty, is a condition:
+For Cloud clear, the existing envelope `spaceId`, when non-empty, is a condition:
 a delayed clear for A cannot erase a newer focus on B. Omitted/blank scope clears
 unconditionally. Local connections can only focus/clear their bound Space.
 

package/contract/device-presentation-v1.md

@@ -0,0 +1,35 @@
+# Device UI presentation
+
+Device-specific UI adapters use `/app/presentation/device/*`. All three are
+read-only, use the standard App Facade envelope and follow Space-mode execution:
+cloud Spaces execute in the cloud; local Spaces execute on their selected Hub.
+They have no native Agent, external CLI Skill, MCP or CLI entrypoint. Shared
+`/app/device/state/get`, list, detail and bounded history remain domain APIs.
+
+- `/app/presentation/device/view/get`, `{deviceId}`: `{deviceId, primaryViewId, views, widgets, twin}`.
+  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. The optional `twin` metadata is
+  returned even when a known device has no render anchor.
+- `/app/presentation/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/presentation/device/online/list`, `{entityIds?: []}`:
+  `{devices:[{entityId,online,updatedAtSec}]}`. Normalizes and deduplicates selected
+  IDs, preserves request order and returns only IDs with stored online records.
+  An empty selection returns no rows. This preserves the existing UI projection:
+  `online` is true for the stored `online` observation and false for other stored
+  states; an absent record is omitted. It never probes a device or reads capability
+  observations. The shared state API instead omits unknown `online` fields.
+
+Device details and Device Group State tabs read static bindings first, then use
+shared selected `/app/device/state/get` and `/app/widget/value/get` observations. Canvas
+content reuses static Card assembly; it does not call the single-device view API.
+History renderers request chart series only when needed. The Devices directory
+reads selected online rows after loading its catalog. These reads never refresh
+providers, change Twin lifecycle or initialize new business resources.
+
+The backend adapters own visibility, unique render-anchor validation and existing
+series filtering. Managers, persistence tables, group aggregation, generated
+Automations and push protocols are unchanged. Only the namespaced UI routes are registered.

package/contract/entity-v1.md

@@ -0,0 +1,53 @@
+# General Entity reads
+
+All reads use authenticated tenant and Space. Device, Automation and Widget types
+belong to their dedicated domains. Location and concrete AppClient endpoints are
+built-in Entity types; other types are Integration-defined.
+
+- `/app/entity/list`: `{entityType, includeGroups?, integrationId?, connectId?}` returns `{entities: [EntityMetadata]}` for the
+  exact type, including same-type Groups by default. `includeGroups:false` reads only
+  ordinary entities. A Provider filter selects ordinary source resources only;
+  `connectId` requires `integrationId`. There is one list, with no mode or refresh.
+- `/app/entity/detail/get`: `{entityType, ids}` returns ordered deduplicated
+  `{items: [{requestedId, found, reason?, entity?}]}`. `entity` is exactly the same
+  metadata model as a list row; callers with known IDs need not list first.
+- `/app/entity/state/get`: `{entityType, ids}` (1–100 nonblank IDs before
+  deduplication) returns ordered `{items: [{requestedId, found, reason?, resource?}]}`.
+  `resource` is `{entityId, latest: [{capabilityId, state?, event?, log?}]}`.
+  These are latest persisted observations, without refreshing a Provider or deriving
+  online status. Groups read their own observations without expanding members.
+  Existing Location/AppClient endpoints return `latest: []`; missing resources use
+  `found: false, reason: "not_found"` and omit resource. No observations is not missing.
+- `/app/entity/history/list` remains independent and returns at most 100 records.
+
+Metadata contains id, name, entityType, integration?, connectId?, active, capabilities, data,
+tags (Blueprint IDs), availabilityStatus?, issue, group and entityIds (Group members).
+It contains no current capability values. Full retains the complete metadata.
+Essential omits Blueprint tags, ordinary entityIds, absent optional values and
+redundant built-in data identity fields. It preserves arbitrary Integration data,
+including Provider-local data.id, falsy values and Group entityIds. State payloads
+are not trimmed; only declared observation timestamps are localized by the shared
+presentation-time rules. No arbitrary business-data timestamp inference is used.
+
+List, detail and state respect installed Provider and persisted source visibility.
+Ordinary reads accept Provider-owned Twins only. Groups are read from independent
+definitions; their derived Twins cannot masquerade as ordinary entities.
+Provider-defined types resolve installation through their parent Integration.
+Built-ins are scoped to the current Space and reject Provider filters.
+
+## Device sources
+
+`/app/device/list` accepts `{includeGroups?, integrationId?, connectId?}` with the
+same source filter semantics. Its rows contain standard Device metadata, never
+card relationships or current observations. UI Resources and House compose domain
+reads; they do not require a multi-type backend catalog.
+
+`/app/device/source/resolve` is a read-only onboarding helper. Input is
+`{integrationId, connectId?, sourceIds}` (1–100 nonblank opaque IDs before
+ordered deduplication). A connected Provider requires one exact Connection; a
+direct Provider omits it. Each result is `{requestedSourceId, found, entityId?,
+reason?}`. Missing IDs return `not_found`; multiple canonical IDs for one source
+identity fail the request. Only installed, visible Provider-owned Devices match.
+The operation never synchronizes sources or returns metadata, state or cards.
+Source synchronization remains `/app/integration/entity/refresh`; onboarding reads
+standard Device metadata only after an explicitly successful synchronization.

package/contract/pod-commissioning-v1.md

@@ -135,7 +135,7 @@ the response also carries `"mode":"reprovision"` and `wifiConfigured` is false
 
 `pod-credential` requests:
 
-- `{"op":"deliver","clientMode":"user","podId","loginGrant","scopeId","cloudApi","cloudWs"}` →
+- `{"op":"deliver","clientMode":"user","podId","loginGrant","spaceId","cloudApi","cloudWs"}` →
   `{"ok":true,"state":"activating"}`. Accepted only in `wifi_connected` outside a
   Wi-Fi change window; otherwise `{"ok":false,"state":<current pod state>,"reason"}`
   with `reason` `invalid_payload` (a missing or malformed field, including a
@@ -241,7 +241,7 @@ Lion returns `{podId, loginGrant, activateBefore}`. The random approval expires
 in ten minutes and is bound to this User and the Pod identity key. It is not a
 login refresh token. The helper must never deliver its own login credentials.
 
-The App delivers the approval through the paired LAN channel. `scopeId` in the
+The App delivers the approval through the paired LAN channel. `spaceId` in the
 device delivery selects the initial UI Space; it does not constrain the User
 identity or grant Space authority. The device independently redeems the approval
 at `POST /api/v1/pod/login/redeem` with `{podId, loginGrant, proof}`. The proof is
@@ -304,7 +304,7 @@ never show these values or `message` verbatim.
 | `invalid_wifi` | SSID not 1–32 bytes, or password not empty or 8–63 characters (64 hex digits) |
 | `bluetooth_unavailable` | no usable Bluetooth adapter |
 | `not_signed_in` | no signed-in MeowLink account |
-| `scope_not_offered` | the Space is not among those offered, or the account has no Space |
+| `space_not_offered` | the Space is not among those offered, or the account has no Space |
 | `cloud_unreachable_for_device` | the cloud address is loopback |
 | `busy` | the native Client cannot take the request now; retry |
 
@@ -318,7 +318,7 @@ never show these values or `message` verbatim.
 | `/local/pod/commission/code` | `{"sessionId","code"}` | session snapshot |
 | `/local/pod/commission/wifi` | `{"sessionId","ssid","password"?}` | session snapshot |
 | `/local/pod/commission/wifi/scan` | `{"sessionId"}` | session snapshot |
-| `/local/pod/commission/authorize` | `{"sessionId","scopeId"}` | session snapshot |
+| `/local/pod/commission/authorize` | `{"sessionId","spaceId"}` | session snapshot |
 | `/local/pod/commission/status` | `{}` | `{"session": snapshot or null}` |
 | `/local/pod/bluetooth/settings` | `{}` | `{"opened"}` |
 
@@ -346,7 +346,7 @@ page does not end setup; returning to it reads `status`. Waiting for user input
 also counts toward the deadline. Discovery leases still control scanning.
 
 Sign-in and Spaces are checked at `start` (`not_signed_in`,
-`scope_not_offered`) and again when the authorization prompt is built.
+`space_not_offered`) and again when the authorization prompt is built.
 
 A pod inside a Wi-Fi change window (`pod-info` `"mode":"reprovision"`) gets a
 Wi-Fi-only session. From `reading_info` on, its snapshots carry
@@ -409,7 +409,7 @@ The schemas are `schema/pod-discovery.v1.schema.json` and
 ## 8. Space Client local credential
 
 `POST /api/v1/pod/space/credential/issue` uses the assisting App's user
-`Authorization` and `ScopeId`, with the same device identity request as personal
+`Authorization` and `SpaceId`, with the same device identity request as personal
 issuance. Only the current Space owner may assist. The Space must be local and have one
 published Hub with business and Host TLS identities. Cloud Spaces must complete
 Hub setup first. The issuer derives `appClientId` from tenant, Space and the validated
@@ -417,12 +417,12 @@ persistent device-key fingerprint. The same device in the same Space retains thi
 ID across retries; a factory reset rotates its key. Candidate local JWTs use the
 existing Space signing key and local-client audience.
 
-Claims are `token_type: local_space_client_access`, `sub: <scopeId>`,
-`tenant_id`, `scope_id`, `hub_id`, `app_client_id`, `jti`, `iat`, `exp`, `is_test`.
+Claims are `token_type: local_space_client_access`, `sub: <spaceId>`,
+`tenant_id`, `space_id`, `hub_id`, `app_client_id`, `jti`, `iat`, `exp`, `is_test`.
 The expiry follows existing long-lived User local credentials. No `userId`,
-initializer identity, `podId` or `issuedScopeId` grants authority. User local
+initializer identity, `podId` or `issuedSpaceId` grants authority. User local
 credentials retain `local_client_access` and must not contain `app_client_id`.
-Personal Pod issuance no longer stores `issuedScopeId`.
+Personal Pod issuance no longer stores `issuedSpaceId`.
 
 Lion sends `{jwtToken, clientSource:"pod"}` to the authenticated Hub Bridge
 `/hub/client/space/register`. Core verifies signature, audience, issuer, current
@@ -437,12 +437,12 @@ The Bridge returns `{credentialId, appClientId, jwtToken, status, activateBefore
 Lion returns `{credentialId, appClientId, jwtToken, credentialState, activateBefore,
 hubIdentity}`. State is `pending` with its epoch-millisecond first-use deadline, or
 `active` with `activateBefore:null`. Issuance alone does not publish a device-list entry. The Hub identity includes its business P-256 key and
-Host TLS public key, bound to `tenantId`, `scopeId`, `hubId` and `hostId`.
+Host TLS public key, bound to `tenantId`, `spaceId`, `hubId` and `hostId`.
 
 The secured LAN `pod-credential` delivery is:
 
 ```json
-{"op":"deliver","clientMode":"space","credentialId":"…","appClientId":"a:…","jwtToken":"…","tenantId":"…","scopeId":"…","hubIdentity":{}}
+{"op":"deliver","clientMode":"space","credentialId":"…","appClientId":"a:…","jwtToken":"…","tenantId":"…","spaceId":"…","hubIdentity":{}}
 ```
 
 The actual `hubIdentity` is the complete issuer response. User credential fields

package/contract/reference-presentation-v1.md

@@ -1,7 +1,7 @@
 # Reference picker presentation
 
 UI-only Space reads use the standard FacadeCall and success/data/error envelope.
-Both targets require spaceRead and follow scopeMode routing. They are not native
+Both targets require spaceRead and follow spaceMode routing. They are not native
 Agent, CLI or MCP tools. Full and Essential preserve the same business fields;
 Essential represents them as YAML.
 

package/contract/resource-read-v1.md

@@ -11,6 +11,9 @@ follow the Space execution authority on both local Core and cloud.
 | --- | --- | --- |
 | `/app/device/detail/get` | `{ids}` | Existing ordered `items` with `device` definitions, capabilities, group membership, physical Twin enablement or Group application state, source metadata; no online or state fields |
 | `/app/device/state/get` | `{ids}` | Ordered `items` with `resource: {entityId, online?, onlineUpdatedAtSec?, latest}` |
+| `/app/entity/list` | `{entityType}` | Complete static directory metadata of the exact general Entity type; same-type Groups included; no list modes |
+| `/app/entity/detail/get` | `{entityType, ids}` | Selected metadata identical to list rows, under ordered `items[].entity` |
+| `/app/entity/state/get` | `{entityType, ids}` | Ordered `items` with `resource: {entityId, latest}`; no source refresh or derived online; see [Entity contract](entity-v1.md) |
 | `/app/widget/list` | `{}` | Summaries: id, displayName, description, type, tag; Data adds dataType/repeated. No list mode or full-definition catalog |
 | `/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?}` |
@@ -30,7 +33,9 @@ Observation batches accept 1–100 IDs, reject blanks, trim and deduplicate pres
 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
+Device state supports visible physical devices and Device groups. General Entity state
+also requires entityType, supports same-type Groups and respects source visibility;
+known Location/AppClient endpoints return empty latest without querying Twin. 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.
@@ -56,15 +61,10 @@ observation and graph reads preserve their bounded business fields in Essential.
 
 ## UI-only reads
 
-- `/app/device/view/get`, `{deviceId}`: `{deviceId, primaryViewId, views, widgets, twin}`.
-  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. The optional `twin` metadata is
-  returned even when a known device has no render anchor.
-- `/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.
+Device-specific rendering, chart series and selected online reads use the
+[`/app/presentation/device/*` contract](device-presentation-v1.md). They are UI
+adapters, separate from the shared definition/state/history contracts.
+
 - `/app/dashboard/canvas/content/get`, `{canvasId}`: Canvas metadata plus Cards' static
   titles, view bindings, layouts, settings, metadata and selected Widget definitions.
   Each entity Card includes the same `twin` metadata, loaded once per entity in the
@@ -88,7 +88,7 @@ identity/connection/capabilities. Schema publication does not expire them. Expli
 device refresh rereads attributes and reconciles related Groups. These are write-side
 operations; definition reads remain cache-only.
 
-`/twin/entityUpdate` pushes `{scopeId, entityIds}` after cached metadata changes.
+`/twin/entityUpdate` pushes `{spaceId, entityIds}` after cached metadata changes.
 Open views refresh their definition batches; other Spaces and unrelated entities
 are ignored. A new definition owns its capability membership: old observations
 for removed capabilities must not be merged back into the current view. History

package/contract/trace-v1.md

@@ -0,0 +1,17 @@
+# Linear execution attribution
+
+Trace is an ordered array of flat items, each with an uppercase type and Unix-millisecond timestamp. Source kinds reuse Facade source kinds. The array records user-visible attribution boundaries; Automation instructions, conditions, branches and payloads are not trace items.
+
+Ignite explicitly starts an Automation, trigger starts an ordinary run, and resume continues an existing run. Resume preserves the saved run chain. Internal asynchronous instruction completions do not append resume items. Trace uses run-level attribution, without per-branch causal graphs.
+
+Command history stores an optional `r` reference. Snapshots are immutable and scoped by tenant and Space; IDs are positive signed 64-bit integers, represented as decimal strings in JSON. The trace and referencing command use the existing command storage owner. Recording is best effort: missing attribution cannot fail an operation or suppress its command history.
+
+Each cross-runtime invocation keeps its own frozen attribution prefix in the caller's in-memory context. The provider returns only the local suffix for each command it recorded; the caller composes each suffix with that invocation's prefix independently. Responses may complete in any order. Different calls do not share a mutable trace, and no shared placeholder list, durable pending record or cross-runtime command ID is required. Closing a request discards later recording work under the existing best-effort bounds.
+
+Trace collection does not change Twin observation semantics. Reports and observed state values update Twin when received; unchanged state retains its transition time and existing deduplication, while events represent separate occurrences. Received command records update the latest command log and append history under the existing rules. A late response is not rejected merely because another command started later. A command log is distinct from reported device state and does not establish that a physical state change occurred.
+
+`/app/trace/get` accepts `input.traceIds`, at most 100 decimal IDs in the current Space. The result contains `traces` (ID to array) and `missingTraceIds`. Normal history reads do not implicitly resolve references. Entity and device history timelines return the command’s optional `r` unchanged as a decimal string; state and event entries omit it. Their `traceSteps` contains only legacy stored string sources, never a downgraded projection of a structured snapshot. Callers that need attribution batch the selected references through `/app/trace/get`; missing or expired snapshots leave the command visible. Full returns the original structured model with Unix-millisecond timestamps; Essential preserves its attribution fields and renders item times in the Space Home timezone. Authorization is Space read and routing follows Space mode. Legacy stored string sources remain readable without inventing per-item times.
+
+Snapshots have a seven-day best-effort retention window. Local cleanup is opportunistic on writes; cloud providers use native TTL. Reuse is a small in-memory optimization, without a global deduplication guarantee.
+
+Attribution is bounded to 256 items and 32 KiB encoded JSON. Oversized attribution is omitted. Consecutive resumes of the same Automation keep the latest resume timestamp in the new snapshot, preserving the original chain and previously persisted snapshots.

package/contract/user-navigation-v1.md

@@ -0,0 +1,47 @@
+# Personal home navigation
+
+The signed-in User owns two independent profiles, `compact` and `wide`, shared
+across Web, desktop and phone Clients and independent of the focused Space.
+`/app/user/navigation/catalog` takes an empty object and returns the canonical
+`manifest/navigation-cards.v1.json` catalog. `get` takes `{layout}`. `update`
+takes `{layout, cardIds, menuCardIds?}`. Both return
+`{layout, cardIds, menuCardIds, revision}`. The authenticated caller selects
+the owner; requests cannot select a User, Client, Space, URL or arbitrary page.
+
+`cardIds` is the ordered Nav list. Dashboard, Now and Menu each occur exactly
+once; Menu is always projected and stored last. Requests and stored profiles
+from older Clients with Menu elsewhere are normalized, preserving all other
+relative order. Additional entries are Menu card IDs from the catalog.
+Membership makes the card's root route a home page; child editors and object
+details retain their ordinary navigation lifecycle.
+
+`menuCardIds` is the ordered list of remaining Menu cards. A complete edit supplies
+both lists and replaces them in one document write. They must be disjoint and
+together contain every catalog ID exactly once. Required Nav entries cannot move
+to Menu. Unavailable cards remain in their saved lists/order when a Client filters
+its UI, so a different Space/platform does not delete personal preferences.
+New catalog cards absent from an older request or stored profile are appended in
+default order. Unknown IDs, duplicates and overlap are rejected.
+
+For backward compatibility, omitting `menuCardIds` changes only Nav membership
+and order: retained Menu entries keep their saved relative order, newly unpinned
+entries are appended, and newly pinned entries leave Menu. Older readers may
+ignore the additive response field. The default Nav list is
+`[dashboard, now, menu]`; the default Menu order is Devices, Automations, Widgets,
+Integrations, Messaging Apps, NFC, Matter, Camera, Floor Plan, People, Storage,
+Phone Setting. No startup data rewrite or separate Menu document is needed.
+
+UI edits are drafts until the user clicks Done. Normal browsing does not reorder
+or show per-card editing menus. Editing blocks page navigation, supports transfers
+between Menu and Nav and sorting within both, and leaves Menu fixed last with a
+thin separator. Dropping outside both lists changes nothing; touch scrolling
+stays native until a held drag activates. Cancel discards the draft; a failed
+save retains it for retry. Screen profiles remain independent.
+
+Writes are last-write-wins per profile, without a caller revision precondition.
+An opaque revision identifies a saved snapshot, not a Client clock. Each write
+replaces one profile only. `/user/navigation/changed` invalidates that authenticated
+user's profile across their connected Clients. Consumers re-read authoritative
+state and also resync on reconnection/focus; notifications are not a second durable
+store. Saving a profile does not require an App Client online and never performs
+a page's business action.