@kumwe/studio-protocol 0.1.0-alpha.4 → 0.1.0-alpha.6

package/schemas/host-vector.schema.json

@@ -0,0 +1,197 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kumwe.org/studio/v1/host-vector.schema.json",
+  "title": "Studio canonical host conformance vector",
+  "description": "One canonical host-port exchange: the host state a conforming implementation is seeded with, the request envelope and argument Studio sends, and either the accepted result or the exact error category the closed taxonomy requires. Every precondition is a condition a real host can reproduce - a seeded revision, a withheld permission, an unknown identifier, an unsupported wire version - so the corpus is replayable by any implementation in any language without executing Studio code.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contractVersion",
+    "kind",
+    "id",
+    "description",
+    "profile",
+    "port",
+    "operation",
+    "given",
+    "context",
+    "expect"
+  ],
+  "properties": {
+    "contractVersion": { "$ref": "common.schema.json#/$defs/contractVersion" },
+    "kind": { "const": "host-vector" },
+    "id": { "$ref": "common.schema.json#/$defs/stableId" },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500
+    },
+    "profile": {
+      "description": "The conformance profile whose assertion set this vector belongs to.",
+      "$ref": "common.schema.json#/$defs/qualifiedName"
+    },
+    "port": {
+      "enum": [
+        "artifact",
+        "localization",
+        "media",
+        "model",
+        "permission",
+        "preview",
+        "recovery",
+        "resource",
+        "telemetry"
+      ]
+    },
+    "operation": { "$ref": "common.schema.json#/$defs/localName" },
+    "given": {
+      "description": "The reproducible host state before the request. A conforming host seeds exactly this state; nothing here is a test double.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["artifacts", "permissions"],
+      "properties": {
+        "artifacts": {
+          "description": "Artifact identities the host already stores, with the revision each is stored at.",
+          "type": "array",
+          "maxItems": 20,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "kind", "revision"],
+            "properties": {
+              "id": { "$ref": "common.schema.json#/$defs/stableId" },
+              "kind": { "enum": ["blueprint", "content-model", "entry"] },
+              "revision": { "$ref": "common.schema.json#/$defs/revision" }
+            }
+          }
+        },
+        "permissions": {
+          "description": "Operations the acting identity is authorized for. An operation absent here is withheld.",
+          "type": "array",
+          "maxItems": 50,
+          "uniqueItems": true,
+          "items": { "$ref": "common.schema.json#/$defs/qualifiedName" }
+        },
+        "sessionGeneration": {
+          "description": "The host's live session generation. A request naming any other generation is stale.",
+          "$ref": "common.schema.json#/$defs/revision"
+        }
+      }
+    },
+    "context": {
+      "description": "The request envelope every port operation carries.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "operationId",
+        "protocolVersion",
+        "requestId",
+        "resourceContextKey",
+        "sessionGeneration"
+      ],
+      "properties": {
+        "expectedRevision": { "$ref": "common.schema.json#/$defs/revision" },
+        "idempotencyKey": { "$ref": "common.schema.json#/$defs/stableId" },
+        "locale": { "$ref": "common.schema.json#/$defs/locale" },
+        "operationId": { "$ref": "common.schema.json#/$defs/qualifiedName" },
+        "protocolVersion": {
+          "description": "Deliberately looser than the negotiated wire version so a vector can carry a version the host must refuse.",
+          "type": "string",
+          "maxLength": 100
+        },
+        "requestId": {
+          "description": "Deliberately looser than the canonical stable identifier so a vector can carry a structurally invalid envelope the host must refuse.",
+          "type": "string",
+          "maxLength": 240
+        },
+        "resourceContextKey": { "$ref": "common.schema.json#/$defs/stableId" },
+        "sessionGeneration": { "$ref": "common.schema.json#/$defs/revision" }
+      }
+    },
+    "argument": {
+      "description": "The port argument, shaped by the operation. Absent for operations that take only the envelope.",
+      "$ref": "common.schema.json#/$defs/jsonValue"
+    },
+    "expect": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["outcome"],
+          "properties": {
+            "outcome": { "const": "result" },
+            "revision": {
+              "description": "The accepted revision the result carries. A mutation MUST advance it beyond the stored revision.",
+              "$ref": "common.schema.json#/$defs/revision"
+            },
+            "revisionAdvances": {
+              "description": "True when the operation mutates and the returned revision must differ from the stored one.",
+              "type": "boolean"
+            },
+            "value": {
+              "description": "The value shape the result carries.",
+              "enum": [
+                "artifact",
+                "artifact-references",
+                "media-asset",
+                "media-page",
+                "message-bundle",
+                "null",
+                "permission-explanation",
+                "permission-snapshot",
+                "recovery-envelope",
+                "rendered",
+                "search-page",
+                "upload-accepted",
+                "upload-grant"
+              ]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["outcome", "category"],
+          "properties": {
+            "outcome": { "const": "error" },
+            "category": {
+              "enum": [
+                "cancelled",
+                "conflict",
+                "forbidden",
+                "incompatible",
+                "internal",
+                "invalid-request",
+                "limit-exceeded",
+                "not-found",
+                "rate-limited",
+                "unauthenticated",
+                "unavailable",
+                "validation-failed"
+              ]
+            },
+            "retryable": {
+              "description": "The retry classification the error MUST carry.",
+              "type": "boolean"
+            },
+            "revision": {
+              "description": "The safe current revision a conflict MUST return so the client can resolve without a second read.",
+              "$ref": "common.schema.json#/$defs/revision"
+            },
+            "messageMustNotContain": {
+              "description": "Values the user-facing message MUST NOT echo, so a rejection never discloses private resource existence or request internals.",
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 10,
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 200
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/schemas/inspector.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kumwe.org/studio/v1/inspector.schema.json",
+  "title": "Studio inspector contribution",
+  "description": "The declarative payload behind an `inspector` plugin contribution: a panel an extension offers for inspecting or configuring the block types it declares. The declaration is inert data; whether its executable half runs, and in which realm, stays a host decision recorded in the plugin manifest.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contractVersion",
+    "kind",
+    "id",
+    "version",
+    "owner",
+    "label",
+    "blockTypes",
+    "placement"
+  ],
+  "properties": {
+    "contractVersion": { "$ref": "common.schema.json#/$defs/contractVersion" },
+    "kind": { "const": "inspector" },
+    "id": { "$ref": "common.schema.json#/$defs/qualifiedName" },
+    "version": { "$ref": "common.schema.json#/$defs/semanticVersion" },
+    "owner": { "$ref": "common.schema.json#/$defs/ownerReference" },
+    "label": { "$ref": "common.schema.json#/$defs/messageReference" },
+    "description": { "$ref": "common.schema.json#/$defs/messageReference" },
+    "blockTypes": {
+      "description": "The block types this inspector applies to. It never sees a node of any other type.",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 500,
+      "uniqueItems": true,
+      "items": { "$ref": "common.schema.json#/$defs/qualifiedName" }
+    },
+    "placement": {
+      "description": "Whether the panel augments the built-in inspector or replaces it for the declared block types. Replacement never removes the host's own policy and accessibility surfaces.",
+      "enum": ["augment", "replace"]
+    },
+    "requiredCapability": {
+      "description": "The capability the executable half requires. A declaration without one is inspectable but never executed.",
+      "$ref": "common.schema.json#/$defs/qualifiedName"
+    },
+    "extensions": { "$ref": "common.schema.json#/$defs/extensions" }
+  }
+}

package/schemas/manifest.json

@@ -13,6 +13,11 @@
       "file": "blueprint.schema.json",
       "id": "https://schemas.kumwe.org/studio/v1/blueprint.schema.json"
     },
+    {
+      "digest": "sha256-WrqnuGMzdcSi5geh9LXT5uhL1AsimMgw1jhizsAKyBA=",
+      "file": "canonical-vector.schema.json",
+      "id": "https://schemas.kumwe.org/studio/v1/canonical-vector.schema.json"
+    },
     {
       "digest": "sha256-GEoWp72qtRDvyf9V7pyQzshlqDecOjtUxIYCY7TJ8SA=",
       "file": "command-vector.schema.json",
@@ -33,6 +38,11 @@
       "file": "content-model.schema.json",
       "id": "https://schemas.kumwe.org/studio/v1/content-model.schema.json"
     },
+    {
+      "digest": "sha256-DuM7fZghcN9YsMdEHf5Eap7jijiPBLl4B68OFMFIJZo=",
+      "file": "corpus-manifest.schema.json",
+      "id": "https://schemas.kumwe.org/studio/v1/corpus-manifest.schema.json"
+    },
     {
       "digest": "sha256-KoGp/qlqlsqabqtELbd/bdRHyM1wU8sRxyyLvOg/OFg=",
       "file": "design-vocabulary.schema.json",
@@ -44,7 +54,12 @@
       "id": "https://schemas.kumwe.org/studio/v1/entry.schema.json"
     },
     {
-      "digest": "sha256-aUL8J4tsw6t00BG80OkuLvhZSQQ0bWKzk1XvYtqdb7g=",
+      "digest": "sha256-pmSxOOQO2G0OAxej15ISDEd9tS16w3XwZXyBxXyalzk=",
+      "file": "field-adapter.schema.json",
+      "id": "https://schemas.kumwe.org/studio/v1/field-adapter.schema.json"
+    },
+    {
+      "digest": "sha256-dcyPPmPmKLyU3jwajgfQd17xBtrI8sL9nhweAF3LsnY=",
       "file": "host-capabilities.schema.json",
       "id": "https://schemas.kumwe.org/studio/v1/host-capabilities.schema.json"
     },
@@ -53,6 +68,36 @@
       "file": "host-error.schema.json",
       "id": "https://schemas.kumwe.org/studio/v1/host-error.schema.json"
     },
