@mhome/core-protocol 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 mHome.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,10 @@
+# mhome-core-api
+
+Canonical internal wire protocol for MeowCore, host services, Nodes, and
+provider runtimes. Public `/app/*` contracts belong to
+`mhome-app-facade-api`; this crate owns internal MWS, authentication, LLM,
+Messaging normalization, Node runtime, and Storage contracts.
+
+Storage separates backing-filesystem capacity from Storage-owned logical
+usage. Namespace is an internal protocol term; user-facing clients present it
+as a Folder.

package/contract/node-runtime-protocol-v1.json

@@ -0,0 +1,20 @@
+{
+  "manifest": "mhome.node.runtime.v1",
+  "version": "v1",
+  "runtimeEnvelope": {
+    "requestFields": ["version", "payload"],
+    "responseFields": ["version", "data"]
+  },
+  "settings": {
+    "changedTarget": "/node/settings/changed",
+    "routes": ["settings/status", "settings/update", "settings/revert", "settings/retry"]
+  },
+  "llm": {
+    "runtimeTargetPrefix": "/llm/app/",
+    "completeTarget": "/llm/complete",
+    "modelImportUploadPathPrefix": "/llm/model/import/upload"
+  },
+  "audioBridge": {
+    "runtimeTargetPrefix": "/audiobridge/app/"
+  }
+}

package/contract/node-service-protocol-v1.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mhome.dev/contracts/node-service-protocol-v1.json",
+  "title": "Node Service Protocol V1",
+  "$defs": {
+    "emptyRequest": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    },
+    "describe": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "nodeType",
+        "serviceId",
+        "serviceVersion",
+        "instancePolicy",
+        "routes",
+        "capabilities",
+        "details"
+      ],
+      "properties": {
+        "schemaVersion": { "const": "mhome.node.describe.v1" },
+        "nodeType": { "type": "string", "minLength": 1 },
+        "serviceId": { "type": "string", "minLength": 1 },
+        "serviceVersion": { "type": "string", "minLength": 1 },
+        "instancePolicy": {
+          "enum": ["multiple", "singleton", "shared"]
+        },
+        "routes": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^/" },
+          "uniqueItems": true
+        },
+        "capabilities": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "details": { "type": "object" }
+      },
+      "additionalProperties": true
+    },
+    "readinessReason": {
+      "type": "object",
+      "required": ["code", "message", "retryable"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "retryable": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "readiness": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "nodeType",
+        "serviceId",
+        "serviceVersion",
+        "processGeneration",
+        "state",
+        "ready",
+        "revision",
+        "updatedAtMs",
+        "reason",
+        "details"
+      ],
+      "properties": {
+        "schemaVersion": { "const": "mhome.node.readiness.v1" },
+        "nodeType": { "type": "string", "minLength": 1 },
+        "serviceId": { "type": "string", "minLength": 1 },
+        "serviceVersion": { "type": "string", "minLength": 1 },
+        "processGeneration": { "type": "string", "minLength": 1 },
+        "state": {
+          "enum": [
+            "starting",
+            "ready",
+            "degraded",
+            "failed",
+            "stopping",
+            "stopped"
+          ]
+        },
+        "ready": { "type": "boolean" },
+        "revision": { "type": "integer", "minimum": 0 },
+        "updatedAtMs": { "type": "integer" },
+        "reason": {
+          "oneOf": [
+            { "type": "null" },
+            { "$ref": "#/$defs/readinessReason" }
+          ]
+        },
+        "details": { "type": "object" }
+      },
+      "additionalProperties": true
+    }
+  },
+  "type": "object",
+  "required": ["describeRequest", "readinessRequest", "describe", "readiness"],
+  "properties": {
+    "describeRequest": { "$ref": "#/$defs/emptyRequest" },
+    "readinessRequest": { "$ref": "#/$defs/emptyRequest" },
+    "describe": { "$ref": "#/$defs/describe" },
+    "readiness": { "$ref": "#/$defs/readiness" }
+  },
+  "additionalProperties": false
+}

