@clowder-ai/plugin-contract 0.1.0-beta.11 → 0.1.0-beta.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clowder-ai/plugin-contract",
-  "version": "0.1.0-beta.11",
+  "version": "0.1.0-beta.13",
   "private": false,
   "description": "Clowder AI plugin contract — the single machine-readable truth source for plugin schema, types, capability table, and conformance fixtures (P15)",
   "license": "MIT",
@@ -16,6 +16,8 @@
     },
     "./schemas/messaging": "./src/schemas/messaging.schema.json",
     "./schemas/manifest": "./src/schemas/manifest.schema.json",
+    "./schemas/catalog": "./src/schemas/catalog.schema.json",
+    "./schemas/plugin-metadata": "./src/schemas/plugin-metadata.schema.json",
     "./schemas/signals": "./src/schemas/signal.schema.json",
     "./schemas/physical-limb": "./src/schemas/physical-limb.schema.json",
     "./schemas/behavior-fixture": "./src/schemas/behavior-fixture.schema.json",

package/src/schemas/behavior-fixture.schema.json

@@ -178,6 +178,78 @@
         }
       ]
     },
+    "PluginToHostMethod": {
+      "type": "string",
+      "enum": [
+        "messaging.send",
+        "messaging.appendElements",
+        "messaging.subscribe",
+        "messaging.read",
+        "messaging.ack",
+        "messaging.snapshot"
+      ]
+    },
+    "BehaviorExpectationOracle": {
+      "type": "object",
+      "properties": {
+        "kind": { "const": "behavior-expectation" }
+      },
+      "required": ["kind"],
+      "additionalProperties": false
+    },
+    "JsonRpcAdmissionOracle": {
+      "type": "object",
+      "properties": {
+        "kind": { "const": "json-rpc-error" },
+        "code": { "const": -32602 },
+        "sideEffects": { "const": "behavior-expectation" }
+      },
+      "required": ["kind", "code", "sideEffects"],
+      "additionalProperties": false
+    },
+    "BehaviorExecution": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "plane": { "const": "plugin-to-host-wire" },
+            "method": { "$ref": "#/$defs/PluginToHostMethod" },
+            "verdictOracle": { "$ref": "#/$defs/BehaviorExpectationOracle" }
+          },
+          "required": ["plane", "method", "verdictOracle"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "plane": { "const": "wire-admission" },
+            "method": { "$ref": "#/$defs/PluginToHostMethod" },
+            "verdictOracle": { "$ref": "#/$defs/JsonRpcAdmissionOracle" }
+          },
+          "required": ["plane", "method", "verdictOracle"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "plane": { "const": "host-to-plugin-delivery" },
+            "method": { "const": "host.messaging.deliver" },
+            "verdictOracle": { "$ref": "#/$defs/BehaviorExpectationOracle" }
+          },
+          "required": ["plane", "method", "verdictOracle"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "plane": { "const": "host-control" },
+            "verdictOracle": { "$ref": "#/$defs/BehaviorExpectationOracle" }
+          },
+          "required": ["plane", "verdictOracle"],
+          "additionalProperties": false
+        }
+      ]
+    },
     "SendOperationInput": {
       "type": "object",
       "properties": {
@@ -359,12 +431,200 @@
       "properties": {
         "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
         "invariant": { "type": "string", "minLength": 1 },
+        "execution": { "$ref": "#/$defs/BehaviorExecution" },
         "given": { "$ref": "#/$defs/FixtureSetup" },
         "when": { "$ref": "#/$defs/FixtureOperation" },
         "expect": { "$ref": "#/$defs/ExpectedVerdict" }
       },
-      "required": ["id", "invariant", "given", "when", "expect"],
-      "additionalProperties": false
+      "required": ["id", "invariant", "execution", "given", "when", "expect"],
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "when": {
+                "properties": { "operation": { "const": "send" } },
+                "required": ["operation"]
+              }
+            },
+            "required": ["when"]
+          },
+          "then": {
+            "properties": {
+              "execution": {
+                "type": "object",
+                "properties": {
+                  "plane": { "enum": ["plugin-to-host-wire", "wire-admission"] },
+                  "method": { "const": "messaging.send" }
+                },
+                "required": ["plane", "method"]
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "when": {
+                "properties": { "operation": { "const": "appendElements" } },
+                "required": ["operation"]
+              }
+            },
+            "required": ["when"]
+          },
+          "then": {
+            "properties": {
+              "execution": {
+                "type": "object",
+                "properties": {
+                  "plane": { "enum": ["plugin-to-host-wire", "wire-admission"] },
+                  "method": { "const": "messaging.appendElements" }
+                },
+                "required": ["plane", "method"]
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "when": {
+                "properties": { "operation": { "const": "subscribe" } },
+                "required": ["operation"]
+              }
+            },
+            "required": ["when"]
+          },
+          "then": {
+            "properties": {
+              "execution": {
+                "type": "object",
+                "properties": {
+                  "plane": { "enum": ["plugin-to-host-wire", "wire-admission"] },
+                  "method": { "const": "messaging.subscribe" }
+                },
+                "required": ["plane", "method"]
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "when": {
+                "properties": { "operation": { "const": "read" } },
+                "required": ["operation"]
+              }
+            },
+            "required": ["when"]
+          },
+          "then": {
+            "properties": {
+              "execution": {
+                "type": "object",
+                "properties": {
+                  "plane": { "enum": ["plugin-to-host-wire", "wire-admission"] },
+                  "method": { "const": "messaging.read" }
+                },
+                "required": ["plane", "method"]
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "when": {
+                "properties": { "operation": { "const": "ack" } },
+                "required": ["operation"]
+              }
+            },
+            "required": ["when"]
+          },
+          "then": {
+            "properties": {
+              "execution": {
+                "type": "object",
+                "properties": {
+                  "plane": { "enum": ["plugin-to-host-wire", "wire-admission"] },
+                  "method": { "const": "messaging.ack" }
+                },
+                "required": ["plane", "method"]
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "when": {
+                "properties": { "operation": { "const": "snapshot" } },
+                "required": ["operation"]
+              }
+            },
+            "required": ["when"]
+          },
+          "then": {
+            "properties": {
+              "execution": {
+                "type": "object",
+                "properties": {
+                  "plane": { "enum": ["plugin-to-host-wire", "wire-admission"] },
+                  "method": { "const": "messaging.snapshot" }
+                },
+                "required": ["plane", "method"]
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "when": {
+                "properties": { "operation": { "const": "deliverOnMessage" } },
+                "required": ["operation"]
+              }
+            },
+            "required": ["when"]
+          },
+          "then": {
+            "properties": {
+              "execution": {
+                "type": "object",
+                "properties": {
+                  "plane": { "const": "host-to-plugin-delivery" },
+                  "method": { "const": "host.messaging.deliver" }
+                },
+                "required": ["plane", "method"]
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "when": {
+                "properties": {
+                  "operation": {
+                    "enum": ["applyGrantPreset", "revokeGrant", "checkPermissionMatrix", "deleteReplayEvents"]
+                  }
+                },
+                "required": ["operation"]
+              }
+            },
+            "required": ["when"]
+          },
+          "then": {
+            "properties": {
+              "execution": {
+                "type": "object",
+                "properties": { "plane": { "const": "host-control" } },
+                "required": ["plane"]
+              }
+            }
+          }
+        }
+      ]
     }
   }
 }

package/src/schemas/catalog.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://clowder-ai.dev/schemas/catalog/v1",
+  "title": "Clowder AI Plugin Catalog (v1)",
+  "description": "Repository-owned immutable discovery coordinates. Installed/configured/enabled/live state is deliberately absent because it belongs to the local Host inventory.",
+  "$defs": {
+    "CatalogSemVer": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(-(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(\\.(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$"
+    },
+    "CatalogPublisher": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 }
+      },
+      "required": ["id", "name"],
+      "additionalProperties": false
+    },
+    "ArtifactProvenance": {
+      "type": "object",
+      "properties": {
+        "repository": { "type": "string", "format": "uri", "pattern": "^https://" },
+        "sourceDirectory": { "type": "string", "pattern": "^packages/[a-z0-9-]+$" }
+      },
+      "required": ["repository", "sourceDirectory"],
+      "additionalProperties": false
+    },
+    "NpmArtifact": {
+      "type": "object",
+      "properties": {
+        "kind": { "const": "npm" },
+        "packageName": {
+          "type": "string",
+          "pattern": "^@[a-z0-9][a-z0-9._-]*/[a-z0-9][a-z0-9._-]*$"
+        },
+        "version": { "$ref": "#/$defs/CatalogSemVer" },
+        "tarballUrl": { "type": "string", "format": "uri", "pattern": "^https://registry\\.npmjs\\.org/" },
+        "integrity": { "type": "string", "pattern": "^sha512-[A-Za-z0-9+/]{86}==$" },
+        "shasum": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+        "provenance": { "$ref": "#/$defs/ArtifactProvenance" }
+      },
+      "required": ["kind", "packageName", "version", "tarballUrl", "integrity", "shasum", "provenance"],
+      "additionalProperties": false
+    },
+    "CatalogPluginVersion": {
+      "type": "object",
+      "properties": {
+        "version": { "$ref": "#/$defs/CatalogSemVer" },
+        "contractVersion": { "$ref": "#/$defs/CatalogSemVer" },
+        "manifestPath": { "const": "plugin.yaml" },
+        "artifact": { "$ref": "#/$defs/NpmArtifact" }
+      },
+      "required": ["version", "contractVersion", "manifestPath", "artifact"],
+      "additionalProperties": false
+    },
+    "CatalogPluginEntry": {
+      "type": "object",
+      "properties": {
+        "pluginId": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "description": { "$ref": "https://clowder-ai.dev/schemas/plugin-metadata/v1#/$defs/LocalizedDescription" },
+        "icon": { "$ref": "https://clowder-ai.dev/schemas/plugin-metadata/v1#/$defs/PluginIcon" },
+        "publisher": { "$ref": "#/$defs/CatalogPublisher" },
+        "keywords": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "versions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/CatalogPluginVersion" },
+          "minItems": 1
+        }
+      },
+      "required": ["pluginId", "name", "description", "icon", "publisher", "versions"],
+      "additionalProperties": false
+    }
+  },
+  "type": "object",
+  "properties": {
+    "schemaVersion": { "const": "1" },
+    "plugins": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/CatalogPluginEntry" }
+    }
+  },
+  "required": ["schemaVersion", "plugins"],
+  "additionalProperties": false
+}