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

package/fixtures/manifest/valid/minimal-builtin.json

@@ -0,0 +1,17 @@
+{
+  "pluginId": "dev.clowder.fixture.minimal",
+  "version": "0.1.0",
+  "contractVersion": "0.1.0",
+  "name": "Minimal fixture plugin",
+  "features": [
+    {
+      "id": "echo",
+      "name": "Echo",
+      "resources": [],
+      "capabilities": []
+    }
+  ],
+  "runtime": {
+    "transport": "builtin"
+  }
+}

package/fixtures/manifest/valid/protocol-intrinsic-lifecycle.json

@@ -0,0 +1,18 @@
+{
+  "pluginId": "dev.clowder.fixture.protocol-lifecycle",
+  "version": "0.1.0",
+  "contractVersion": "0.1.0",
+  "name": "Protocol-intrinsic lifecycle fixture",
+  "description": "Lifecycle callbacks remain available as protocol baseline behavior without a grantable capability ID.",
+  "features": [
+    {
+      "id": "lifecycle-baseline",
+      "name": "Lifecycle baseline",
+      "resources": [],
+      "capabilities": []
+    }
+  ],
+  "runtime": {
+    "transport": "builtin"
+  }
+}

package/fixtures/manifest/valid/semver-build-metadata.json

@@ -0,0 +1,17 @@
+{
+  "pluginId": "dev.clowder.fixture.semver-build",
+  "version": "1.2.3+build.7",
+  "contractVersion": "0.1.0-candidate.1+sha.359d56e",
+  "name": "SemVer build metadata fixture",
+  "features": [
+    {
+      "id": "echo",
+      "name": "Echo",
+      "resources": [],
+      "capabilities": []
+    }
+  ],
+  "runtime": {
+    "transport": "builtin"
+  }
+}

package/fixtures/manifest/valid/stdio-entrypoint.json

@@ -0,0 +1,18 @@
+{
+  "pluginId": "dev.clowder.fixture.stdio",
+  "version": "0.1.0",
+  "contractVersion": "0.1.0",
+  "name": "Stdio fixture plugin",
+  "features": [
+    {
+      "id": "echo",
+      "name": "Echo",
+      "resources": [],
+      "capabilities": []
+    }
+  ],
+  "runtime": {
+    "transport": "stdio",
+    "entrypoint": "dist/plugin.js"
+  }
+}

package/fixtures/messaging/invalid/non-rfc3339-occurred-at.json

@@ -0,0 +1,34 @@
+{
+  "_meta": {
+    "schemaRef": "MessageEnvelope"
+  },
+  "messageId": "message-1",
+  "revision": 1,
+  "threadId": "thread-1",
+  "actor": {
+    "kind": "plugin",
+    "id": "fixture-plugin"
+  },
+  "audience": {
+    "kind": "public"
+  },
+  "occurredAt": "not-a-date",
+  "payload": {
+    "provenance": {
+      "origin": {
+        "kind": "plugin",
+        "instanceId": "fixture-plugin-instance"
+      },
+      "epistemicStatus": "inference"
+    },
+    "elements": [
+      {
+        "elementId": "text-1",
+        "kind": "text",
+        "payload": {
+          "text": "Must be rejected"
+        }
+      }
+    ]
+  }
+}

package/fixtures/messaging/invalid/non-utc-occurred-at.json

@@ -0,0 +1,34 @@
+{
+  "_meta": {
+    "schemaRef": "MessageEnvelope"
+  },
+  "messageId": "message-1",
+  "revision": 1,
+  "threadId": "thread-1",
+  "actor": {
+    "kind": "plugin",
+    "id": "fixture-plugin"
+  },
+  "audience": {
+    "kind": "public"
+  },
+  "occurredAt": "2026-07-15T10:42:00+08:00",
+  "payload": {
+    "provenance": {
+      "origin": {
+        "kind": "plugin",
+        "instanceId": "fixture-plugin-instance"
+      },
+      "epistemicStatus": "inference"
+    },
+    "elements": [
+      {
+        "elementId": "text-1",
+        "kind": "text",
+        "payload": {
+          "text": "UTC must be emitted with Z"
+        }
+      }
+    ]
+  }
+}

package/fixtures/messaging/invalid/raw-message-id-append.json

@@ -0,0 +1,16 @@
+{
+  "_meta": {
+    "schemaRef": "AppendElementsRequest"
+  },
+  "messageId": "raw-message-id",
+  "operationId": "append-operation-raw-id",
+  "elements": [
+    {
+      "elementId": "summary-1",
+      "kind": "text",
+      "payload": {
+        "text": "Must be rejected"
+      }
+    }
+  ]
+}

package/fixtures/messaging/invalid/raw-thread-id.json

@@ -0,0 +1,28 @@
+{
+  "_meta": {
+    "schemaRef": "MessageDraft"
+  },
+  "address": {
+    "kind": "thread",
+    "threadId": "raw-thread-id"
+  },
+  "idempotencyKey": "fixture-send-raw-thread",
+  "payload": {
+    "provenance": {
+      "origin": {
+        "kind": "plugin",
+        "instanceId": "fixture-plugin-instance"
+      },
+      "epistemicStatus": "inference"
+    },
+    "elements": [
+      {
+        "elementId": "text-1",
+        "kind": "text",
+        "payload": {
+          "text": "Must be rejected"
+        }
+      }
+    ]
+  }
+}

package/fixtures/messaging/invalid/stale-read-with-ack-token.json

@@ -0,0 +1,8 @@
+{
+  "_meta": {
+    "schemaRef": "SubscriptionReadResponse"
+  },
+  "events": [],
+  "ackToken": "must-be-null-while-stale",
+  "stale": true
+}

