@mhome/artifact-protocol 1.7.0 → 1.9.0

package/README.md

@@ -19,3 +19,50 @@ 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.
 
 Upload/import preserves bytes. Callers perform conversion before upload. Public ingress is limited to 1 MiB; internal producers retain their own limits. The shared reference and storage contracts do not impose the public ingress limit.
+
+### Temporary artifacts (MeowCore)
+
+`put`, explicit HTTP `import`, and `upload/prepare` accept `temporary: true`.
+Omitting the flag preserves durable storage. The flag is a storage request, not
+part of the content-addressed URI: putting the same bytes in the same tenant and
+scope reuses that content. Existing durable content is never downgraded. Put and
+resolve responses report `temporary: true` and `expiresAtUnixMs` for temporary
+content; durable responses omit both fields.
+
+MeowCore keeps temporary content only in memory, without a total capacity or
+object-count quota and without disk spill. Each successful content read resets
+one hour of idle retention. Upload and repeated put / import revalidation also
+reset that deadline; resolve and metadata queries do not. Objects never read
+expire one hour after upload. Reads reject expired objects immediately, while
+periodic maintenance reclaims idle entries. An already opened snapshot may
+finish after deletion or expiry. Existing per-upload size and transport limits
+still apply. The caller is responsible for peak memory use.
+
+`/artifact/persist` takes `{ "uri": "meow-artifact://…" }` and returns a put
+response after durable storage succeeds. Promotion is idempotent, preserves the
+URI, and leaves the temporary object readable if writing fails. MeowCore's
+existing thirty-day durable retention policy still applies. Expired or missing
+objects cannot be promoted. Persist before saving a reference in long-lived
+history or scheduling work beyond its expiration.
+
+`/artifact/delete` takes the same request and returns `{}`. Deleting missing
+content succeeds. Deletion affects all metadata aliases of that content in the
+same scope; an opened snapshot may finish, while subsequent opens fail. Do not
+delete after each LLM call when another caller may reuse the URI. There is no
+separate eviction API. A signed URL is not a revocable object identity: recreating
+the identical content may make an unexpired old URL usable again.
+
+App Facade equivalents are `/app/artifact/persist` and `/app/artifact/delete`;
+Wasm hosts expose `artifact_persist_async` and `artifact_delete_async`. LLM inputs
+continue to use canonical Artifact references. Temporary HTTP uploads and native
+reads transfer content from memory without staging files. Large native transfers use bounded attachments on the existing
+IPC connection; the JSON control frame limit is unchanged. Temporary delivery uses
+`no-store`, and resolve grants never outlive the reported object expiration.
+
+Temporary state is process-owned and is lost on restart. Startup removes
+abandoned spill directories left by older runtimes. This contract adds no database
+or migration. Cloud forwarding preserves the local owner’s lifetime metadata and
+routes persist/delete to that owner. Cloud-owned storage rejects temporary writes;
+it supports idempotent persist for existing durable content and exact-key delete.
+A multi-instance cloud service must not emulate temporary storage with an
+uncoordinated in-process map.

package/manifest/artifact.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.artifact.v1",
-  "contractVersion": "1.7.0",
+  "contractVersion": "1.9.0",
   "uriPrefix": "meow-artifact://v1/",
   "kinds": [
     "image",
@@ -30,5 +30,17 @@
   "import": {
     "schema": "schema/artifact-import.v1.schema.json",
     "schemaVersion": 1
+  },
+  "persist": {
+    "target": "/artifact/persist",
+    "requestSchema": "schema/artifact-resolve.v1.schema.json#/$defs/request",
+    "responseSchema": "schema/artifact-put.v1.schema.json#/$defs/response",
+    "schemaVersion": 1
+  },
+  "delete": {
+    "target": "/artifact/delete",
+    "requestSchema": "schema/artifact-resolve.v1.schema.json#/$defs/request",
+    "responseSchema": "schema/artifact-delete.v1.schema.json",
+    "schemaVersion": 1
   }
 }

package/package.json

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

package/protocol.json

@@ -1,11 +1,12 @@
 {
   "protocol": "mhome.artifact",
-  "contractVersion": "1.7.0",
+  "contractVersion": "1.9.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",
+    "artifactDelete": "schema/artifact-delete.v1.schema.json",
     "artifactImport": "schema/artifact-import.v1.schema.json",
     "mediaReference": "schema/media-reference.v1.schema.json",
     "artifactUpload": "schema/artifact-upload.v1.schema.json"

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

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {}
+}

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

@@ -25,6 +25,10 @@
       "type": "string",
       "minLength": 3,
       "maxLength": 255
+    },
+    "temporary": {
+      "type": "boolean",
+      "default": false
     }
   }
 }

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

@@ -58,8 +58,48 @@
           "type": "integer",
           "minimum": 1,
           "maximum": 9007199254740991
+        },
+        "temporary": {
+          "type": "boolean",
+          "default": false
+        },
+        "expiresAtUnixMs": {
+          "type": "integer",
+          "minimum": 1
         }
-      }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "temporary": {
+                "const": true
+              }
+            },
+            "required": [
+              "temporary"
+            ]
+          },
+          "then": {
+            "properties": {
+              "expiresAtUnixMs": {}
+            },
+            "required": [
+              "expiresAtUnixMs"
+            ]
+          },
+          "else": {
+            "not": {
+              "properties": {
+                "expiresAtUnixMs": {}
+              },
+              "required": [
+                "expiresAtUnixMs"
+              ]
+            }
+          }
+        }
+      ]
     },
     "request": {
       "type": "object",
@@ -93,6 +133,10 @@
           "type": "integer",
           "minimum": 1,
           "maximum": 9007199254740991
+        },
+        "temporary": {
+          "type": "boolean",
+          "default": false
         }
       }
     },

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

@@ -149,8 +149,48 @@
               }
             }
           }
+        },
+        "temporary": {
+          "type": "boolean",
+          "default": false
+        },
+        "expiresAtUnixMs": {
+          "type": "integer",
+          "minimum": 1
         }
-      }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "temporary": {
+                "const": true
+              }
+            },
+            "required": [
+              "temporary"
+            ]
+          },
+          "then": {
+            "properties": {
+              "expiresAtUnixMs": {}
+            },
+            "required": [
+              "expiresAtUnixMs"
+            ]
+          },
+          "else": {
+            "not": {
+              "properties": {
+                "expiresAtUnixMs": {}
+              },
+              "required": [
+                "expiresAtUnixMs"
+              ]
+            }
+          }
+        }
+      ]
     }
   }
 }

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

@@ -47,6 +47,10 @@
           "type": "integer",
           "minimum": 1,
           "maximum": 9007199254740991
+        },
+        "temporary": {
+          "type": "boolean",
+          "default": false
         }
       }
     },