@mhome/core-protocol 1.16.0 → 1.19.0

package/README.md

@@ -27,6 +27,41 @@ Storage separates backing-filesystem capacity from Storage-owned logical
 usage. Namespace is an internal protocol term; user-facing clients present it
 as a Folder.
 
+## Lossless external boundaries (core-api 1.19.0)
+
+External protocol **17** returns `HttpPayloadResponse { statusCode, body }` from
+all HTTP handler RPCs. A completed HTTP response (including 4xx/5xx) is an RPC
+success; RPC errors describe failures to execute the call, not HTTP status.
+Hosts preserve status and JSON body, never infer them from error messages.
+`ExternalCoreError` preserves domain `code`, `message` and optional `details`,
+with conversions to/from the shared client `ErrorResponse`.
+
+The transport-neutral `webhook` module defines the common route, body limit and
+JSON-versus-UTF-8-text decoding. Hosts own network listeners and method admission;
+Core owns dispatch and execution. Upgrade service shell and Core together.
+
+## Host LAN observations (introduced in core-api 1.18.0)
+
+The Host owns `host::network::HostNetworkSnapshot`, exposed through local IPC
+`GET /internal/network`. It samples eligible private IPv4 interfaces at startup
+and every 15 seconds, preferring `192.168/16`, then `10/8`, then `172.16/12`.
+Within the best priority it retains a still-valid address, otherwise picks the
+numerically smallest address. This is a deterministic common LAN policy, not
+Ethernet/Wi-Fi classification or proof of reachability to every destination.
+
+The response is `{ "lanIpv4": "192.168.1.2", "observedAtMs": 123456789 }`;
+`lanIpv4: null` means unavailable. Consumers reject observations older than
+45 seconds, future observations, and non-private IPv4. No loopback fallback.
+The query does not enumerate interfaces. Existing multicast discovery still
+uses its own complete interface inventory, not this single preferred address.
+
+External protocol 16 changes `UpdateCallbackBaseRequest` to `{ network, port }`.
+The service supplies the actual bound HTTP port and the unchanged Host
+observation. Core derives the origin instead of trusting an independent URL.
+Before the service reports, the sidecar has no callback origin. Freshness-only
+updates do not trigger subscription reconciliation. Shell and runtime must be
+upgraded together; local IPC is distinct from advertised callback URLs.
+
 ## Playground Provider (core-api 1.10.0)
 
 External protocol 15 removes the dedicated Playground webhook method and payload.

package/contract/host-permissions.md

@@ -9,48 +9,37 @@ This is a direct development cutover. There is one report model and no legacy
 serialization, implicit component selection or alternative compatibility route.
 Update Foundation consumers together after publishing the matching packages.
 
-## Declaration, executor and authorization subject
-
-Each service keeps its source-root `permission.yml`, packages it, and reports its
-own requirements. Host stores installed declarations so stopped services remain
-visible. A declaration says which feature needs access, not who the OS charges.
-
-`PermissionObservation.processId` identifies the actual executing process. It is
-not a grant identity. A helper may share its responsible application's consent.
-A Rust service must obtain a sidecar's observation over its private transport when
-that sidecar executes the protected operation; it must not substitute its own
-Foundation query. Check the real backend used by that executor, including access
-errors. Standalone launches report their actual launch context, which can differ
-from Host-managed launches. Reading status must not start an absent sidecar.
-
-`PermissionSubject` is an authorization scope established for the specific
-permission, launch path and packaging profile. Host may group by this subject and
-the full `PermissionKey`. Equal states, equal signing teams, a common parent,
-service-supplied labels or environment variables alone do not establish sharing.
-There is no generic public macOS query in this contract that discovers another
-process's TCC grant owner. Verify responsible-application attribution using the
-real signed launch chain before enabling a shared subject for a permission.
-If attribution is unconfirmed, `subject` is null and that component stays separate.
-Different Automation `targetBundleId` values always remain distinct grants.
-
-A grouped row preserves every `PermissionUse`, its observation and any collection
-error. There is deliberately no group-level grant/state that can erase a denial,
-an unknown executor or conflicting observations. A stopped service has no current
-observation. Do not copy another service's grant into that empty observation.
-Host chooses `requestComponentId` from available executors; it is null when none
-can handle the request. `supportedActions` describes available mechanisms only.
+## Declaration and executor
+
+Each service keeps its source-root `permission.yml` and packages it. The installed
+package is the sole source of desired permissions. Host loads declarations into
+its installed-service inventory on startup and when packages change. Status reads
+use that memory snapshot; they do not scan packages or maintain a database copy.
+Stopped services retain their requirements. Invalid declarations remain visible.
+
+Each `HostPermission` is one component and one permission: `componentId`,
+`componentName`, `permission`, `feature`, `reason`, `observation`, `error`, and
+`supportedActions`. There are no grouped subjects or selected substitute executors.
+`PermissionObservation.processId` identifies the actual executing process, not an
+OS grant identity. A sidecar reports its own observation through its service.
+Reading status must not start an absent sidecar or substitute its parent's grant.
+
+A helper can share its responsible application's consent without any grouping
+fields in this protocol. Equal PIDs, signing teams or states alone do not establish
+shared grants. Automation keys remain distinct per target application.
 
 ## Transport and actions
 
 - `GET /v1/permissions` returns `HostPermissions` for installed requirements,
   including stopped services and declaration/collection failures.
 - `POST /internal/permissions/request` performs one explicit request or probe in