package/fixtures/messaging-commands.conformance.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 1,
+  "parseCases": [
+    { "name": "info", "input": "/info", "result": { "kind": "command", "command": "info" } },
+    { "name": "case-insensitive-help", "input": " /HELP ", "result": { "kind": "command", "command": "help" } },
+    { "name": "new-rotates", "input": "/new", "result": { "kind": "command", "command": "rotate" } },
+    { "name": "clear-rotates", "input": "/clear", "result": { "kind": "command", "command": "rotate" } },
+    { "name": "spaced-switch", "input": "/switch 3", "result": { "kind": "command", "command": "switch", "selection": 3 } },
+    { "name": "compact-switch", "input": "/SWITCH2", "result": { "kind": "command", "command": "switch", "selection": 2 } },
+    { "name": "missing-switch-selection", "input": "/switch", "result": { "kind": "invalid_switch" } },
+    { "name": "zero-switch-selection", "input": "/switch 0", "result": { "kind": "invalid_switch" } },
+    { "name": "negative-switch-selection", "input": "/switch -1", "result": { "kind": "invalid_switch" } },
+    { "name": "unknown-text", "input": "hello", "result": { "kind": "not_command" } },
+    { "name": "unknown-command", "input": "/usage", "result": { "kind": "not_command" } }
+  ],
+  "orderingCases": [
+    { "name": "stable-scope-id-order", "scopeIds": ["scope-z", "scope-a", "scope-m"], "expected": ["scope-a", "scope-m", "scope-z"] },
+    { "name": "lexical-order-is-case-sensitive", "scopeIds": ["scope-b", "Scope-a"], "expected": ["Scope-a", "scope-b"] }
+  ]
+}

package/fixtures/normalized-inbound.conformance.json

@@ -0,0 +1,148 @@
+{
+  "valid": [
+    {
+      "name": "personal_text",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event-personal-text",
+        "address": { "provider": "telegram", "accountId": "bot-1", "conversationId": "chat-1", "audience": "personal" },
+        "actor": { "provider": "telegram", "accountId": "bot-1", "externalUserId": "user-1", "displayName": "User One" },
+        "content": { "type": "message", "providerMessageId": "message-1", "attention": "unknown", "parts": [{ "type": "text", "text": "hello" }] },
+        "occurredAtMs": 1
+      }
+    },
+    {
+      "name": "shared_text_with_lane",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event-shared-text",
+        "address": { "provider": "feishu", "accountId": "app-1", "conversationId": "group-1", "laneId": "thread-1", "audience": "shared" },
+        "actor": { "provider": "feishu", "accountId": "app-1", "externalUserId": "open-id-1" },
+        "content": { "type": "message", "attention": "addressed", "parts": [{ "type": "text", "text": "group hello" }] },
+        "conversationDisplayName": "Project room"
+      }
+    },
+    {
+      "name": "audio_with_transcript",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event-audio",
+        "address": { "provider": "telegram", "accountId": "bot-1", "conversationId": "chat-1", "audience": "personal" },
+        "actor": { "provider": "telegram", "accountId": "bot-1", "externalUserId": "user-1" },
+        "content": {
+          "type": "message",
+          "providerMessageId": "message-2",
+          "attention": "unknown",
+          "parts": [{ "type": "media", "reference": { "handle": "file-1", "kind": "audio", "mimeType": "audio/ogg", "durationMs": 1200, "transcript": "hello" } }]
+        }
+      }
+    },
+    {
+      "name": "action_selected",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event-action-selected",
+        "address": { "provider": "feishu", "accountId": "app-1", "conversationId": "chat-1", "audience": "personal" },
+        "actor": { "provider": "feishu", "accountId": "app-1", "externalUserId": "open-id-1" },
+        "content": { "type": "action_selected", "token": "route-1" }
+      }
+    }
+  ],
+  "invalid": [
+    {
+      "name": "provider_starts_with_digit",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event",
+        "address": { "provider": "1telegram", "accountId": "bot", "conversationId": "chat", "audience": "personal" },
+        "actor": { "provider": "1telegram", "accountId": "bot", "externalUserId": "user" },
+        "content": { "type": "message", "attention": "unknown", "parts": [{ "type": "text", "text": "hello" }] }
+      }
+    },
+    {
+      "name": "negative_occurrence_time",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event",
+        "address": { "provider": "telegram", "accountId": "bot", "conversationId": "chat", "audience": "personal" },
+        "actor": { "provider": "telegram", "accountId": "bot", "externalUserId": "user" },
+        "content": { "type": "message", "attention": "unknown", "parts": [{ "type": "text", "text": "hello" }] },
+        "occurredAtMs": -1
+      }
+    },
+    {
+      "name": "actor_account_mismatch",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event",
+        "address": { "provider": "telegram", "accountId": "bot-a", "conversationId": "chat", "audience": "personal" },
+        "actor": { "provider": "telegram", "accountId": "bot-b", "externalUserId": "user" },
+        "content": { "type": "message", "attention": "unknown", "parts": [{ "type": "text", "text": "hello" }] }
+      }
+    },
+    {
+      "name": "empty_message",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event",
+        "address": { "provider": "telegram", "accountId": "bot", "conversationId": "chat", "audience": "personal" },
+        "actor": { "provider": "telegram", "accountId": "bot", "externalUserId": "user" },
+        "content": { "type": "message", "attention": "unknown", "parts": [] }
+      }
+    },
+    {
+      "name": "incomplete_media_dimensions",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event",
+        "address": { "provider": "telegram", "accountId": "bot", "conversationId": "chat", "audience": "personal" },
+        "actor": { "provider": "telegram", "accountId": "bot", "externalUserId": "user" },
+        "content": { "type": "message", "attention": "unknown", "parts": [{ "type": "media", "reference": { "handle": "file", "kind": "image", "widthPx": 100 } }] }
+      }
+    },
+    {
+      "name": "unknown_schema_version",
+      "value": {
+        "schemaVersion": 2,
+        "eventId": "event",
+        "address": { "provider": "telegram", "accountId": "bot", "conversationId": "chat", "audience": "personal" },
+        "actor": { "provider": "telegram", "accountId": "bot", "externalUserId": "user" },
+        "content": { "type": "message", "attention": "unknown", "parts": [{ "type": "text", "text": "hello" }] }
+      }
+    },
+    {
+      "name": "missing_message_attention",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event",
+        "address": { "provider": "telegram", "accountId": "bot", "conversationId": "chat", "audience": "shared" },
+        "actor": { "provider": "telegram", "accountId": "bot", "externalUserId": "user" },
+        "content": { "type": "message", "parts": [{ "type": "text", "text": "hello" }] }
+      }
+    },
+    {
+      "name": "too_many_message_parts",
+      "value": {
+        "schemaVersion": 4,
+        "eventId": "event",
+        "address": { "provider": "telegram", "accountId": "bot", "conversationId": "chat", "audience": "personal" },
+        "actor": { "provider": "telegram", "accountId": "bot", "externalUserId": "user" },
+        "content": {
+          "type": "message",
+          "attention": "unknown",
+          "parts": [
+            { "type": "text", "text": "1" }, { "type": "text", "text": "2" },
+            { "type": "text", "text": "3" }, { "type": "text", "text": "4" },
+            { "type": "text", "text": "5" }, { "type": "text", "text": "6" },
+            { "type": "text", "text": "7" }, { "type": "text", "text": "8" },
+            { "type": "text", "text": "9" }, { "type": "text", "text": "10" },
+            { "type": "text", "text": "11" }, { "type": "text", "text": "12" },
+            { "type": "text", "text": "13" }, { "type": "text", "text": "14" },
+            { "type": "text", "text": "15" }, { "type": "text", "text": "16" },
+            { "type": "text", "text": "17" }
+          ]
+        }
+      }
+    }
+  ]
+}