package/fixtures/messaging/invalid/system-draft-audience.json

@@ -0,0 +1,31 @@
+{
+  "_meta": {
+    "schemaRef": "MessageDraft"
+  },
+  "address": {
+    "kind": "thread_handle",
+    "handle": "opaque-host-signed-thread-handle"
+  },
+  "draftAudience": {
+    "kind": "system"
+  },
+  "idempotencyKey": "fixture-send-system-audience",
+  "payload": {
+    "provenance": {
+      "origin": {
+        "kind": "plugin",
+        "instanceId": "fixture-plugin-instance"
+      },
+      "epistemicStatus": "inference"
+    },
+    "elements": [
+      {
+        "elementId": "text-1",
+        "kind": "text",
+        "payload": {
+          "text": "Must be rejected"
+        }
+      }
+    ]
+  }
+}

package/fixtures/messaging/invalid/text-payload-missing-text.json

@@ -0,0 +1,10 @@
+{
+  "_meta": {
+    "schemaRef": "MessageElement"
+  },
+  "elementId": "text-1",
+  "kind": "text",
+  "payload": {
+    "html": "text payloads must carry text"
+  }
+}

package/fixtures/messaging/invalid/untyped-root-document.json

@@ -0,0 +1,3 @@
+{
+  "unexpected": "the messaging root must reject arbitrary JSON"
+}

package/fixtures/messaging/valid/append-elements-with-handle.json

@@ -0,0 +1,21 @@
+{
+  "_meta": {
+    "schemaRef": "AppendElementsRequest"
+  },
+  "handle": {
+    "kind": "message",
+    "token": "opaque-host-signed-message-handle"
+  },
+  "operationId": "append-operation-001",
+  "baseRevision": 1,
+  "elements": [
+    {
+      "elementId": "summary-1",
+      "kind": "text",
+      "payload": {
+        "text": "Derived summary"
+      },
+      "derivedFromElementId": "text-1"
+    }
+  ]
+}

package/fixtures/messaging/valid/message-draft.json

@@ -0,0 +1,28 @@
+{
+  "_meta": {
+    "schemaRef": "MessageDraft"
+  },
+  "address": {
+    "kind": "thread_handle",
+    "handle": "opaque-host-signed-thread-handle"
+  },
+  "idempotencyKey": "fixture-send-001",
+  "payload": {
+    "provenance": {
+      "origin": {
+        "kind": "plugin",
+        "instanceId": "fixture-plugin-instance"
+      },
+      "epistemicStatus": "inference"
+    },
+    "elements": [
+      {
+        "elementId": "text-1",
+        "kind": "text",
+        "payload": {
+          "text": "Fixture message"
+        }
+      }
+    ]
+  }
+}

package/fixtures/messaging/valid/root-message-draft.json

@@ -0,0 +1,25 @@
+{
+  "address": {
+    "kind": "thread_handle",
+    "handle": "opaque-host-signed-thread-handle"
+  },
+  "idempotencyKey": "fixture-root-send-001",
+  "payload": {
+    "provenance": {
+      "origin": {
+        "kind": "plugin",
+        "instanceId": "fixture-plugin-instance"
+      },
+      "epistemicStatus": "inference"
+    },
+    "elements": [
+      {
+        "elementId": "text-1",
+        "kind": "text",
+        "payload": {
+          "text": "Root schema fixture"
+        }
+      }
+    ]
+  }
+}

package/fixtures/messaging/valid/subscription-delivery.json

@@ -0,0 +1,45 @@
+{
+  "_meta": {
+    "schemaRef": "SubscriptionReadResponse"
+  },
+  "events": [
+    {
+      "eventId": "ev_pub_message-1_1",
+      "sequence": 1,
+      "type": "message.publish",
+      "envelope": {
+          "messageId": "message-1",
+          "revision": 1,
+          "threadId": "thread-1",
+          "actor": {
+            "kind": "plugin",
+            "id": "fixture-plugin"
+          },
+          "audience": {
+            "kind": "public"
+          },
+          "occurredAt": "2026-07-15T02:42:00Z",
+          "payload": {
+            "provenance": {
+              "origin": {
+                "kind": "plugin",
+                "instanceId": "fixture-plugin-instance"
+              },
+              "epistemicStatus": "inference"
+            },
+            "elements": [
+              {
+                "elementId": "text-1",
+                "kind": "text",
+                "payload": {
+                  "text": "Fixture message"
+                }
+              }
+            ]
+          }
+      }
+    }
+  ],
+  "ackToken": "opaque-subscription-local-cursor",
+  "stale": false
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@clowder-ai/plugin-contract",
+  "version": "0.1.0-beta.1",
+  "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",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schemas/messaging": "./src/schemas/messaging.schema.json",
+    "./schemas/manifest": "./src/schemas/manifest.schema.json",
+    "./schemas/behavior-fixture": "./src/schemas/behavior-fixture.schema.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src/schemas",
+    "fixtures"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "generate": "node --import tsx src/codegen/generate-contract.ts",
+    "generate:check": "node --import tsx src/codegen/generate-contract.ts --check",
+    "build": "pnpm clean && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test src/**/*.test.ts",
+    "conformance": "node --import tsx src/conformance/runner.ts",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepack": "pnpm build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "ajv": "^8.17.0",
+    "ajv-formats": "^3.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "clowder-ai",
+    "plugin",
+    "contract",
+    "schema"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zts212653/clowder-ai-plugins.git",
+    "directory": "packages/plugin-contract"
+  }
+}