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

package/schemas/corpus-manifest.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kumwe.org/studio/v1/corpus-manifest.schema.json",
+  "title": "Studio corpus integrity manifest",
+  "description": "The digest of every file in the published conformance corpus, grouped by the directory it ships in. A host that vendors the corpus verifies its copy against this manifest, so a stale or altered fixture is detected before it silently changes what a conformance claim means. The schema manifest covers the schemas; this covers everything replayed against them.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "kind", "groups"],
+  "properties": {
+    "contractVersion": { "$ref": "common.schema.json#/$defs/contractVersion" },
+    "kind": { "const": "corpus-manifest" },
+    "groups": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 50,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["files", "group", "path"],
+        "properties": {
+          "files": {
+            "type": "array",
+            "maxItems": 5000,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["digest", "file"],
+              "properties": {
+                "digest": { "$ref": "common.schema.json#/$defs/integrity" },
+                "file": { "type": "string", "minLength": 1, "maxLength": 200 }
+              }
+            }
+          },
+          "group": {
+            "description": "The stable name of the corpus group.",
+            "$ref": "common.schema.json#/$defs/localName"
+          },
+          "path": {
+            "description": "The package-relative directory the group ships in.",
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/field-adapter.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kumwe.org/studio/v1/field-adapter.schema.json",
+  "title": "Studio field adapter contribution",
+  "description": "The declarative payload behind a `field-adapter` plugin contribution: a control an extension offers for editing a declared field kind. The declaration is inert data - it names the control, the field kinds it accepts, the capability its executable half requires, and the bounded option schema an author configures it through. It never carries markup, styles or code.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contractVersion",
+    "kind",
+    "id",
+    "version",
+    "owner",
+    "label",
+    "control",
+    "fieldKinds"
+  ],
+  "properties": {
+    "contractVersion": { "$ref": "common.schema.json#/$defs/contractVersion" },
+    "kind": { "const": "field-adapter" },
+    "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" },
+    "control": {
+      "description": "The control identifier a field's authoring metadata names to select this adapter.",
+      "$ref": "common.schema.json#/$defs/qualifiedName"
+    },
+    "fieldKinds": {
+      "description": "The field kinds this control accepts. A field of any other kind never resolves to it.",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 50,
+      "uniqueItems": true,
+      "items": { "$ref": "common.schema.json#/$defs/qualifiedName" }
+    },
+    "optionSchema": {
+      "description": "The bounded schema an author's control options validate against, inside the Studio Schema Profile exactly like a contributed block's property schema.",
+      "type": "object",
+      "maxProperties": 100,
+      "propertyNames": { "$ref": "common.schema.json#/$defs/safeJsonMemberName" },
+      "additionalProperties": { "$ref": "common.schema.json#/$defs/jsonValue" }
+    },
+    "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/host-capabilities.schema.json

@@ -33,14 +33,15 @@
         "additionalProperties": false,
         "required": ["id", "version", "operations"],
         "properties": {
-          "id": { "$ref": "common.schema.json#/$defs/qualifiedName" },
+          "id": { "$ref": "host-operations.schema.json#/$defs/portCapability" },
           "version": { "$ref": "common.schema.json#/$defs/semanticVersion" },
           "operations": {
+            "description": "The operations this host actually implements, closed by the operation registry so a capability document cannot advertise an operation that is not on the wire.",
             "type": "array",
             "minItems": 1,
             "maxItems": 100,
             "uniqueItems": true,
-            "items": { "$ref": "common.schema.json#/$defs/qualifiedName" }
+            "items": { "$ref": "host-operations.schema.json#/$defs/operationCapability" }
           }
         }
       }

package/schemas/host-operations.schema.json