package/manifest/core.v1.json

@@ -0,0 +1,21 @@
+{
+  "manifest": "mhome.core.v1",
+  "contractVersion": "1.1.1",
+  "protocols": {
+    "llm": {
+      "completeTarget": "/llm/complete"
+    },
+    "node": {
+      "settingsChangedTarget": "/node/settings/changed",
+      "statusContract": "mhome.node.status.v1",
+      "runtimeVersion": "v1"
+    },
+    "messaging": {
+      "normalizedInboundSchema": "schema/normalized-inbound.v4.schema.json",
+      "commandsSchema": "schema/messaging-commands.v1.schema.json"
+    },
+    "storage": {
+      "version": "storage.v2"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@mhome/core-protocol",
+  "version": "1.1.1",
+  "description": "Build-time protocol artifacts for mhome.core",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mhome-ai/foundation.git",
+    "directory": "crates/core-api"
+  },
+  "homepage": "https://github.com/mhome-ai/foundation#readme",
+  "bugs": {
+    "url": "https://github.com/mhome-ai/foundation/issues"
+  },
+  "keywords": [
+    "mhome",
+    "protocol",
+    "json-schema",
+    "fixtures"
+  ],
+  "private": false,
+  "files": [
+    "protocol.json",
+    "manifest",
+    "contract",
+    "schema",
+    "fixtures",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./protocol.json": "./protocol.json",
+    "./manifest/*": "./manifest/*",
+    "./contract/*": "./contract/*",
+    "./schema/*": "./schema/*",
+    "./fixtures/*": "./fixtures/*"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/protocol.json

@@ -0,0 +1,13 @@
+{
+  "protocol": "mhome.core",
+  "contractVersion": "1.1.1",
+  "manifest": "manifest/core.v1.json",
+  "schemas": {
+    "normalizedInbound": "schema/normalized-inbound.v4.schema.json",
+    "messagingCommands": "schema/messaging-commands.v1.schema.json"
+  },
+  "fixtures": {
+    "normalizedInbound": "fixtures/normalized-inbound.conformance.json",
+    "messagingCommands": "fixtures/messaging-commands.conformance.json"
+  }
+}

package/schema/messaging-commands.v1.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:mhome:core-api:messaging:commands:v1",
+  "title": "mHome messaging command conformance corpus v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "parseCases", "orderingCases"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "parseCases": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "input", "result"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "input": { "type": "string" },
+          "result": {
+            "oneOf": [
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["kind"],
+                "properties": { "kind": { "enum": ["not_command", "invalid_switch"] } }
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["kind", "command"],
+                "properties": {
+                  "kind": { "const": "command" },
+                  "command": { "enum": ["info", "help", "rotate"] }
+                }
+              },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["kind", "command", "selection"],
+                "properties": {
+                  "kind": { "const": "command" },
+                  "command": { "const": "switch" },
+                  "selection": { "type": "integer", "minimum": 1 }
+                }
+              }
+            ]
+          }
+        }
+      }
+    },
+    "orderingCases": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "scopeIds", "expected"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "scopeIds": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+          "expected": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+        }
+      }
+    }
+  }
+}

