@mhome/app-facade-protocol 1.127.1 → 1.129.1

package/README.md

@@ -39,15 +39,18 @@ conversion belongs at the Facade implementation boundary.
 
 Agent Profile get/save use `content` for the complete document. LLM mode get/save
 use `llmMode`; summary and default-provider metadata use that same field.
-`control.mode` selects response detail. Each LLM use case has one current model. The existing
+`control.responseDetail` selects response detail. Each LLM use case has one current model. The existing
 `/app/agent/llm/summary` operation owns the combined LLM read used by UI and CLI.
 See the Agent cases in the shared [presentation fixtures](fixtures/presentation/cases.json).
 
-Client workflows may coordinate input, login, polling and local files. Native
-Profile updates may run model-based merging. These workflows own explicit final
-results and compose real Facade calls; they are not alternative DTOs for a single
-Facade operation. A UI view model may derive display state after the SDK boundary.
-Composition does not imply a distributed transaction or automatic rollback.
+Business aggregation, multi-write orchestration and overall outcome settlement belong
+behind a Facade. Clients may make independent reads needed by the caller and adapt
+arguments, local files and terminal/UI input. They may drive defined prepare/commit,
+interactive-session and asynchronous-operation protocols; the backend owns business
+steps, transitions and final DTOs. Do not implement product business composites or
+alternative DTOs in CLI, SDK or surface adapters. A UI view model may derive display
+state after the SDK boundary. Backend composition does not imply a distributed
+transaction or automatic rollback.
 
 ## Full values and Essential presentation
 

package/contract/card-skins-v1.md

@@ -65,8 +65,13 @@ Package caching does not install, select, upgrade, or grant additional device au
 All platforms retain the renderer isolation requirement, including for cached files.
 
 The publication service validates metadata and bytes, not JavaScript behavior.
-The renderer contract remains `apiVersion: 1` during development and changes in
-place. Hosts and skins use that current contract without a compatibility layer.
+The renderer contract is `apiVersion: 2`. Renderers supply content in a
+framework-owned surface, both standalone and embedded. The host owns background,
+radius, clipping, menus, editing and composition dividers. A content root stays
+transparent and uses the inherited foreground; the renderer may arrange its title,
+values and controls without a reserved header. Each member receives its own grid
+and measured content viewport. Whole-card API 1 packages are rejected and must be
+adapted and rebuilt; there is no legacy rendering mode.
 The authoring build verifies the bundled ESM structure; the browser host verifies
 renderer exports against the manifest before using them. Each base owns its
 presentation adapter and renderer host; common card state and actions do not

package/contract/dashboard-composition-v1.md

@@ -0,0 +1,59 @@
+# Canvas layout and card composition
+
+Canvas owns one versioned layout document for every Dashboard placement. Card
+bodies own content, views, business references and size-only `defaultSizes`.
+`cardIds`, absolute leaf positions and parent membership are read projections,
+never independent stored placement authorities. Physical Device parentage does
+not change this presentation model; arbitrary logical Cards can be composed.
+
+The layout schema is `schema/canvas-layout.v1.schema.json`. Root coordinates are
+Canvas-global; member coordinates are relative to their composition. Each item
+has independent sm/md/lg layouts, limited to 2/4/6 columns respectively. Members
+are leaf Card references, never nested compositions. IDs are unique and leaves
+cannot be placed twice. Siblings cannot overlap; children must fit within their
+outer rectangle. Coordinates use nonnegative signed-32-bit integers. The UTF-8
+layout document is at most 256 KiB.
+
+`/app/dashboard/canvas/content/get` returns all leaf definitions, `revision` and
+`layoutDocument`. Observations remain independent and do not advance layout
+revision. Opening the Dashboard or switching profiles never repacks a saved
+layout. Default dimensions are used only when creating a placement.
+
+## Commands
+
+All three composition commands require current-Space write authorization and
+`expectedRevision`. They return `{spaceId, canvasId, revision, layoutDocument}`;
+creation also returns `createdItemId`. The backend owns validation and the whole
+operation. A stale revision changes nothing. An optional `rootDrafts` array includes unsaved root placement changes for up to
+three distinct profiles in that same commit. `rootDraft` remains supported for a
+single profile; the two fields are mutually exclusive. Ordinary layout updates
+may include `rootDrafts` for profiles other than their main `layoutSize`; organize
+may include all edited profiles before arranging its selected profile.
+
+- `/app/dashboard/canvas/composition/create`: `itemIds` selects two or more roots.
+  Existing compositions flatten to leaves; leaf identities and current dimensions
+  remain. Fixed-pass first-fit packing compares original, area, height and width
+  order across available widths. Choose smaller bounding area, then greater
+  width, with deterministic ties. No rotations, resizing or optimality guarantee.
+  Place the resulting outer rectangle near the selection without moving others.
+- `/app/dashboard/canvas/composition/ungroup`: `compositionId` expands members
+  at outer-position plus local-position in every profile, preserving current size.
+- `/app/dashboard/canvas/composition/layout/update`: `compositionId`, `layoutSize`
+  and all `members` replace that profile's local layout. Alternatively `reset:true`
+  repacks within current outer width and height. Omit `members` when resetting.
+
+Ordinary drag, resize and organize also save Canvas layout and advance revision.
+Organize treats a composition as one root, keeping its internal layout intact.
+Group copy creates fresh container and Card IDs while retaining business refs;
+move preserves member identity and internal layout. Cross-Canvas move commits
+source and target Canvas documents together. Delete and resource cleanup prune
+leaf references: one surviving member becomes an independent Card at its current
+absolute position; zero members removes the container.
+
+Existing data is converted explicitly with old writers stopped, a verified
+backup and conflict checks. Runtime startup never converts legacy placement or
+silently deletes a database. Cloud Canvas records stay in the existing `canvas`
+table with unchanged primary keys. Existing records require an explicit in-place
+conversion and a verified backup before cutover. Aliyun must have local
+transactions enabled on that table; existing tables without the feature require
+provider support. No replacement Canvas table is introduced.

