@mhome/app-facade-protocol 1.45.0 → 1.46.1

package/README.md

@@ -7,8 +7,9 @@ The package also carries the explicitly private `/local/*` native-daemon
 extension. `/app/*` is portable and may be routed according to the public
 routing manifest. `/local/*` is an exact allowlist for the current MeowLink
 native client process and must never be forwarded to cloud, Hub, or Host
-connections. Hub `/app/*` calls are direct-only `FacadeCall`s; Hub `/local/*`
-calls carry the domain input directly and never use the public envelope.
+connections. Hub `/app/*` calls use `FacadeCall`, whether delivered directly
+or forwarded by authenticated Cloud ingress. The separate Hub `/local/*`
+protocol carries domain input and never uses the public envelope.
 
 Every `/app/*` request uses the strict `FacadeCall` envelope. Invocation
 metadata lives in `control`; the domain request lives in `input`. The crate
@@ -57,13 +58,17 @@ claim of that Host requires. See [the contract](contract/host-provisioning-v1.md
 
 ## Routing contract
 
-`manifest/routing.v1.json` is the canonical client-side routing policy for the
+`manifest/routing.v1.json` is the shared business execution policy for the
 new `/app/*` facade. Ordinary operations follow the active Space mode. Only
 exceptional domains declare a fixed Cloud, Hub, or request-placement executor.
-Relay permission is separate from execution authority so a client
-cannot silently turn every Hub request into a cloud-proxied request.
-
-The checked-in Rust table is generated from that manifest, and non-Rust clients
+Cloud-capable User Clients may enter through Cloud for registered public control
+operations. Lion resolves the same execution rules before converting domain input,
+and forwards complete Core-owned calls through the authenticated Bridge. Runtime
+connection state, ingress restrictions, authorization, and surface exposure remain
+separate concerns. A transport change never changes business ownership or replays
+a request whose outcome is unknown.
+
+The checked-in Rust table is generated from that manifest, and Lion and non-Rust clients
 consume the same manifest from the npm protocol package. Local Spaces execute
 Host inventory and management on the selected Hub through `/app/system/hosts/*`.
 A native Client remains the path when no local Hub is selected. Lion's legacy

package/contract/card-skins-v1.md

@@ -0,0 +1,138 @@
+# Card skins v1
+
+These direct App Facade operations manage MeowLink Dashboard skins. They do not
+change device state or expose the application SDK to a skin. `control` remains
+the standard Facade envelope; `input` must match the named definition in
+`schema/card-skins.v1.schema.json`. Responses are JSON. Tenant, Space and caller
+identity come exclusively from authenticated ingress, never from domain input.
+
+## Catalog and publication
+
+`/app/card-skins/catalog/*` always executes in Cloud. Catalog reads require a
+User principal. Package creation reserves `packageId` in that tenant. Only the
+stored author may edit its display metadata or publish versions. Authorship is
+immutable. Package lookup is by known package ID; this is not a public marketplace
+or a searchable cross-tenant catalog.
+
+| Target suffix | Input definition | Output |
+| --- | --- | --- |
+| `catalog/package/get` | `packageGet` | `{revision, value: {packageId, authorUserId, name, description, createdAt}}` |
+| `catalog/package/create` | `packageCreate` | `{}` |
+| `catalog/package/update` | `packageUpdate` | `{}` |
+| `catalog/release/get` | `releaseGet` | `{id, baseUrl, manifest}` |
+| `catalog/release/list` | `packageGet` | `{releases: [...]}`; ordering is unspecified |
+| `catalog/publish/prepare` | `publishPrepare` | `{uploadId, expiresAt, files: [{path, url, headers}]}` |
+| `catalog/publish/complete` | `publishComplete` | The immutable release |
+
+Times are Unix milliseconds. Prepare validates the complete manifest against
+`schema/card-skin-package.v1.schema.json`, its config schemas, paths, file types,
+unique renderer IDs/patterns and inventory. A package has one nonempty bundled
+`.mjs` entry, at most 128 files and 128 renderers, at most 8 MiB per file and 32 MiB
+in total. Metadata documents are limited to 256 KiB UTF-8 JSON. The manifest lists
+only supported asset extensions with their exact media type, size and SHA-256.
+`manifest.json` is reserved. Config schemas are synchronous, self-contained JSON
+Schema draft-07, with only fragment `$ref`s, no `$async`, and at most 64 levels.
+Each config root must have `type: object`.
+
+Each prepared session binds one manifest, author and immutable delivery directory.
+It expires after 15 minutes. Upload each file with HTTP PUT to its returned URL
+and the exact returned headers. Upload grants are bearer secrets; only their
+SHA-256 digests are persisted. The server verifies the actual body before writing
+it to a private bucket. S3 conditional create / OSS forbid-overwrite makes each
+verified object immutable; clients never receive an object-store write URL.
+A repeated identical PUT is safe. Different bytes, sizes or media types fail.
+
+Complete checks authorship, session expiry and all server-verified immutable
+object receipts before a create-only release write. Missing files never create a
+release. Two sessions racing for the same version have one winner. Retrying the
+winning completion returns that exact release, including after session expiry;
+a different session cannot replace it. Unknown storage outcomes are errors, not
+automatically replayed business operations. Reload the version to resolve them.
+A newer version requires another prepare/upload/complete cycle.
+
+Published `baseUrl` is a stable HTTPS directory. GET of a declared file checks the
+published release and its random delivery-directory ID, verifies content integrity,
+and serves the correct media type with CORS, `nosniff`, and immutable caching.
+There is no expiring signed URL in a release. Unpublished files cannot be fetched
+through delivery. A delivery URL is shareable: knowledge of it permits reading
+that release's executable bytes, without granting catalog or upload permissions.
+Do not put secrets in skins. Config values stay in the Space selection.
+
+The publication service validates metadata and bytes, not JavaScript behavior.
+The authoring build verifies the bundled ESM structure; the browser host verifies
+renderer exports against the manifest before using them. Skins run in the host's
+JavaScript realm and are not sandboxed by the UI interface. Publication is not a
+claim of a malicious-code audit or cryptographic browser SRI enforcement.
+
+## Space selection
+
+These operations execute on the authoritative owner of the Space: Cloud for
+cloud Spaces, Core for local Spaces. Read requires Space read access; mutations
+require Space write access. Agent/MCP surface exposure is separate and is not
+introduced by this contract.
+
+| Target suffix | Input definition | Output |
+| --- | --- | --- |
+| `selection/get` | `empty` | `{revision: string|null, selection: {installations, overrides, releases}}` |
+| `install` | `install` | `{}` |
+| `uninstall` | `uninstall` | `{}` |
+| `upgrade` | `upgrade` | `{}` |
+| `override/set` | `overrideSet` | `{}` |
+| `override/reset` | `overrideReset` | `{}` |
+
+Every mutation **requires** `expectedRevision`: null means the document has never
+been created; otherwise it must equal the latest read token. A stale token returns
+`PRECONDITION_FAIL` without retry or overwrite. An empty selection can have a
+non-null revision. Mutation responses acknowledge the write; read the selection
+again for its latest state/revision, which may include another writer's edit.
+
+Install takes a known package ID and exact version; the service resolves the
+published release from the tenant catalog. Core uses its authenticated cloud
+bridge for that read. Neither accepts client-provided release IDs, manifests or
+URLs. Installation does not automatically enable pattern overrides. Each package
+has one installation per Space; installing another version uses `upgrade`.
+
+Set override selects an installed renderer declaring that pattern and validates
+the supplied config against its schema. Reset removes just that pattern's
+override. Uninstall removes the installation, its pinned descriptor and every
+override referencing it in one commit. Reset/uninstall/config edits use local
+pinned metadata; they do not need a live catalog connection.
+
+Upgrade keeps the installation ID and all existing overrides. Every affected
+renderer must still exist, declare exactly the same pattern/contract ID/version,
+and accept the existing config. A different catalog identity is never silently
+substituted after Space transfer. Any incompatibility rejects the entire write;
+there is no partial upgrade or implicit config conversion. The user can explicitly
+reset incompatible overrides before switching versions. Successful upgrades
+atomically replace the pinned release while preserving valid overrides.
+
+The cloud/SQLite storage contract and `ui/cardSkins` backup category retain
+complete pinned descriptors. They do not cache executable bytes for offline use.
+An installed host still performs its own current-pattern compatibility check;
+publication does not assume every MeowLink client supports the same contracts.
+
+## Deployment and boundaries
+
+The cloud service needs a private `card-skins.storage.bucket` on its configured
+AWS/OSS provider and an HTTPS `card-skins.delivery.base-url` reaching the binary
+controller. Object-store credentials must not grant end users overwrite/delete
+access to skin objects. Existing release directories and URLs must be preserved
+across deployment. A trusted reverse proxy/CDN may cache successful delivery;
+upload and error responses are `no-store`.
+
+Unfinished publishing sessions expire but their draft records and unreferenced
+objects are currently retained. This version provides no automatic garbage
+collector, package deletion or release deletion. Cleanup must never remove a
+published directory. The App dashboard and Space management page consume these
+endpoints through the existing SDK transport port. The page supports installation,
+pattern selection, configuration, explicit version changes and uninstall. Visible
+clients refresh selection on reconnect, foregrounding and every 30 seconds;
+realtime notifications remain future work. The standalone versioned Card DevKit
+provides project creation, metadata, typed builds, verification, real App preview
+and publication. The MeowLink CLI and Agent/MCP tools expose catalog queries and
+Space installation/override management; the external coding Agent Skill guides
+authoring with the DevKit. Built-in Agent project editing and compilation require
+a future local execution node. These source capabilities require their matching
+published artifacts and deployed services. See the frontend's
+[card guide](../../../../pallas-cat/docs/cards/README.md) for the authoring tools
+and management flow.

package/fixtures/actor-link-code-create.request.json

@@ -1,8 +1,5 @@
 {
-  "target": "/app/messaging/actor/link-code/create",
+  "target": "/app/messaging/link/code/create",
   "direction": "request",
-  "body": {
-    "provider": "telegram",
-    "placement": "local"
-  }
+  "body": {}
 }

package/fixtures/actor-link-code-create.response.json

@@ -1,5 +1,5 @@
 {
-  "target": "/app/messaging/actor/link-code/create",
+  "target": "/app/messaging/link/code/create",
   "direction": "response",
   "body": {
     "challenge": {

package/fixtures/actor-link-delete.request.json

@@ -1 +1,7 @@
-{"target":"/app/messaging/actor/link/delete","direction":"request","body":{"provider":"telegram","placement":"local","linkId":"link_a"}}
+{
+  "target": "/app/messaging/unlink",
+  "direction": "request",
+  "body": {
+    "linkId": "link_a"
+  }
+}

package/fixtures/actor-link-delete.response.json

@@ -1 +1,7 @@
-{"target":"/app/messaging/actor/link/delete","direction":"response","body":{"success":true}}
+{
+  "target": "/app/messaging/unlink",
+  "direction": "response",
+  "body": {
+    "success": true
+  }
+}

package/fixtures/actor-link-list.request.json

@@ -1 +1,5 @@
-{"target":"/app/messaging/actor/link/list","direction":"request","body":{"provider":"telegram","placement":"local","accountId":"bot_a"}}
+{
+  "target": "/app/messaging/link/list",
+  "direction": "request",
+  "body": {}
+}

package/fixtures/actor-link-list.response.json

@@ -1 +1,18 @@
-{"target":"/app/messaging/actor/link/list","direction":"response","body":{"links":[{"linkId":"link_a","provider":"telegram","placement":"local","accountId":"bot_a","externalUserId":"user_42","displayName":"Alice","createdAtMs":1720000000000,"updatedAtMs":1720000000000}]}}
+{
+  "target": "/app/messaging/link/list",
+  "direction": "response",
+  "body": {
+    "links": [
+      {
+        "linkId": "link_a",
+        "provider": "telegram",
+        "placement": "local",
+        "accountId": "bot_a",
+        "externalUserId": "user_42",
+        "displayName": "Alice",
+        "createdAtMs": 1720000000000,
+        "updatedAtMs": 1720000000000
+      }
+    ]
+  }
+}

package/fixtures/authorization/decisions.json

@@ -614,5 +614,41 @@
     "scopeId": "space",
     "target": "/app/artifact/internal/read",
     "allowed": false
+  },
+  {
+    "name": "credit-usage:owner",
+    "principal": {
+      "kind": "user",
+      "userId": "owner"
+    },
+    "memberRole": "OWNER",
+    "tenantId": "tenant",
+    "scopeId": "space",
+    "target": "/app/agent/credit/usage",
+    "allowed": true
+  },
+  {
+    "name": "credit-usage:member",
+    "principal": {
+      "kind": "user",
+      "userId": "member"
+    },
+    "memberRole": "MEMBER",
+    "tenantId": "tenant",
+    "scopeId": "space",
+    "target": "/app/agent/credit/usage",
+    "allowed": true
+  },
+  {
+    "name": "credit-usage:nonmember",
+    "principal": {
+      "kind": "user",
+      "userId": "nonmember"
+    },
+    "memberRole": null,
+    "tenantId": "tenant",
+    "scopeId": "space",
+    "target": "/app/agent/credit/usage",
+    "allowed": false
   }
 ]

package/fixtures/bind-code-create.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/bind/code/create",
+  "direction": "request",
+  "body": {}
+}

package/fixtures/{surface-bind-code-create.response.json → bind-code-create.response.json}

@@ -1,5 +1,5 @@
 {
-  "target": "/app/messaging/surface/bind-code/create",
+  "target": "/app/messaging/bind/code/create",
   "direction": "response",
   "body": {
     "challenge": {

package/fixtures/binding-list.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/binding/list",
+  "direction": "request",
+  "body": {}
+}

package/fixtures/binding-list.response.json

@@ -0,0 +1,18 @@
+{
+  "target": "/app/messaging/binding/list",
+  "direction": "response",
+  "body": {
+    "bindings": [
+      {
+        "bindingId": "binding",
+        "provider": "telegram",
+        "placement": "local",
+        "accountId": "bot",
+        "conversationId": "group",
+        "scopeId": "home",
+        "displayName": "Family",
+        "createdAtMs": 1
+      }
+    ]
+  }
+}

package/fixtures/card-skins/space.json

@@ -0,0 +1,79 @@
+{
+  "tenantId": "mlink",
+  "scopeId": "space-a",
+  "selection": {
+    "installations": [
+      {
+        "id": "evening",
+        "spaceId": "space-a",
+        "releaseId": "mlink:example.evening@1.0.0"
+      }
+    ],
+    "overrides": [
+      {
+        "spaceId": "space-a",
+        "patternId": "basic.device.onoff_brightness_color",
+        "installationId": "evening",
+        "rendererId": "evening-light",
+        "config": {
+          "accent": "#c04040"
+        }
+      }
+    ],
+    "releases": [
+      {
+        "id": "mlink:example.evening@1.0.0",
+        "baseUrl": "https://skins.example.test/evening/1.0.0/",
+        "manifest": {
+          "schemaVersion": 1,
+          "packageId": "example.evening",
+          "version": "1.0.0",
+          "name": "Evening cards",
+          "description": "Full-card skins for a color light, a playable speaker and a thermostat.",
+          "apiVersion": 1,
+          "entry": "skin.test.mjs",
+          "renderers": [
+            {
+              "id": "evening-light",
+              "name": "Evening light",
+              "description": "Example light renderer.",
+              "supportedPatterns": [
+                {
+                  "patternId": "basic.device.onoff_brightness_color",
+                  "contractId": "light",
+                  "contractVersion": 1
+                },
+                {
+                  "patternId": "basic.device.onoff_brightness_colorrgb",
+                  "contractId": "light",
+                  "contractVersion": 1
+                }
+              ],
+              "detail": {
+                "mode": "custom"
+              },
+              "configSchema": {
+                "type": "object",
+                "properties": {
+                  "accent": {
+                    "type": "string",
+                    "pattern": "^#[0-9a-fA-F]{6}$"
+                  }
+                },
+                "additionalProperties": false
+              }
+            }
+          ],
+          "files": [
+            {
+              "path": "skin.test.mjs",
+              "mediaType": "text/javascript",
+              "sizeBytes": 1,
+              "sha256": "0000000000000000000000000000000000000000000000000000000000000000"
+            }
+          ]
+        }
+      }
+    ]
+  }
+}

package/fixtures/identity-code-failed.response.json

@@ -1,11 +1,10 @@
 {
-  "target": "/app/messaging/identity-code/status",
+  "target": "/app/messaging/code/status",
   "direction": "response",
   "body": {
     "status": {
       "challengeId": "challenge_01",
       "provider": "telegram",
-      "placement": "local",
       "accountId": "bot_a",
       "expiresAtMs": 1720000300000,
       "lifecycle": {

package/fixtures/identity-code-status.request.json

@@ -1 +1,7 @@
-{"target":"/app/messaging/identity-code/status","direction":"request","body":{"provider":"telegram","placement":"local","challengeId":"challenge_01"}}
+{
+  "target": "/app/messaging/code/status",
+  "direction": "request",
+  "body": {
+    "challengeId": "challenge_01"
+  }
+}

package/fixtures/identity-code-status.response.json

@@ -1,11 +1,10 @@
 {
-  "target": "/app/messaging/identity-code/status",
+  "target": "/app/messaging/code/status",
   "direction": "response",
   "body": {
     "status": {
       "challengeId": "challenge_01",
       "provider": "telegram",
-      "placement": "local",
       "accountId": "bot_a",
       "expiresAtMs": 1720000300000,
       "lifecycle": {

package/fixtures/interaction-flow.conformance.json

@@ -12,15 +12,21 @@
     "sessionId": "session-1",
     "commandId": "command-1",
     "expectedRevision": 1,
-    "input": { "$host": "192.0.2.1" },
-    "vars": ["$cameras"],
+    "input": {
+      "$host": "192.0.2.1"
+    },
+    "vars": [
+      "$cameras"
+    ],
     "force": false
   },
   "transitionRequest": {
     "sessionId": "session-1",
     "commandId": "command-2",
     "expectedRevision": 2,
-    "input": { "$camera": "camera-1" }
+    "input": {
+      "$camera": "camera-1"
+    }
   },
   "completeRequest": {
     "sessionId": "session-1",
@@ -62,7 +68,11 @@
   },
   "completeResponse": {
     "completed": true,
-    "result": { "providerConnectionId": "provider-1" }
+    "result": {
+      "providerConnectionId": "provider-1"
+    }
   },
-  "cancelResponse": { "cancelled": true }
+  "cancelResponse": {
+    "cancelled": true
+  }
 }

package/fixtures/provider-account-delete.response.json

@@ -1,5 +1,7 @@
 {
   "target": "/app/messaging/provider-account/delete",
   "direction": "response",
-  "body": { "success": true }
+  "body": {
+    "success": true
+  }
 }

package/fixtures/provider-account-list.request.json

@@ -1,5 +1,8 @@
 {
   "target": "/app/messaging/provider-account/list",
   "direction": "request",
-  "body": { "provider": "telegram", "placement": "local" }
+  "body": {
+    "provider": "telegram",
+    "placement": "local"
+  }
 }

package/fixtures/provider-account-status.request.json

@@ -1,5 +1,8 @@
 {
   "target": "/app/messaging/provider-account/status",
   "direction": "request",
-  "body": { "provider": "telegram", "placement": "local" }
+  "body": {
+    "provider": "telegram",
+    "placement": "local"
+  }
 }

package/fixtures/provider-account-status.response.json

@@ -4,9 +4,11 @@
   "body": {
     "status": {
       "provider": "telegram",
-      "placement": "local",
       "enabled": true,
-      "providerData": { "connected": 1 }
+      "providerData": {
+        "connected": 1
+      },
+      "placement": "local"
     }
   }
 }

package/fixtures/provider-account-test.request.json

@@ -1,5 +1,11 @@
 {
   "target": "/app/messaging/provider-account/test",
   "direction": "request",
-  "body": { "provider": "telegram", "placement": "local", "data": { "botToken": "secret" } }
+  "body": {
+    "provider": "telegram",
+    "placement": "local",
+    "data": {
+      "botToken": "secret"
+    }
+  }
 }

package/fixtures/provider-account-test.response.json

@@ -1,5 +1,9 @@
 {
   "target": "/app/messaging/provider-account/test",
   "direction": "response",
-  "body": { "result": { "reachable": true } }
+  "body": {
+    "result": {
+      "reachable": true
+    }
+  }
 }

package/fixtures/provider-account-update.request.json

@@ -5,6 +5,8 @@
     "provider": "telegram",
     "placement": "local",
     "accountId": "123456",
-    "data": { "enabled": true }
+    "data": {
+      "enabled": true
+    }
   }
 }

package/fixtures/provider-list.request.json

@@ -7,7 +7,10 @@
       {
         "provider": "telegram",
         "deprecated": false,
-        "supportedPlacements": ["cloud", "local"]
+        "supportedPlacements": [
+          "cloud",
+          "local"
+        ]
       }
     ]
   }

package/fixtures/provider-list.response.json

@@ -10,13 +10,28 @@
         "deprecated": false,
         "available": true,
         "setupFlow": "pairing_code",
-        "audiences": ["personal", "shared"],
-        "inboundCapabilities": ["text", "audio", "action"],
-        "outboundCapabilities": ["text", "markdown", "action"],
+        "audiences": [
+          "personal",
+          "shared"
+        ],
+        "inboundCapabilities": [
+          "text",
+          "audio",
+          "action"
+        ],
+        "outboundCapabilities": [
+          "text",
+          "markdown",
+          "action"
+        ],
         "deliveryMode": "unrestricted",
         "projections": {
-          "notification": { "supported": true },
-          "dialog": { "supported": true }
+          "notification": {
+            "supported": true
+          },
+          "dialog": {
+            "supported": true
+          }
         },
         "managementOperations": [
           "provider_account.list",

package/fixtures/route-delete.request.json

@@ -1,5 +1,9 @@
 {
   "target": "/app/messaging/route/delete",
   "direction": "request",
-  "body": { "provider": "telegram", "placement": "cloud", "routeId": "route-1" }
+  "body": {
+    "provider": "telegram",
+    "placement": "cloud",
+    "routeId": "route-2"
+  }
 }

package/fixtures/route-delete.response.json

@@ -1,5 +1,7 @@
 {
   "target": "/app/messaging/route/delete",
   "direction": "response",
-  "body": { "success": true }
+  "body": {
+    "success": true
+  }
 }

package/fixtures/route-list.request.json

@@ -1,5 +1,9 @@
 {
   "target": "/app/messaging/route/list",
   "direction": "request",
-  "body": { "provider": "telegram", "placement": "cloud", "audience": "personal" }
+  "body": {
+    "provider": "telegram",
+    "placement": "cloud",
+    "audience": "personal"
+  }
 }