@mhome/artifact-protocol 1.1.1 → 1.3.0

package/README.md

@@ -6,9 +6,14 @@ The crate is the source of truth for the `meow-artifact://v1/` URI format and it
 immutable image, audio, video, and file metadata. The published schema and conformance
 fixtures are intended for non-Rust runtimes.
 
-The crate also defines the transport-neutral `/artifact/resolve` request and response.
+The crate also defines the transport-neutral `/artifact/resolve`, `/artifact/put`, and
+`/artifact/upload/prepare` request and response contracts. The upload preparation
+contract keeps large artifact bytes on an authenticated HTTP data plane instead of
+embedding them in a control-plane message.
 Delivery is an explicit `DATA_URL` or `SIGNED_URL` union; a signed URL may point to a
 cloud object store or an authenticated local streaming endpoint.
 
 TTL, storage placement, filesystem paths, signed URLs, and cloud object keys are
 runtime concerns and are deliberately not encoded into an artifact reference.
+
+Capability media values (`Image`, `Audio`) use `MediaReference`: exactly `{ "uri": "meow-artifact://v1/..." }`. The reference has no URL, inline bytes, MIME or creation timestamp fields. Parse and check kind and tenant/scope at capability boundaries; do not implicitly import media. Upload bytes with `PutArtifactRequest` or explicitly download finite HTTP(S) content with `ImportArtifactRequest` via `/app/artifact/put` and `/app/artifact/import`. Storage metadata and upload transports retain their MIME and byte fields. Resolve to temporary delivery URLs only at consumers. Conversation media sources retain their existing tagged artifact protocol. Video storage remains unsupported by the runtimes.

package/fixtures/artifact-upload.conformance.json

@@ -0,0 +1,48 @@
+{
+  "schemaVersion": 1,
+  "valid": [
+    {
+      "name": "audio-upload-request",
+      "value": {
+        "kind": "AUDIO",
+        "mimeType": "audio/ogg",
+        "sizeBytes": 10800000,
+        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "durationMillis": 3600000
+      }
+    },
+    {
+      "name": "upload-response",
+      "value": {
+        "uploadId": "upload-1",
+        "url": "http://127.0.0.1:3210/artifact/v1/upload/signed-grant",
+        "headers": {
+          "content-type": "audio/ogg",
+          "content-length": "10800000",
+          "x-meow-content-sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+        },
+        "expiresAtUnixMs": 1700000000000
+      }
+    }
+  ],
+  "invalid": [
+    {
+      "name": "uppercase-hash",
+      "value": {
+        "kind": "AUDIO",
+        "mimeType": "audio/ogg",
+        "sizeBytes": 42,
+        "sha256": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
+      }
+    },
+    {
+      "name": "non-http-upload-url",
+      "value": {
+        "uploadId": "upload-1",
+        "url": "file:///tmp/upload",
+        "headers": {},
+        "expiresAtUnixMs": 1700000000000
+      }
+    }
+  ]
+}

package/manifest/artifact.v1.json

@@ -1,8 +1,13 @@
 {
   "manifest": "mhome.artifact.v1",
-  "contractVersion": "1.1.1",
+  "contractVersion": "1.3.0",
   "uriPrefix": "meow-artifact://v1/",
-  "kinds": ["image", "audio", "video", "file"],
+  "kinds": [
+    "image",
+    "audio",
+    "video",
+    "file"
+  ],
   "resolve": {
     "target": "/artifact/resolve",
     "schema": "schema/artifact-resolve.v1.schema.json",
@@ -12,5 +17,18 @@
     "target": "/artifact/put",
     "schema": "schema/artifact-put.v1.schema.json",
     "schemaVersion": 1
+  },
+  "uploadPrepare": {
+    "target": "/artifact/upload/prepare",
+    "schema": "schema/artifact-upload.v1.schema.json",
+    "schemaVersion": 1
+  },
+  "mediaReference": {
+    "schema": "schema/media-reference.v1.schema.json",
+    "schemaVersion": 1
+  },
+  "import": {
+    "schema": "schema/artifact-import.v1.schema.json",
+    "schemaVersion": 1
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhome/artifact-protocol",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Build-time protocol artifacts for mhome.artifact",
   "license": "MIT",
   "repository": {

package/protocol.json

@@ -1,15 +1,19 @@
 {
   "protocol": "mhome.artifact",
-  "contractVersion": "1.1.1",
+  "contractVersion": "1.3.0",
   "manifest": "manifest/artifact.v1.json",
   "schemas": {
     "artifactMetadata": "schema/artifact-metadata.v1.schema.json",
     "artifactResolve": "schema/artifact-resolve.v1.schema.json",
-    "artifactPut": "schema/artifact-put.v1.schema.json"
+    "artifactPut": "schema/artifact-put.v1.schema.json",
+    "artifactImport": "schema/artifact-import.v1.schema.json",
+    "mediaReference": "schema/media-reference.v1.schema.json",
+    "artifactUpload": "schema/artifact-upload.v1.schema.json"
   },
   "fixtures": {
     "artifactReference": "fixtures/artifact-reference.conformance.json",
     "artifactResolve": "fixtures/artifact-resolve.conformance.json",
-    "artifactPut": "fixtures/artifact-put.conformance.json"
+    "artifactPut": "fixtures/artifact-put.conformance.json",
+    "artifactUpload": "fixtures/artifact-upload.conformance.json"
   }
 }

package/schema/artifact-import.v1.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mhome.ai/schema/artifact-import.v1.schema.json",
+  "title": "MeowLink artifact import request",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "kind",
+    "sourceUrl"
+  ],
+  "properties": {
+    "kind": {
+      "enum": [
+        "IMAGE",
+        "AUDIO",
+        "FILE"
+      ]
+    },
+    "sourceUrl": {
+      "type": "string",
+      "pattern": "^https?://",
+      "minLength": 8
+    },
+    "mimeType": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 255
+    }
+  }
+}

package/schema/artifact-upload.v1.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mhome.ai/schema/artifact-upload.v1.schema.json",
+  "title": "mHome Artifact Upload v1",
+  "oneOf": [
+    { "$ref": "#/$defs/request" },
+    { "$ref": "#/$defs/response" }
+  ],
+  "$defs": {
+    "request": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "mimeType", "sizeBytes", "sha256"],
+      "properties": {
+        "kind": { "enum": ["IMAGE", "AUDIO", "VIDEO", "FILE"] },
+        "mimeType": { "type": "string", "minLength": 3, "maxLength": 255 },
+        "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "durationMillis": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }
+      }
+    },
+    "response": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["uploadId", "url", "headers", "expiresAtUnixMs"],
+      "properties": {
+        "uploadId": { "type": "string", "minLength": 1 },
+        "url": { "type": "string", "pattern": "^https?://" },
+        "headers": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "expiresAtUnixMs": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }
+      }
+    }
+  }
+}

package/schema/media-reference.v1.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mhome.ai/schema/media-reference.v1.schema.json",
+  "title": "MeowLink media reference",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "uri"
+  ],
+  "properties": {
+    "uri": {
+      "type": "string",
+      "pattern": "^meow-artifact://v1/",
+      "maxLength": 2048
+    }
+  }
+}