-  the selected service's actual execution context, then refreshes the report.
+  the selected service's actual execution context. It returns `{ "ok": true }`
+  once submitted, without collecting another snapshot or waiting for user consent.
 - `POST /internal/permissions/open-settings` opens the platform settings pane.
-  Opening Settings is not a grant; status must be refreshed afterwards.
+  It returns `{ "ok": true }` after opening. Status is queried separately.
 - Both POSTs take `HostPermissionRequest`. `hostId`, `componentId` and `permission`
-  are mandatory. The component must declare that exact key. Host derives grouping
-  itself; the caller cannot assert a subject, locality or an arbitrary Settings URL.
+  are mandatory. The component must declare that exact key. The caller cannot assert locality
+  or an arbitrary Settings URL.
 - Require valid local control credentials and matching Host identity. Native
   Desktop and CLI use Client IPC. Remote Hosts accept status only. Do not send
   local control credentials to discovered addresses or redirects. A future Hub
@@ -59,18 +48,19 @@ can handle the request. `supportedActions` describes available mechanisms only.
   PID identifies the reporting service; individual observations can identify its
   sidecar. The service rejects requests outside its declared requirements.
 
-Host coalesces in-flight requests for an established shared subject and key, or
-for the individual executor and key when sharing is unknown. Transport timeout
-must not start a duplicate native request. Refresh all affected service reports
-when an operation completes. Bound collection concurrency and the whole snapshot
-latency; a stalled executor must not delay every other service indefinitely.
+Foundation owns native request deduplication in the actual executor. Transport
+timeouts do not release that ownership. UI polls status every two seconds while
+managing permissions and refreshes on focus; a pending read is shared. CLI batch
+requests query once after submission. Bound collection concurrency and the whole
+snapshot latency so a stalled executor cannot hold every other service indefinitely.
 
-## Consent and actual access
+## Authorization observations
 
-`PermissionObservation.state` describes application consent. `access` is a
-separate backend observation. A successful consent check does not establish that
-a device is powered on, present, correctly configured or usable. A successful
-scan does not prove that every connection or operation will succeed.
+`PermissionObservation.state` describes application consent only. The report
+contains declared requirements and authorization observations; it does not collect
+or carry resource availability or business-operation results. `granted` and
+`notRequired` satisfy a requirement when the observation has valid evidence and
+no errors. Missing, denied or unreadable observations remain unresolved.
 
 - `system`: passive native authorization query and its timestamp.
 - `platform`: platform consent semantics, not measured resource availability.
@@ -78,17 +68,13 @@ scan does not prove that every connection or operation will succeed.
 - `unavailable`: a reliable consent observation could not be obtained.
 - `notRequired`: this native backend has no application-consent step. It does not
   bypass users/groups, D-Bus policies, device rules, sessions, portals or sandboxes.
-- `access`: the actual backend's checked condition, timestamp and result. Missing
-  access evidence is unknown, not proof of success. Its detail describes only the
-  operation/condition actually observed. Do not relabel a hardware failure as OS
-  user denial or a successful consent query as a successful resource probe.
 
 Passive report reads never request authorization, probe Local Network, scan
 Bluetooth, launch an Automation target, restart a service or open Settings.
 Local Network's last explicit probe is historical; ordinary Refresh cannot make
 it a fresh OS setting. Keep cached reports visibly stale when collection fails.
 Missing/malformed declarations remain errors; an empty list is not proof of a
-complete inventory or successful access. Do not grant by default on other OSes.
+complete inventory. Do not grant by default on other OSes.
 
 ## macOS and Linux
 
@@ -107,8 +93,8 @@ Host BLE broker is implied by this contract.
 
 Linux native services use the configured ordinary runtime account and existing
 system interfaces, including BlueZ D-Bus. Foundation reports the absence of a
-native application-consent step separately from the backend's access results.
-Host and services must not claim access merely because there is no macOS TCC.
+native application-consent step as `notRequired`. Resource health belongs to the
+service's own diagnostics and does not affect this permission report.
 An installation preflight collects concrete missing conditions. An administrator
 may authorize a bounded, idempotent setup step for those conditions; service
 manifests must not supply privileged commands. Runtime processes remain ordinary
@@ -119,10 +105,9 @@ policies are separate deployment conditions, not automatically inherited grants.
 ## Acceptance
 
 Test passive reads without prompts; real signed allow/deny/revoke/relaunch
-behavior; shared grants across two executors; independent/unknown subjects;
-sidecar and stopped-service observations; conflicting per-service states;
+behavior; shared grants across two executors; sidecar and stopped-service observations; conflicting per-component states;
 per-target Automation; cross-host mutation rejection; required component