+    {
+      "digest": "sha256-dKcbTVV2gn4IWAAH1RMpK5Ve12V+RswsDuhlrC1Ohm4=",
+      "file": "host-operations.schema.json",
+      "id": "https://schemas.kumwe.org/studio/v1/host-operations.schema.json"
+    },
+    {
+      "digest": "sha256-pOVrjkIA0RiBKF2aKfmOnmE1DlAFYgg+QBuiH+L5hIk=",
+      "file": "host-request.schema.json",
+      "id": "https://schemas.kumwe.org/studio/v1/host-request.schema.json"
+    },
+    {
+      "digest": "sha256-yNKi6fS95rlh9UubTz2FA+neXY0KDNYKs3NX0vGY+c0=",
+      "file": "host-result.schema.json",
+      "id": "https://schemas.kumwe.org/studio/v1/host-result.schema.json"
+    },
+    {
+      "digest": "sha256-pYvWThxhigEI7S1XeKyUkkN1KMZZPeRj/d5HV3ke+kQ=",
+      "file": "host-sequence-vector.schema.json",
+      "id": "https://schemas.kumwe.org/studio/v1/host-sequence-vector.schema.json"
+    },
+    {
+      "digest": "sha256-KETVqPMNQCSN8faoNW7fHuSWc6rT/Jkp4+Lh31gQuQM=",
+      "file": "host-vector.schema.json",
+      "id": "https://schemas.kumwe.org/studio/v1/host-vector.schema.json"
+    },
+    {
+      "digest": "sha256-gCIQyhwXC4DwTYwg2g+L05rrw2HIu0Ckni22Y7CDbEQ=",
+      "file": "inspector.schema.json",
+      "id": "https://schemas.kumwe.org/studio/v1/inspector.schema.json"
+    },
     {
       "digest": "sha256-tOiXLsL+sv+gnL3sUeAjA/+oumRb5AGSjkeC/1GI+/8=",
       "file": "media-asset.schema.json",
@@ -63,6 +108,11 @@
       "file": "media-reference.schema.json",
       "id": "https://schemas.kumwe.org/studio/v1/media-reference.schema.json"
     },