package/schema/normalized-inbound.v4.schema.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:mhome:core-api:messaging:normalized-inbound:v4",
+  "title": "mHome normalized messaging inbound v4",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "eventId", "address", "actor", "content"],
+  "properties": {
+    "schemaVersion": { "const": 4 },
+    "eventId": { "$ref": "#/$defs/id" },
+    "address": { "$ref": "#/$defs/address" },
+    "actor": { "$ref": "#/$defs/actor" },
+    "content": { "$ref": "#/$defs/content" },
+    "conversationDisplayName": { "$ref": "#/$defs/id" },
+    "occurredAtMs": { "type": "integer", "minimum": 0 }
+  },
+  "$defs": {
+    "id": { "type": "string", "minLength": 1, "pattern": "^\\S(?:.*\\S)?$" },
+    "text": { "type": "string", "minLength": 1 },
+    "providerId": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" },
+    "address": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "accountId", "conversationId", "audience"],
+      "properties": {
+        "provider": { "$ref": "#/$defs/providerId" },
+        "accountId": { "$ref": "#/$defs/id" },
+        "conversationId": { "$ref": "#/$defs/id" },
+        "laneId": { "$ref": "#/$defs/id" },
+        "audience": { "enum": ["personal", "shared"] }
+      }
+    },
+    "actor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "accountId", "externalUserId"],
+      "properties": {
+        "provider": { "$ref": "#/$defs/providerId" },
+        "accountId": { "$ref": "#/$defs/id" },
+        "externalUserId": { "$ref": "#/$defs/id" },
+        "displayName": { "$ref": "#/$defs/id" }
+      }
+    },
+    "media": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["handle", "kind"],
+      "properties": {
+        "handle": { "$ref": "#/$defs/id" },
+        "kind": { "enum": ["image", "audio", "video", "file"] },
+        "mimeType": { "$ref": "#/$defs/id" },
+        "sizeBytes": { "type": "integer", "minimum": 1 },
+        "fileName": { "$ref": "#/$defs/id" },
+        "durationMs": { "type": "integer", "minimum": 1 },
+        "widthPx": { "type": "integer", "minimum": 1 },
+        "heightPx": { "type": "integer", "minimum": 1 },
+        "caption": { "$ref": "#/$defs/id" },
+        "transcript": { "$ref": "#/$defs/id" }
+      },
+      "dependentRequired": {
+        "widthPx": ["heightPx"],
+        "heightPx": ["widthPx"]
+      }
+    },
+    "part": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "text"],
+          "properties": {
+            "type": { "const": "text" },
+            "text": { "$ref": "#/$defs/text" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "reference"],
+          "properties": {
+            "type": { "const": "media" },
+            "reference": { "$ref": "#/$defs/media" }
+          }
+        }
+      ]
+    },
+    "content": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "attention", "parts"],
+          "properties": {
+            "type": { "const": "message" },
+            "providerMessageId": { "$ref": "#/$defs/id" },
+            "attention": { "enum": ["addressed", "unaddressed", "unknown"] },
+            "parts": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 16,
+              "items": { "$ref": "#/$defs/part" }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "token"],
+          "properties": {
+            "type": { "const": "action_selected" },
+            "token": { "$ref": "#/$defs/id" }
+          }
+        }
+      ]
+    }
+  }
+}