@clowder-ai/plugin-contract 0.1.0-beta.1

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

@@ -0,0 +1,370 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://clowder-ai.dev/schemas/behavior-fixture/v0.1",
+  "title": "Clowder AI Contract Behavior Fixture",
+  "type": "object",
+  "properties": {
+    "_meta": { "$ref": "#/$defs/FixtureMetadata" },
+    "cases": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/BehaviorCase" },
+      "minItems": 1
+    }
+  },
+  "required": ["_meta", "cases"],
+  "additionalProperties": false,
+  "$defs": {
+    "FixtureMetadata": {
+      "type": "object",
+      "properties": {
+        "executor": { "const": "loopback" },
+        "domain": { "const": "messaging" },
+        "contractVersion": {
+          "type": "string",
+          "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-]*))*)?$"
+        },
+        "source": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 }
+      },
+      "required": ["executor", "domain", "contractVersion", "source", "description"],
+      "additionalProperties": false
+    },
+    "FixtureCaller": {
+      "type": "object",
+      "properties": {
+        "pluginInstanceId": { "type": "string", "minLength": 1 }
+      },
+      "required": ["pluginInstanceId"],
+      "additionalProperties": false
+    },
+    "FixtureHandle": {
+      "type": "object",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["thread_handle", "connector_binding", "message_handle", "subscription"]
+        },
+        "token": { "type": "string", "minLength": 1 },
+        "ownerPluginInstanceId": { "type": "string", "minLength": 1 },
+        "threadId": { "type": "string", "minLength": 1 },
+        "messageId": { "type": "string", "minLength": 1 },
+        "connectorId": { "type": "string", "minLength": 1 },
+        "subscriptionId": { "type": "string", "minLength": 1 }
+      },
+      "required": ["kind", "token", "ownerPluginInstanceId"],
+      "additionalProperties": false
+    },
+    "FixtureSetup": {
+      "type": "object",
+      "properties": {
+        "caller": { "$ref": "#/$defs/FixtureCaller" },
+        "grants": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/CapabilityName" },
+          "uniqueItems": true
+        },
+        "handles": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/FixtureHandle" }
+        },
+        "state": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      },
+      "required": ["caller", "grants", "handles", "state"],
+      "additionalProperties": false
+    },
+    "FixtureOperation": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "operation": { "const": "send" },
+            "input": { "$ref": "#/$defs/SendOperationInput" }
+          },
+          "required": ["operation", "input"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation": { "const": "appendElements" },
+            "input": { "$ref": "#/$defs/AppendOperationInput" }
+          },
+          "required": ["operation", "input"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation": { "const": "subscribe" },
+            "input": { "$ref": "#/$defs/SubscribeOperationInput" }
+          },
+          "required": ["operation", "input"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation": { "const": "read" },
+            "input": { "$ref": "#/$defs/ReadOperationInput" }
+          },
+          "required": ["operation", "input"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation": { "const": "ack" },
+            "input": { "$ref": "#/$defs/AckOperationInput" }
+          },
+          "required": ["operation", "input"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation": { "const": "snapshot" },
+            "input": { "$ref": "#/$defs/SnapshotOperationInput" }
+          },
+          "required": ["operation", "input"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation": { "const": "applyGrantPreset" },
+            "input": { "$ref": "#/$defs/GrantPresetInput" }
+          },
+          "required": ["operation", "input"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation": { "const": "revokeGrant" },
+            "input": { "$ref": "#/$defs/RevokeGrantInput" }
+          },
+          "required": ["operation", "input"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation": { "const": "deliverOnMessage" },
+            "input": { "$ref": "#/$defs/OnMessageDeliveryInput" }
+          },
+          "required": ["operation", "input"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation": { "const": "checkPermissionMatrix" },
+            "input": { "$ref": "#/$defs/PermissionMatrixInput" }
+          },
+          "required": ["operation", "input"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "operation": { "const": "deleteReplayEvents" },
+            "input": { "$ref": "#/$defs/DeleteReplayEventsInput" }
+          },
+          "required": ["operation", "input"],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "SendOperationInput": {
+      "type": "object",
+      "properties": {
+        "address": { "type": "object" },
+        "idempotencyKey": { "type": "string", "minLength": 1 },
+        "payload": { "type": "object" }
+      },
+      "required": ["address", "idempotencyKey", "payload"],
+      "additionalProperties": true
+    },
+    "AppendOperationInput": {
+      "type": "object",
+      "properties": {
+        "handle": { "type": "object" },
+        "operationId": { "type": "string", "minLength": 1 },
+        "elements": { "type": "array", "minItems": 1 }
+      },
+      "required": ["handle", "operationId", "elements"],
+      "additionalProperties": true
+    },
+    "SubscribeOperationInput": {
+      "type": "object",
+      "properties": {
+        "handleId": { "type": "string", "minLength": 1 }
+      },
+      "required": ["handleId"],
+      "additionalProperties": false
+    },
+    "ReadOperationInput": {
+      "type": "object",
+      "properties": {
+        "subscriptionId": { "type": "string", "minLength": 1 },
+        "limit": { "type": "integer", "minimum": 1, "maximum": 32 }
+      },
+      "required": ["subscriptionId"],
+      "additionalProperties": false
+    },
+    "AckOperationInput": {
+      "type": "object",
+      "properties": {
+        "subscriptionId": { "type": "string", "minLength": 1 },
+        "ackToken": { "type": "string", "minLength": 1 }
+      },
+      "required": ["subscriptionId", "ackToken"],
+      "additionalProperties": false
+    },
+    "SnapshotOperationInput": {
+      "type": "object",
+      "properties": {
+        "subscriptionId": { "type": "string", "minLength": 1 }
+      },
+      "required": ["subscriptionId"],
+      "additionalProperties": false
+    },
+    "CapabilityName": {
+      "$ref": "https://clowder-ai.dev/schemas/manifest/v0.1#/$defs/Capability"
+    },
+    "GrantPresetInput": {
+      "type": "object",
+      "properties": {
+        "presetKind": { "const": "first_party" },
+        "capabilities": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/CapabilityName" },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      },
+      "required": ["presetKind", "capabilities"],
+      "additionalProperties": false
+    },
+    "RevokeGrantInput": {
+      "type": "object",
+      "properties": {
+        "capability": { "$ref": "#/$defs/CapabilityName" }
+      },
+      "required": ["capability"],
+      "additionalProperties": false
+    },
+    "OnMessageDeliveryInput": {
+      "type": "object",
+      "properties": {
+        "threadHandle": { "type": "string", "minLength": 1 },
+        "envelope": { "type": "object" }
+      },
+      "required": ["threadHandle", "envelope"],
+      "additionalProperties": false
+    },
+    "PermissionMatrixEntry": {
+      "type": "object",
+      "properties": {
+        "capability": { "$ref": "#/$defs/CapabilityName" },
+        "layer": { "type": "string", "enum": ["L0", "L1", "L2"] },
+        "firstPartyPreset": { "type": "boolean" }
+      },
+      "required": ["capability", "layer", "firstPartyPreset"],
+      "additionalProperties": false
+    },
+    "PermissionMatrixInput": {
+      "type": "object",
+      "properties": {
+        "entries": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/PermissionMatrixEntry" },
+          "minItems": 17,
+          "maxItems": 17
+        }
+      },
+      "required": ["entries"],
+      "additionalProperties": false
+    },
+    "DeleteReplayEventsInput": {
+      "type": "object",
+      "properties": {
+        "subscriptionId": { "type": "string", "minLength": 1 },
+        "throughSequence": { "type": "integer", "minimum": 0 }
+      },
+      "required": ["subscriptionId", "throughSequence"],
+      "additionalProperties": false
+    },
+    "MessagingErrorCode": {
+      "type": "string",
+      "enum": ["VALIDATION", "PERMISSION", "NOT_FOUND", "CONFLICT", "RETRYABLE_INFLIGHT", "STALE_CURSOR"]
+    },
+    "SideEffectAssertion": {
+      "type": "object",
+      "properties": {
+        "target": {
+          "type": "string",
+          "enum": ["messages", "output_events", "idempotency_ledger", "subscription", "snapshot", "reply_preview", "provenance", "grant_state", "permission_matrix", "replay_events"]
+        },
+        "assertion": {
+          "type": "string",
+          "enum": ["unchanged", "none", "state_equals", "round_trip", "matches"]
+        },
+        "value": true
+      },
+      "required": ["target", "assertion"],
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "assertion": { "enum": ["state_equals", "round_trip", "matches"] }
+            },
+            "required": ["assertion"]
+          },
+          "then": { "required": ["value"] },
+          "else": { "not": { "required": ["value"] } }
+        }
+      ]
+    },
+    "ExpectedVerdict": {
+      "type": "object",
+      "properties": {
+        "status": { "type": "string", "enum": ["success", "error"] },
+        "errorCode": { "$ref": "#/$defs/MessagingErrorCode" },
+        "sideEffects": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/SideEffectAssertion" },
+          "minItems": 1
+        }
+      },
+      "required": ["status", "sideEffects"],
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": { "status": { "const": "error" } },
+            "required": ["status"]
+          },
+          "then": { "required": ["errorCode"] },
+          "else": { "not": { "required": ["errorCode"] } }
+        }
+      ]
+    },
+    "BehaviorCase": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+        "invariant": { "type": "string", "minLength": 1 },
+        "given": { "$ref": "#/$defs/FixtureSetup" },
+        "when": { "$ref": "#/$defs/FixtureOperation" },
+        "expect": { "$ref": "#/$defs/ExpectedVerdict" }
+      },
+      "required": ["id", "invariant", "given", "when", "expect"],
+      "additionalProperties": false
+    }
+  }
+}