+    {
+      "digest": "sha256-sJCtOlIcYAvnMhMS2zPdFo8xJFzKjNlgJLz+HT7J2mg=",
+      "file": "media-upload-grant.schema.json",
+      "id": "https://schemas.kumwe.org/studio/v1/media-upload-grant.schema.json"
+    },
     {
       "digest": "sha256-46XVlSre/jC+J75IDUDtCBq8yawymUGuVmUWyhM0GV8=",
       "file": "media-upload-session.schema.json",
@@ -89,10 +139,15 @@
       "id": "https://schemas.kumwe.org/studio/v1/plugin-manifest.schema.json"
     },
     {
-      "digest": "sha256-k4h+dRatXPF43BWB2quTouTCbOioU5xkV/m31Rp1AJs=",
+      "digest": "sha256-7yQWc2+cZ+LoVmq2nZ5h4NsTO8tRjpODN7vIyJnbDKU=",
       "file": "preview-message.schema.json",
       "id": "https://schemas.kumwe.org/studio/v1/preview-message.schema.json"
     },
+    {
+      "digest": "sha256-h4au/6iI71X7lArbz5moSOxk29g+I+W/1Ewkeh7MqoI=",
+      "file": "preview-vector.schema.json",
+      "id": "https://schemas.kumwe.org/studio/v1/preview-vector.schema.json"
+    },
     {
       "digest": "sha256-QURE0s0zSfvGXEvy3meE4rQeofecsUVZksqQKfKv4ys=",
       "file": "provenance.schema.json",
@@ -109,7 +164,12 @@
       "id": "https://schemas.kumwe.org/studio/v1/rich-text.schema.json"
     },
     {
-      "digest": "sha256-yX+70kh/aPaBZiOlNon3R0B4W9ZWCnvOMKDF3ItxkqU=",
+      "digest": "sha256-200BYrY2bR/TvZGo852CHKtkxFn+7Yf2ULiVirg1R/o=",
+      "file": "schema-profile-vector.schema.json",
+      "id": "https://schemas.kumwe.org/studio/v1/schema-profile-vector.schema.json"
+    },
+    {
+      "digest": "sha256-DbxBTu984mB1oo3O1kcDuqkxbmPJjtTXq65GptM8Xkw=",
       "file": "schema-profile.schema.json",
       "id": "https://schemas.kumwe.org/studio/v1/schema-profile.schema.json"
     },