@@ -0,0 +1,162 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kumwe.org/studio/v1/host-operations.schema.json",
+  "title": "Studio host port operation registry",
+  "description": "The closed registry binding every host port operation to its names: the wire operation a transport addresses, the typed method a client calls, and the capability identifier a host advertises. A host cannot publish a truthful capability document without it, because the vocabularies must map one to one. Adding an operation is an additive protocol change; renaming or removing one is breaking.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "kind", "operations"],
+  "properties": {
+    "contractVersion": {
+      "$ref": "common.schema.json#/$defs/contractVersion"
+    },
+    "kind": {
+      "const": "host-operations"
+    },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 200,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "capability",
+          "expectsRevision",
+          "method",
+          "mutating",
+          "operation",
+          "port",
+          "portCapability",
+          "required",
+          "route"
+        ],
+        "properties": {
+          "capability": {
+            "$ref": "#/$defs/operationCapability"
+          },
+          "expectsRevision": {
+            "description": "The operation is concurrency-protected: the request envelope carries expectedRevision and a mismatch conflicts.",
+            "type": "boolean"
+          },
+          "method": {
+            "description": "The typed method name a client port interface exposes, which differs from the wire name where the wire spelling is not a valid identifier.",
+            "type": "string",
+            "pattern": "^[a-z][A-Za-z0-9]*(?![\\s\\S])",
+            "maxLength": 100
+          },
+          "mutating": {
+            "description": "The operation changes host state, so it is authorized, audited and idempotent when retried.",
+            "type": "boolean"
+          },
+          "operation": {
+            "$ref": "common.schema.json#/$defs/localName"
+          },
+          "port": {
+            "$ref": "#/$defs/portName"
+          },
+          "portCapability": {
+            "$ref": "#/$defs/portCapability"
+          },
+          "required": {
+            "description": "The port must be present for an editable session; an absent optional port degrades with diagnostics.",
+            "type": "boolean"
+          },
+          "route": {
+            "$ref": "#/$defs/operationRoute"
+          }
+        }
+      }
+    },
+    "extensions": {
+      "$ref": "common.schema.json#/$defs/extensions"
+    }
+  },
+  "$defs": {
+    "operationCapability": {
+      "description": "The capability identifier a host advertises for one port operation.",
+      "enum": [
+        "studio.operation/artifact.dependencies",
+        "studio.operation/artifact.load",
+        "studio.operation/artifact.publish",
+        "studio.operation/artifact.save",
+        "studio.operation/artifact.unpublish",
+        "studio.operation/localization.messages",
+        "studio.operation/media.abort-upload",
+        "studio.operation/media.authorize-upload",
+        "studio.operation/media.complete-upload",
+        "studio.operation/media.get",
+        "studio.operation/media.import-external",
+        "studio.operation/media.list",
+        "studio.operation/media.upload-status",
+        "studio.operation/model.get",
+        "studio.operation/model.list",
+        "studio.operation/permission.explain",
+        "studio.operation/permission.refresh",
+        "studio.operation/preview.cancel",
+        "studio.operation/preview.render",
+        "studio.operation/recovery.discard",
+        "studio.operation/recovery.load",
+        "studio.operation/recovery.store",
+        "studio.operation/resource.search",
+        "studio.operation/telemetry.emit"
+      ]
+    },
+    "operationRoute": {
+      "description": "The transport route segment addressing one port operation.",
+      "enum": [
+        "artifact/dependencies",
+        "artifact/load",
+        "artifact/publish",
+        "artifact/save",
+        "artifact/unpublish",
+        "localization/messages",
+        "media/abort-upload",
+        "media/authorize-upload",
+        "media/complete-upload",
+        "media/get",
+        "media/import-external",
+        "media/list",
+        "media/upload-status",
+        "model/get",
+        "model/list",
+        "permission/explain",
+        "permission/refresh",
+        "preview/cancel",
+        "preview/render",
+        "recovery/discard",
+        "recovery/load",
+        "recovery/store",
+        "resource/search",
+        "telemetry/emit"
+      ]
+    },
+    "portCapability": {
+      "description": "The capability identifier a host advertises for a whole port.",
+      "enum": [
+        "studio.port/artifact",
+        "studio.port/localization",
+        "studio.port/media",
+        "studio.port/model",
+        "studio.port/permission",
+        "studio.port/preview",
+        "studio.port/recovery",
+        "studio.port/resource",
+        "studio.port/telemetry"
+      ]
+    },
+    "portName": {
+      "enum": [
+        "artifact",
+        "localization",
+        "media",
+        "model",
+        "permission",
+        "preview",
+        "recovery",
+        "resource",
+        "telemetry"
+      ]
+    }
+  }
+}