package/contract/space-presentation-v1.md

@@ -49,7 +49,42 @@ login and Hub authorization retain their independently owned wire DTOs.
 
 Legacy `/scope/list`, `/scope/get`, `/scope/preference/get`, `/scope/agent/get`,
 and `/scope/location/list` readers are retired, without fallback aliases. Native
-UI membership refresh uses `/app/presentation/space/list`; the CLI uses
-`/app/space/list` for identity-only listing and selection checks, and presentation
-listing for its full management view. Neither lightweight flow expands per-Space
-context. `/focus` remains connection control, not a business Facade.
+UI membership refresh uses `/app/presentation/space/list`. CLI `space list` forwards
+`/app/space/list` and its canonical `{spaces}` DTO with `spaceId`, `name`, `mode`,
+`llmMode` and `lifecycleState`. It never expands per-Space context or adds local
+active-Space state and Hub routes. Read selected details, members and preferences
+through their own Facades. CLI selection uses `/app/client/space/focus`; it returns
+`{focusedSpaceId}` and leaves membership validation/persistence to the receiving
+Client and authoritative executor. `/focus` has no compatibility alias.
+
+Space commands pass the caller's Full/Essential choice to the Facade. Prepare
+previews remain fixed control objects. Whole-Space deletion drives the existing
+asynchronous protocol using structured Full control reads, then returns the
+unchanged `/app/space/delete/status` DTO in the requested detail. It does not
+rewrite `action` or hide operation fields. A successful status read may describe
+`DELETE_FAILED`; waiting for that failed operation still exits unsuccessfully.
+
+## Space mutation outcomes
+
+The backend settles member invite/remove outcomes before presentation. A request
+with no failed items succeeds, including already-pending/already-member invitations
+and removal of absent memberships. Fulfilled and failed items together return
+`partial`; failure of every requested item returns `error` with the complete
+per-item result in diagnostics. Full and Essential retain the same outcome.
+Location writes with `NotCreated`, `NotUpdated` or `NotDeleted` return `error`,
+with the original write result in diagnostics. Prepared previews describe planned
+work and never prove effects. Reading a failed deletion operation remains a
+successful read; accepting deletion never means erasure has completed.
+
+`/app/space/member/update` accepts `{removeEmails?: string[], inviteEmails?: string[]}`
+with at least one requested change. UI member editing and the human-operated CLI
+share this business composite. The backend normalizes/resolves all inputs and
+rejects an OWNER removal before any write. It then removes memberships and sends
+invitations under one Space mutation lock; it does not promise rollback. The same
+email cannot be removed and invited together. Its complete result is
+`{action, spaceId, removal, invitation, problems}`; removal/invitation preserve
+those individual operations' DTOs. If invitation execution becomes unconfirmed,
+`invitation` is null and `problems` explains that membership must be inspected
+before retrying. The backend settles the overall outcome. It supports direct and
+prepared modes; previews perform no writes. This operation does not extend the
+native Agent, MCP or external Skill boundary for member removal.

package/fixtures/card-skins/space.json

@@ -32,7 +32,7 @@
           "version": "1.0.0",
           "name": "Evening cards",
           "description": "Full-card skins for a color light, a playable speaker and a thermostat.",
-          "apiVersion": 1,
+          "apiVersion": 2,
           "entry": "skin.test.mjs",
           "renderers": [
             {