package/schemas/media-upload-grant.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kumwe.org/studio/v1/media-upload-grant.schema.json",
+  "title": "Studio media upload grant",
+  "description": "The host's authorization to transfer one upload. Bytes never cross the JSON port: the host issues a short-lived, single-purpose destination it controls and the client transfers directly to it, so custody, quotas and storage placement stay host-owned and a large body never traverses the port transport. A grant authorizes exactly the declared upload and expires; it is not a credential the client may reuse, cache, or apply to another upload.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["expiresAt", "method", "plan", "uploadId", "url"],
+  "properties": {
+    "expiresAt": {
+      "description": "When the grant stops being honoured. A client that has not completed by then re-authorizes rather than retrying against a dead destination.",
+      "$ref": "common.schema.json#/$defs/rfc3339Instant"
+    },
+    "headers": {
+      "description": "Headers the client must send verbatim on the transfer. They carry no user credential and are never logged by the client.",
+      "type": "object",
+      "maxProperties": 20,
+      "propertyNames": {
+        "type": "string",
+        "pattern": "^[A-Za-z][A-Za-z0-9-]*(?![\\s\\S])",
+        "maxLength": 100
+      },
+      "additionalProperties": { "type": "string", "maxLength": 2000 }
+    },
+    "method": { "enum": ["POST", "PUT"] },
+    "plan": {
+      "description": "The bounded transfer plan the host derived from its policy. The client transfers within it and never negotiates a larger bound.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["maximumBytes", "resumable"],
+      "properties": {
+        "chunkBytes": { "type": "integer", "minimum": 1024, "maximum": 1073741824 },
+        "maximumBytes": { "type": "integer", "minimum": 1, "maximum": 1099511627776 },
+        "resumable": { "type": "boolean" }
+      }
+    },
+    "uploadId": {
+      "description": "The opaque host-issued upload identity used to complete or abort the transfer.",
+      "$ref": "common.schema.json#/$defs/stableId"
+    },
+    "url": {
+      "description": "The absolute https destination the host controls. It is never an author-supplied value and never a Studio-derived address.",
+      "type": "string",
+      "pattern": "^https://",
+      "maxLength": 2000
+    }
+  }
+}