package/schemas/host-request.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kumwe.org/studio/v1/host-request.schema.json",
+  "title": "Studio host port request",
+  "description": "The body of one host port operation call: the argument the operation takes and the envelope every operation carries. A host validates this shape before dispatching, so a malformed envelope is refused as invalid-request rather than partially honoured.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["context"],
+  "properties": {
+    "arguments": {
+      "description": "The operation argument. Absent for operations that take only the envelope.",
+      "$ref": "common.schema.json#/$defs/jsonValue"
+    },
+    "context": { "$ref": "#/$defs/requestContext" }
+  },
+  "$defs": {
+    "requestContext": {
+      "description": "The request envelope. Actor identity and authorization evidence are attached by the trusted transport and never appear here: a Studio-supplied actor value is display context, never authentication.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "operationId",
+        "protocolVersion",
+        "requestId",
+        "resourceContextKey",
+        "sessionGeneration"
+      ],
+      "properties": {
+        "expectedRevision": {
+          "description": "The revision the caller believes is current. Required by every operation the registry marks expectsRevision; a mismatch conflicts and the host returns the safe current revision.",
+          "$ref": "common.schema.json#/$defs/revision"
+        },
+        "idempotencyKey": {
+          "description": "Present when a mutation may be retried. A host that has already accepted this key for this operation returns the original outcome rather than applying the mutation twice.",
+          "$ref": "common.schema.json#/$defs/stableId"
+        },
+        "locale": {
+          "description": "The locale for localized diagnostics. Absent means the session locale.",
+          "$ref": "common.schema.json#/$defs/locale"
+        },
+        "operationId": {
+          "description": "The capability identifier of the operation being invoked, closed by the operation registry.",
+          "$ref": "host-operations.schema.json#/$defs/operationCapability"
+        },
+        "protocolVersion": {
+          "description": "The negotiated wire version. A version the host does not support is refused as incompatible before any work.",
+          "$ref": "common.schema.json#/$defs/semanticVersion"
+        },
+        "requestId": {
+          "description": "Unique per call, used for correlation. It never identifies the actor.",
+          "$ref": "common.schema.json#/$defs/stableId"
+        },
+        "resourceContextKey": {
+          "description": "The opaque, non-secret, non-bearer context key. The host resolves and verifies the canonical context from this key rather than trusting client-supplied scope values; a stale, altered or cross-session key is rejected without disclosing private resource existence.",
+          "$ref": "common.schema.json#/$defs/stableId"
+        },
+        "sessionGeneration": {
+          "description": "The generation the session was opened at. A superseded generation is refused, because a permission or context change mints a new one.",
+          "$ref": "common.schema.json#/$defs/revision"
+        },
+        "traceContext": {
+          "description": "Trace correlation permitted by privacy policy. It carries no actor identity, credential or private resource value.",
+          "type": "object",
+          "maxProperties": 10,
+          "propertyNames": { "$ref": "common.schema.json#/$defs/localName" },
+          "additionalProperties": { "type": "string", "maxLength": 200 }
+        }
+      }
+    }
+  }
+}

package/schemas/host-result.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kumwe.org/studio/v1/host-result.schema.json",
+  "title": "Studio host port result",
+  "description": "The body a host returns when a port operation succeeds. A failure is never expressed here: it carries the canonical host error document instead, so a client distinguishes outcomes by shape rather than by guessing from a status code.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["value"],
+  "properties": {
+    "revision": {
+      "description": "The accepted resource revision. Every operation the registry marks expectsRevision returns the revision it advanced to, so a client never re-reads to learn what it just wrote.",
+      "$ref": "common.schema.json#/$defs/revision"
+    },
+    "value": {
+      "description": "The normalized operation result. Operations that answer with nothing return null rather than omitting the member, so absence is explicit.",
+      "$ref": "common.schema.json#/$defs/jsonValue"
+    }
+  }
+}

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" }
+  }
+}