@kumwe/studio-protocol 0.1.0-alpha.10

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-sequence-vector.schema.json

@@ -0,0 +1,342 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kumwe.org/studio/v1/host-sequence-vector.schema.json",
+  "title": "Studio canonical host sequence conformance vector",
+  "description": "A deterministic sequence of host-port invocations, settlements, logical-clock advances and renderer completions. Every stateful precondition is bounded JSON so another runtime can reproduce retries, rate-limit windows and in-flight cancellation without wall-clock sleeps or executable fixture callbacks.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contractVersion",
+    "kind",
+    "id",
+    "description",
+    "profile",
+    "assertions",
+    "idempotencyPolicy",
+    "given",
+    "steps",
+    "expectFinal"
+  ],
+  "properties": {
+    "contractVersion": { "$ref": "common.schema.json#/$defs/contractVersion" },
+    "kind": { "const": "host-sequence-vector" },
+    "id": { "$ref": "common.schema.json#/$defs/stableId" },
+    "description": { "type": "string", "minLength": 1, "maxLength": 500 },
+    "profile": { "const": "studio.profile/host-baseline-v2" },
+    "assertions": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 12,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/assertion" }
+    },
+    "idempotencyPolicy": { "$ref": "#/$defs/idempotencyPolicy" },
+    "given": { "$ref": "#/$defs/given" },
+    "steps": {
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 24,
+      "items": {
+        "oneOf": [
+          { "$ref": "#/$defs/invokeStep" },
+          { "$ref": "#/$defs/settleStep" },
+          { "$ref": "#/$defs/advanceClockStep" },
+          { "$ref": "#/$defs/releasePreviewRenderStep" }
+        ]
+      }
+    },
+    "expectFinal": { "$ref": "#/$defs/finalState" }
+  },
+  "$defs": {
+    "assertion": {
+      "enum": [
+        "operation-id-mismatch-refusal",
+        "idempotent-in-flight-coalescing",
+        "idempotent-completed-replay",
+        "idempotency-changed-argument-refusal",
+        "idempotency-changed-context-refusal",
+        "idempotency-resource-scope-separation",
+        "canonical-number-equivalence",
+        "failed-attempt-retry",
+        "fixed-window-rate-limit",
+        "fixed-window-reset",
+        "in-flight-preview-cancellation",
+        "cross-context-cancellation-isolation",
+        "late-preview-result-discard"
+      ]
+    },
+    "idempotencyPolicy": {
+      "description": "The exact map key and canonical intent preimage used by this profile. Scope fields select an accepted record; the argument and listed semantic context fields form its canonical JSON fingerprint. Optional semantic fields that are absent are omitted, not serialized as null. Canonical JSON applies its number grammar, including normalization of negative zero to zero. Per-attempt request and trace correlation never affect intent.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "scopeFields",
+        "argumentCanonicalization",
+        "intentContextFields",
+        "absentOptionalFields",
+        "numberNormalization",
+        "excludedContextFields"
+      ],
+      "properties": {
+        "scopeFields": {
+          "const": ["idempotencyKey", "operationId", "resourceContextKey", "sessionGeneration"]
+        },
+        "argumentCanonicalization": { "const": "canonical-json" },
+        "intentContextFields": {
+          "const": ["expectedRevision", "locale", "protocolVersion"]
+        },
+        "absentOptionalFields": { "const": "omit" },
+        "numberNormalization": { "const": "canonical-json" },
+        "excludedContextFields": { "const": ["requestId", "traceContext"] }
+      }
+    },
+    "port": {
+      "enum": [
+        "artifact",
+        "localization",
+        "media",
+        "model",
+        "permission",
+        "preview",
+        "recovery",
+        "resource",
+        "telemetry"
+      ]
+    },
+    "artifactSeed": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "revision", "status"],
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/stableId" },
+        "kind": { "enum": ["blueprint", "content-model", "entry"] },
+        "revision": { "$ref": "common.schema.json#/$defs/revision" },
+        "status": { "enum": ["archived", "draft", "in-review", "published", "retired"] }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "kind": { "const": "entry" } }, "required": ["kind"] },
+          "then": {
+            "properties": {
+              "status": { "enum": ["archived", "draft", "in-review", "published"] }
+            }
+          },
+          "else": {
+            "properties": { "status": { "enum": ["draft", "published", "retired"] } }
+          }
+        }
+      ]
+    },
+    "rateLimit": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "operationId",
+        "maximumRequests",
+        "windowMilliseconds",
+        "retryAfterMilliseconds"
+      ],
+      "properties": {
+        "operationId": { "$ref": "host-operations.schema.json#/$defs/operationCapability" },
+        "maximumRequests": { "type": "integer", "minimum": 1, "maximum": 1000 },
+        "windowMilliseconds": { "type": "integer", "minimum": 1, "maximum": 86400000 },
+        "retryAfterMilliseconds": {
+          "description": "The retry delay at logical time zero after the fixed-window bound is reached. It equals the initial window duration.",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 86400000
+        }
+      }
+    },
+    "given": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["artifacts", "permissions", "sessionGeneration"],
+      "properties": {
+        "artifacts": {
+          "type": "array",
+          "maxItems": 20,
+          "items": { "$ref": "#/$defs/artifactSeed" }
+        },
+        "permissions": {
+          "type": "array",
+          "maxItems": 50,
+          "uniqueItems": true,
+          "items": { "$ref": "common.schema.json#/$defs/qualifiedName" }
+        },
+        "rateLimits": {
+          "type": "array",
+          "maxItems": 20,
+          "items": { "$ref": "#/$defs/rateLimit" }
+        },
+        "sessionGeneration": { "$ref": "common.schema.json#/$defs/revision" }
+      }
+    },
+    "requestContext": {
+      "description": "The canonical host request envelope. Malformed single exchanges remain in the original host corpus; an intentional registered-capability mismatch is an executable invalid-request assertion here.",
+      "$ref": "host-request.schema.json#/$defs/requestContext"
+    },
+    "resultExpectation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["outcome"],
+      "properties": {
+        "outcome": { "const": "result" },
+        "revisionAdvancesFrom": { "$ref": "common.schema.json#/$defs/revision" },
+        "sameAs": { "$ref": "common.schema.json#/$defs/stableId" },
+        "value": { "enum": ["null", "rendered"] }
+      }
+    },
+    "errorExpectation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["outcome", "category", "retryable"],
+      "properties": {
+        "outcome": { "const": "error" },
+        "category": {
+          "enum": [
+            "cancelled",
+            "conflict",
+            "forbidden",
+            "incompatible",
+            "internal",
+            "invalid-request",
+            "limit-exceeded",
+            "not-found",
+            "rate-limited",
+            "unauthenticated",
+            "unavailable",
+            "validation-failed"
+          ]
+        },
+        "retryable": { "type": "boolean" },
+        "retryAfterMilliseconds": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 86400000
+        }
+      }
+    },
+    "expectation": {
+      "oneOf": [{ "$ref": "#/$defs/resultExpectation" }, { "$ref": "#/$defs/errorExpectation" }]
+    },
+    "invokeStep": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["action", "id", "port", "operation", "context", "completion"],
+      "properties": {
+        "action": { "const": "invoke" },
+        "id": { "$ref": "common.schema.json#/$defs/stableId" },
+        "port": { "$ref": "#/$defs/port" },
+        "operation": { "$ref": "common.schema.json#/$defs/localName" },
+        "context": { "$ref": "#/$defs/requestContext" },
+        "argument": { "$ref": "common.schema.json#/$defs/jsonValue" },
+        "completion": { "enum": ["pending", "settled"] },
+        "expect": { "$ref": "#/$defs/expectation" }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "completion": { "const": "settled" } },
+            "required": ["completion"]
+          },
+          "then": {
+            "properties": { "expect": { "$ref": "#/$defs/expectation" } },
+            "required": ["expect"]
+          },
+          "else": { "not": { "required": ["expect"] } }
+        },
+        {
+          "if": {
+            "properties": {
+              "port": { "const": "preview" },
+              "operation": { "const": "render" }
+            },
+            "required": ["port", "operation"]
+          },
+          "then": {
+            "properties": {
+              "argument": { "$ref": "preview-message.schema.json#/$defs/render" }
+            },
+            "required": ["argument"]
+          }
+        }
+      ]
+    },
+    "settleStep": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["action", "id", "invocation", "expect"],
+      "properties": {
+        "action": { "const": "settle" },
+        "id": { "$ref": "common.schema.json#/$defs/stableId" },
+        "invocation": { "$ref": "common.schema.json#/$defs/stableId" },
+        "expect": { "$ref": "#/$defs/expectation" }
+      }
+    },
+    "advanceClockStep": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["action", "id", "milliseconds"],
+      "properties": {
+        "action": { "const": "advance-clock" },
+        "id": { "$ref": "common.schema.json#/$defs/stableId" },
+        "milliseconds": { "type": "integer", "minimum": 1, "maximum": 86400000 }
+      }
+    },
+    "releasePreviewRenderStep": {
+      "description": "A deterministic renderer completion injected after a prior preview.render invocation. It is a harness precondition, not a host port or transport operation.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["action", "id", "invocation", "value"],
+      "properties": {
+        "action": { "const": "release-preview-render" },
+        "id": { "$ref": "common.schema.json#/$defs/stableId" },
+        "invocation": { "$ref": "common.schema.json#/$defs/stableId" },
+        "value": { "$ref": "preview-message.schema.json#/$defs/rendered" }
+      }
+    },
+    "artifactFinalState": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "status", "revisionFrom"],
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/stableId" },
+        "status": { "enum": ["archived", "draft", "in-review", "published", "retired"] },
+        "revisionFrom": { "$ref": "common.schema.json#/$defs/stableId" }
+      }
+    },
+    "recoveryFinalState": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["resourceContextKey", "value"],
+      "properties": {
+        "resourceContextKey": { "$ref": "common.schema.json#/$defs/stableId" },
+        "value": { "$ref": "common.schema.json#/$defs/jsonValue" }
+      }
+    },
+    "finalState": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pendingPreviewRenders", "previewDeliveries"],
+      "properties": {
+        "artifacts": {
+          "type": "array",
+          "maxItems": 20,
+          "items": { "$ref": "#/$defs/artifactFinalState" }
+        },
+        "recovery": {
+          "type": "array",
+          "maxItems": 20,
+          "items": { "$ref": "#/$defs/recoveryFinalState" }
+        },
+        "pendingPreviewRenders": { "const": 0 },
+        "previewDeliveries": {
+          "type": "array",
+          "maxItems": 20,
+          "items": { "type": "string", "pattern": "^[a-f0-9]{64}(?![\\s\\S])" }
+        }
+      }
+    }
+  }
+}