package/src/schemas/manifest.schema.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://clowder-ai.dev/schemas/manifest/v0.1",
+  "title": "Clowder AI Plugin Manifest (v0.1)",
+  "description": "Machine-readable truth source for plugin manifest (§3.4/§3.5). v0.1 covers core manifest + features + data classification. Signals/events (C-2) and schedule/state (C-3) are schema deltas in future contract versions.",
+  "x-clowder-capability-layers": {
+    "L0": ["plugin.config.read", "plugin.state.get", "plugin.state.set"],
+    "L1": ["messaging.send", "schedule.register", "events.publish", "messaging.appendElements"],
+    "L2": ["onMessage", "message.event.subscribe", "secret.read", "thread.listMetadata", "thread.readContent", "memory.query", "memory.append", "memory.retrieve", "windows.create", "whisper.extend"]
+  },
+  "x-clowder-data-class-strategies": {
+    "cache": ["lifecycle", "retained", "ask-on-uninstall"],
+    "ephemeral": ["lifecycle", "retained", "ask-on-uninstall"],
+    "user-authored": ["retained", "ask-on-uninstall"],
+    "derived-user-visible": ["retained", "ask-on-uninstall"],
+    "relationship": ["retained", "ask-on-uninstall"],
+    "interaction-history": ["retained", "ask-on-uninstall"]
+  },
+
+  "$defs": {
+    "SemVer": {
+      "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-]+)*)?$",
+      "description": "SemVer 2.0.0 including optional prerelease and build metadata."
+    },
+
+    "DataClass": {
+      "type": "string",
+      "enum": ["cache", "ephemeral", "user-authored", "derived-user-visible", "relationship", "interaction-history"]
+    },
+
+    "DataStrategy": {
+      "type": "string",
+      "enum": ["lifecycle", "retained", "ask-on-uninstall"]
+    },
+
+    "Capability": {
+      "type": "string",
+      "enum": [
+        "plugin.config.read",
+        "plugin.state.get",
+        "plugin.state.set",
+        "messaging.send",
+        "schedule.register",
+        "events.publish",
+        "messaging.appendElements",
+        "onMessage",
+        "message.event.subscribe",
+        "secret.read",
+        "thread.listMetadata",
+        "thread.readContent",
+        "memory.query",
+        "memory.append",
+        "memory.retrieve",
+        "windows.create",
+        "whisper.extend"
+      ]
+    },
+
+    "DataDeclaration": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "dataClass": { "$ref": "#/$defs/DataClass" },
+        "strategy": { "$ref": "#/$defs/DataStrategy" },
+        "schemaVersion": { "type": "string" }
+      },
+      "required": ["name", "dataClass", "strategy"],
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "dataClass": {
+                "enum": ["user-authored", "derived-user-visible", "relationship", "interaction-history"]
+              }
+            },
+            "required": ["dataClass"]
+          },
+          "then": {
+            "properties": {
+              "strategy": {
+                "enum": ["retained", "ask-on-uninstall"],
+                "description": "User-visible/relationship data MUST be retained or ask-on-uninstall. lifecycle is structurally forbidden (铁律 #5: user state defaults to persistent)."
+              }
+            }
+          }
+        }
+      ]
+    },
+
+    "ResourceReference": {
+      "type": "object",
+      "properties": {
+        "type": { "type": "string", "minLength": 1 },
+        "id": { "type": "string", "minLength": 1 }
+      },
+      "required": ["type", "id"],
+      "additionalProperties": false
+    },
+
+    "PluginFeature": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "resources": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ResourceReference" }
+        },
+        "capabilities": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Capability" },
+          "description": "@signed(G-0 2026-07-15) — capability vocabulary is contract-versioned (P15). Adding a new capability = new contract version. Unknown strings are structurally rejected at schema level; authorization is a separate host runtime layer. Lifecycle callbacks are protocol-intrinsic baseline behavior, so they are not grantable or revocable capability IDs."
+        }
+      },
+      "required": ["id", "name", "resources", "capabilities"],
+      "additionalProperties": false
+    },
+
+    "RuntimeTransport": {
+      "type": "string",
+      "enum": ["stdio", "ipc", "builtin"]
+    },
+
+    "ExternalRuntimeTransport": {
+      "type": "string",
+      "enum": ["stdio", "ipc"]
+    },
+
+    "ExternalRuntimeDeclaration": {
+      "type": "object",
+      "properties": {
+        "transport": { "$ref": "#/$defs/ExternalRuntimeTransport" },
+        "entrypoint": { "type": "string", "minLength": 1 }
+      },
+      "required": ["transport", "entrypoint"],
+      "additionalProperties": false
+    },
+
+    "BuiltinRuntimeDeclaration": {
+      "type": "object",
+      "properties": {
+        "transport": { "const": "builtin" },
+        "entrypoint": { "type": "string", "minLength": 1 }
+      },
+      "required": ["transport"],
+      "additionalProperties": false
+    },
+
+    "RuntimeDeclaration": {
+      "oneOf": [
+        { "$ref": "#/$defs/ExternalRuntimeDeclaration" },
+        { "$ref": "#/$defs/BuiltinRuntimeDeclaration" }
+      ]
+    }
+  },
+
+  "type": "object",
+  "properties": {
+    "pluginId": { "type": "string", "minLength": 1 },
+    "version": {
+      "$ref": "#/$defs/SemVer",
+      "description": "Plugin version — must be valid semver (§9: numeric prerelease identifiers MUST NOT have leading zeroes)."
+    },
+    "contractVersion": {
+      "$ref": "#/$defs/SemVer",
+      "description": "Must be an exact published semver version — no ranges, wildcards, or operator prefixes (five-step freeze: pin exact version). §9: numeric prerelease identifiers MUST NOT have leading zeroes."
+    },
+    "name": { "type": "string", "minLength": 1 },
+    "description": { "type": "string" },
+    "features": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/PluginFeature" },
+      "minItems": 1
+    },
+    "data": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/DataDeclaration" }
+    },
+    "runtime": { "$ref": "#/$defs/RuntimeDeclaration" }
+  },
+  "required": ["pluginId", "version", "contractVersion", "name", "features", "runtime"],
+  "additionalProperties": false
+}