-selection; incomplete manifests; bounded collection; coalesced requests; and
-Linux policy denial versus missing/disabled resources. Test Linux setup first as
+selection; incomplete manifests; bounded collection; native request deduplication; and
+Linux `notRequired` without any resource observation. Test Linux setup first as
 a dry-run and verify effective access in the intended ordinary runtime session.
 Signing fixtures and mocked status tests do not prove TCC attribution.

package/manifest/core.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.core.v1",
-  "contractVersion": "1.16.0",
+  "contractVersion": "1.19.0",
   "protocols": {
     "agentGateway": {
       "submitTarget": "/agent/submit",
@@ -63,7 +63,7 @@
       "version": "storage.v2"
     },
     "hostDelivery": {
-      "externalProtocolVersion": 15,
+      "externalProtocolVersion": 17,
       "requestKind": "deliveryRequested",
       "connectionControlKind": "connectionControlRequested",
       "acceptanceBoundaries": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhome/core-protocol",
-  "version": "1.16.0",
+  "version": "1.19.0",
   "description": "Build-time protocol artifacts for mhome.core",
   "license": "MIT",
   "repository": {

package/protocol.json

@@ -1,6 +1,6 @@
 {
   "protocol": "mhome.core",
-  "contractVersion": "1.16.0",
+  "contractVersion": "1.19.0",
   "manifest": "manifest/core.v1.json",
   "schemas": {
     "hostManagementRequest": "schema/host-management-request.v1.schema.json",

package/schema/host-permissions.schema.json

@@ -41,39 +41,6 @@
         }
       ]
     },
-    "PermissionAccess": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "state",
-        "observedAtMs",
-        "detail"
-      ],
-      "properties": {
-        "state": {
-          "enum": [
-            "unknown",
-            "available",
-            "unavailable"
-          ]
-        },
-        "observedAtMs": {
-          "anyOf": [
-            {
-              "type": "integer",
-              "minimum": 0
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "detail": {
-          "type": "string",
-          "minLength": 1
-        }
-      }
-    },
     "PermissionObservation": {
       "type": "object",
       "additionalProperties": false,
@@ -83,7 +50,6 @@
         "state",
         "evidence",
         "observedAtMs",
-        "access",
         "error"
       ],
       "properties": {
@@ -124,16 +90,6 @@
             }
           ]
         },
-        "access": {
-          "anyOf": [
-            {
-              "$ref": "#/$defs/PermissionAccess"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
         "error": {
           "anyOf": [
             {
@@ -165,34 +121,18 @@
         }
       ]
     },
-    "PermissionSubject": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "id",
-        "name"
-      ],
-      "properties": {
-        "id": {
-          "type": "string",
-          "minLength": 1
-        },
-        "name": {
-          "type": "string",
-          "minLength": 1
-        }
-      }
-    },
-    "PermissionUse": {
+    "HostPermission": {
       "type": "object",
       "additionalProperties": false,
       "required": [
         "componentId",
         "componentName",
+        "permission",
         "feature",
         "reason",
         "observation",
-        "error"
+        "error",
+        "supportedActions"
       ],
       "properties": {
         "componentId": {
@@ -203,6 +143,9 @@
           "type": "string",
           "minLength": 1
         },
+        "permission": {
+          "$ref": "#/$defs/PermissionKey"
+        },
         "feature": {
           "type": "string",
           "minLength": 1
@@ -230,50 +173,6 @@
               "type": "null"
             }
           ]
-        }
-      }
-    },
-    "HostPermission": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "permission",
-        "subject",
-        "uses",
-        "requestComponentId",
-        "supportedActions"
-      ],
-      "properties": {
-        "permission": {
-          "$ref": "#/$defs/PermissionKey"
-        },
-        "subject": {
-          "anyOf": [
-            {
-              "$ref": "#/$defs/PermissionSubject"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "uses": {
-          "type": "array",
-          "minItems": 1,
-          "items": {
-            "$ref": "#/$defs/PermissionUse"
-          }
-        },
-        "requestComponentId": {
-          "anyOf": [
-            {
-              "type": "string",
-              "minLength": 1
-            },
-            {
-              "type": "null"
-            }
-          ]
         },
         "supportedActions": {
           "type": "array",
@@ -285,45 +184,7 @@
             ]
           }
         }
-      },
-      "allOf": [
-        {
-          "if": {
-            "properties": {
-              "subject": {
-                "type": "null"
-              }
-            }
-          },
-          "then": {
-            "properties": {
-              "uses": {
-                "maxItems": 1
-              }
-            }
-          }
-        },
-        {
-          "if": {
-            "properties": {
-              "requestComponentId": {
-                "type": "null"
-              }
-            }
-          },
-          "then": {
-            "properties": {
-              "supportedActions": {
-                "not": {
-                  "contains": {
-                    "const": "request"
-                  }
-                }
-              }
-            }
-          }
-        }
-      ]
+      }
     },
     "PermissionDeclarationError": {
       "type": "object",