@clowder-ai/plugin-contract 0.1.0-beta.9 → 0.3.0

package/fixtures/behavior/messaging/adversarial-invariants.json

@@ -10,9 +10,13 @@
     {
       "id": "raw-thread-id-rejection",
       "invariant": "Plugins cannot address threads by raw threadId.",
+      "execution": {
+        "plane": "wire-admission",
+        "method": "messaging.send",
+        "verdictOracle": { "kind": "json-rpc-error", "code": -32602, "sideEffects": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "plugin-a" },
-        "grants": ["messaging.send"],
         "handles": {},
         "state": { "threads": [{ "threadId": "thread-1" }] }
       },
@@ -40,9 +44,13 @@
     {
       "id": "system-audience-dual-rejection",
       "invariant": "Drafts cannot express the host-only system audience.",
+      "execution": {
+        "plane": "wire-admission",
+        "method": "messaging.send",
+        "verdictOracle": { "kind": "json-rpc-error", "code": -32602, "sideEffects": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "plugin-a" },
-        "grants": ["messaging.send"],
         "handles": {
           "target": { "kind": "thread_handle", "token": "thread-handle-a", "ownerPluginInstanceId": "plugin-a", "threadId": "thread-1" }
         },
@@ -73,9 +81,13 @@
     {
       "id": "cross-instance-handle-rejection",
       "invariant": "A message handle issued to one plugin instance cannot authorize another.",
+      "execution": {
+        "plane": "plugin-to-host-wire",
+        "method": "messaging.appendElements",
+        "verdictOracle": { "kind": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "plugin-a" },
-        "grants": ["messaging.appendElements"],
         "handles": {
           "foreignMessage": { "kind": "message_handle", "token": "message-handle-b", "ownerPluginInstanceId": "plugin-b", "threadId": "thread-1", "messageId": "message-1" }
         },
@@ -103,9 +115,13 @@
     {
       "id": "origin-forgery-rejection",
       "invariant": "A thread-handle send may only declare the caller's own plugin origin.",
+      "execution": {
+        "plane": "plugin-to-host-wire",
+        "method": "messaging.send",
+        "verdictOracle": { "kind": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "plugin-a" },
-        "grants": ["messaging.send"],
         "handles": {
           "target": { "kind": "thread_handle", "token": "thread-handle-a", "ownerPluginInstanceId": "plugin-a", "threadId": "thread-1" }
         },
@@ -135,9 +151,13 @@
     {
       "id": "base-revision-conflict-zero-change",
       "invariant": "A stale baseRevision produces CONFLICT and no mutation.",
+      "execution": {
+        "plane": "plugin-to-host-wire",
+        "method": "messaging.appendElements",
+        "verdictOracle": { "kind": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "plugin-a" },
-        "grants": ["messaging.appendElements"],
         "handles": {
           "message": { "kind": "message_handle", "token": "message-handle-a", "ownerPluginInstanceId": "plugin-a", "threadId": "thread-1", "messageId": "message-1" }
         },
@@ -165,9 +185,13 @@
     {
       "id": "stale-cursor-snapshot-roundtrip",
       "invariant": "A stale cursor reports stale and snapshot catch-up supplies an exact resume point.",
+      "execution": {
+        "plane": "plugin-to-host-wire",
+        "method": "messaging.read",
+        "verdictOracle": { "kind": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "plugin-a" },
-        "grants": ["message.event.subscribe"],
         "handles": {
           "subscription": { "kind": "subscription", "token": "subscription-token-a", "ownerPluginInstanceId": "plugin-a", "threadId": "thread-1", "subscriptionId": "subscription-a" }
         },
@@ -189,9 +213,13 @@
     {
       "id": "cross-subscription-ack-rejection",
       "invariant": "Ack tokens are subscription-local and cannot cross subscriptions.",
+      "execution": {
+        "plane": "plugin-to-host-wire",
+        "method": "messaging.ack",
+        "verdictOracle": { "kind": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "plugin-a" },
-        "grants": ["message.event.subscribe"],
         "handles": {
           "subscriptionA": { "kind": "subscription", "token": "ack-from-a", "ownerPluginInstanceId": "plugin-a", "threadId": "thread-1", "subscriptionId": "subscription-a" },
           "subscriptionB": { "kind": "subscription", "token": "subscription-token-b", "ownerPluginInstanceId": "plugin-a", "threadId": "thread-2", "subscriptionId": "subscription-b" }
@@ -214,9 +242,13 @@
     {
       "id": "reply-to-cross-thread-leakage",
       "invariant": "replyTo cannot reference a message from another thread.",
+      "execution": {
+        "plane": "plugin-to-host-wire",
+        "method": "messaging.send",
+        "verdictOracle": { "kind": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "plugin-a" },
-        "grants": ["messaging.send"],
         "handles": {
           "target": { "kind": "thread_handle", "token": "thread-handle-a", "ownerPluginInstanceId": "plugin-a", "threadId": "thread-1" }
         },
@@ -247,9 +279,13 @@
     {
       "id": "epistemic-status-upgrade-rejection",
       "invariant": "Derived content cannot claim a stronger epistemic status than its source.",
+      "execution": {
+        "plane": "plugin-to-host-wire",
+        "method": "messaging.appendElements",
+        "verdictOracle": { "kind": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "plugin-a" },
-        "grants": ["messaging.appendElements"],
         "handles": {
           "message": { "kind": "message_handle", "token": "message-handle-a", "ownerPluginInstanceId": "plugin-a", "threadId": "thread-1", "messageId": "message-1" }
         },
@@ -274,116 +310,18 @@
         ]
       }
     },
+
+
     {
-      "id": "preset-l2-rejected",
-      "invariant": "First-party presets are derived from L1 and cannot silently grant L2 capabilities.",
-      "given": {
-        "caller": { "pluginInstanceId": "first-party-plugin" },
-        "grants": ["messaging.send"],
-        "handles": {},
-        "state": { "grantState": { "presetCapabilities": ["messaging.send"] } }
-      },
-      "when": {
-        "operation": "applyGrantPreset",
-        "input": { "presetKind": "first_party", "capabilities": ["onMessage"] }
-      },
-      "expect": {
-        "status": "error",
-        "errorCode": "PERMISSION",
-        "sideEffects": [
-          { "target": "grant_state", "assertion": "unchanged" }
-        ]
-      }
-    },
-    {
-      "id": "preset-visible-revocable",
-      "invariant": "A first-party L1 preset remains visible and independently revocable.",
-      "given": {
-        "caller": { "pluginInstanceId": "first-party-plugin" },
-        "grants": ["messaging.send"],
-        "handles": {},
-        "state": { "grantState": { "messaging.send": { "visible": true, "granted": true } } }
-      },
-      "when": {
-        "operation": "revokeGrant",
-        "input": { "capability": "messaging.send" }
-      },
-      "expect": {
-        "status": "success",
-        "sideEffects": [
-          { "target": "grant_state", "assertion": "state_equals", "value": { "capability": "messaging.send", "visible": true, "granted": false } }
-        ]
-      }
-    },
-    {
-      "id": "whisper-target-beyond-default-empty-grant-rejected",
-      "invariant": "The default whisper target grant is empty; messaging.send alone cannot add a target.",
-      "given": {
-        "caller": { "pluginInstanceId": "plugin-a" },
-        "grants": ["messaging.send"],
-        "handles": {
-          "target": { "kind": "thread_handle", "token": "thread-handle-a", "ownerPluginInstanceId": "plugin-a", "threadId": "thread-1" }
-        },
-        "state": { "whisperGrantTargets": [] }
-      },
-      "when": {
-        "operation": "send",
-        "input": {
-          "address": { "kind": "thread_handle", "handle": "thread-handle-a" },
-          "draftAudience": { "kind": "whisper", "targets": ["cat-b"] },
-          "idempotencyKey": "whisper-without-target-grant-1",
-          "payload": {
-            "provenance": { "epistemicStatus": "inference" },
-            "elements": [{ "elementId": "text-1", "kind": "text", "payload": { "text": "blocked" } }]
-          }
-        }
-      },
-      "expect": {
-        "status": "error",
-        "errorCode": "PERMISSION",
-        "sideEffects": [
-          { "target": "messages", "assertion": "unchanged" },
-          { "target": "output_events", "assertion": "none" },
-          { "target": "idempotency_ledger", "assertion": "unchanged" }
-        ]
-      }
-    },
-    {
-      "id": "append-without-grant-rejected",
-      "invariant": "A valid message handle does not bypass the messaging.appendElements grant.",
-      "given": {
-        "caller": { "pluginInstanceId": "plugin-a" },
-        "grants": [],
-        "handles": {
-          "message": { "kind": "message_handle", "token": "message-handle-a", "ownerPluginInstanceId": "plugin-a", "threadId": "thread-1", "messageId": "message-1" }
-        },
-        "state": { "messages": [{ "messageId": "message-1", "threadId": "thread-1", "revision": 1 }] }
-      },
-      "when": {
-        "operation": "appendElements",
-        "input": {
-          "handle": { "kind": "message", "token": "message-handle-a" },
-          "operationId": "append-without-grant-1",
-          "baseRevision": 1,
-          "elements": [{ "elementId": "text-2", "kind": "text", "payload": { "text": "blocked" } }]
-        }
+      "id": "on-message-delivery",
+      "invariant": "A live instance receives its scoped message through the declared handler",
+      "execution": {
+        "plane": "host-to-plugin-delivery",
+        "method": "host.messaging.deliver",
+        "verdictOracle": { "kind": "behavior-expectation" }
       },
-      "expect": {
-        "status": "error",
-        "errorCode": "PERMISSION",
-        "sideEffects": [
-          { "target": "messages", "assertion": "unchanged" },
-          { "target": "output_events", "assertion": "none" },
-          { "target": "idempotency_ledger", "assertion": "unchanged" }
-        ]
-      }
-    },
-    {
-      "id": "denied-on-message-rejected",
-      "invariant": "The Host cannot deliver an onMessage envelope without an explicit scoped L2 grant.",
       "given": {
         "caller": { "pluginInstanceId": "plugin-a" },
-        "grants": [],
         "handles": {
           "target": { "kind": "thread_handle", "token": "thread-handle-a", "ownerPluginInstanceId": "plugin-a", "threadId": "thread-1" }
         },
@@ -397,60 +335,22 @@
         }
       },
       "expect": {
-        "status": "error",
-        "errorCode": "PERMISSION",
+        "status": "success",
         "sideEffects": [
           { "target": "messages", "assertion": "unchanged" },
           { "target": "output_events", "assertion": "none" }
         ]
       }
     },
-    {
-      "id": "permission-matrix-complete",
-      "invariant": "The loopback policy matrix covers every signed capability and presets only L1 for first-party plugins.",
-      "given": {
-        "caller": { "pluginInstanceId": "policy-auditor" },
-        "grants": [],
-        "handles": {},
-        "state": {}
-      },
-      "when": {
-        "operation": "checkPermissionMatrix",
-        "input": {
-          "entries": [
-            { "capability": "plugin.config.read", "layer": "L0", "firstPartyPreset": false },
-            { "capability": "plugin.state.get", "layer": "L0", "firstPartyPreset": false },
-            { "capability": "plugin.state.set", "layer": "L0", "firstPartyPreset": false },
-            { "capability": "messaging.send", "layer": "L1", "firstPartyPreset": true },
-            { "capability": "schedule.register", "layer": "L1", "firstPartyPreset": true },
-            { "capability": "events.publish", "layer": "L1", "firstPartyPreset": true },
-            { "capability": "messaging.appendElements", "layer": "L1", "firstPartyPreset": true },
-            { "capability": "onMessage", "layer": "L2", "firstPartyPreset": false },
-            { "capability": "message.event.subscribe", "layer": "L2", "firstPartyPreset": false },
-            { "capability": "secret.read", "layer": "L2", "firstPartyPreset": false },
-            { "capability": "thread.listMetadata", "layer": "L2", "firstPartyPreset": false },
-            { "capability": "thread.readContent", "layer": "L2", "firstPartyPreset": false },
-            { "capability": "memory.query", "layer": "L2", "firstPartyPreset": false },
-            { "capability": "memory.append", "layer": "L2", "firstPartyPreset": false },
-            { "capability": "memory.retrieve", "layer": "L2", "firstPartyPreset": false },
-            { "capability": "windows.create", "layer": "L2", "firstPartyPreset": false },
-            { "capability": "whisper.extend", "layer": "L2", "firstPartyPreset": false }
-          ]
-        }
-      },
-      "expect": {
-        "status": "success",
-        "sideEffects": [
-          { "target": "permission_matrix", "assertion": "matches", "value": { "complete": true, "firstPartyPresetLayers": ["L1"], "defaultWhisperTargets": [] } }
-        ]
-      }
-    },
     {
       "id": "delete-replay-events-preserves-canonical-messages",
       "invariant": "Deleting the replay transport buffer cannot delete canonical messages or threads.",
+      "execution": {
+        "plane": "host-control",
+        "verdictOracle": { "kind": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "host-retention" },
-        "grants": ["message.event.subscribe"],
         "handles": {
           "subscription": { "kind": "subscription", "token": "subscription-token-a", "ownerPluginInstanceId": "host-retention", "threadId": "thread-1", "subscriptionId": "subscription-a" }
         },
@@ -471,36 +371,15 @@
         ]
       }
     },
-    {
-      "id": "snapshot-without-grant-rejected",
-      "invariant": "A subscription identifier cannot bypass the message.event.subscribe grant for snapshots.",
-      "given": {
-        "caller": { "pluginInstanceId": "plugin-a" },
-        "grants": [],
-        "handles": {
-          "subscription": { "kind": "subscription", "token": "subscription-token-a", "ownerPluginInstanceId": "plugin-a", "threadId": "thread-1", "subscriptionId": "subscription-a" }
-        },
-        "state": { "subscription": { "cursorSequence": 4 } }
-      },
-      "when": {
-        "operation": "snapshot",
-        "input": { "subscriptionId": "subscription-a" }
-      },
-      "expect": {
-        "status": "error",
-        "errorCode": "PERMISSION",
-        "sideEffects": [
-          { "target": "snapshot", "assertion": "none" },
-          { "target": "subscription", "assertion": "unchanged" }
-        ]
-      }
-    },
     {
       "id": "foreign-replay-delete-rejected",
       "invariant": "A caller cannot delete another plugin instance's subscription replay buffer.",
+      "execution": {
+        "plane": "host-control",
+        "verdictOracle": { "kind": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "plugin-b" },
-        "grants": ["message.event.subscribe"],
         "handles": {
           "subscription": { "kind": "subscription", "token": "subscription-token-a", "ownerPluginInstanceId": "plugin-a", "threadId": "thread-1", "subscriptionId": "subscription-a" }
         },

package/fixtures/manifest/invalid/contract-version-leading-zero-prerelease.json

@@ -7,9 +7,7 @@
     {
       "id": "echo",
       "name": "Echo",
-      "resources": [],
-      "capabilities": []
-    }
+      "resources": []}
   ],
   "runtime": {
     "transport": "builtin"

package/fixtures/manifest/invalid/contract-version-range.json

@@ -7,9 +7,7 @@
     {
       "id": "echo",
       "name": "Echo",
-      "resources": [],
-      "capabilities": []
-    }
+      "resources": []}
   ],
   "runtime": {
     "transport": "builtin"

package/fixtures/manifest/invalid/duplicate-signal-type.json

@@ -7,9 +7,7 @@
     {
       "id": "meeting-intake",
       "name": "Meeting intake",
-      "resources": [],
-      "capabilities": ["events.publish"]
-    }
+      "resources": []}
   ],
   "signals": {
     "provides": [
@@ -29,5 +27,7 @@
       }
     ]
   },
-  "runtime": { "transport": "builtin" }
+  "runtime": {
+    "transport": "builtin"
+  }
 }

package/fixtures/manifest/invalid/icon-package-escape.json

@@ -0,0 +1,20 @@
+{
+  "pluginId": "com.example.icon-escape",
+  "version": "1.0.0",
+  "contractVersion": "0.1.0-beta.13",
+  "name": "Icon escape fixture",
+  "description": "Legacy description remains accepted.",
+  "icon": {
+    "type": "svg",
+    "src": "../outside.svg"
+  },
+  "features": [
+    {
+      "id": "main",
+      "name": "Main",
+      "resources": []}
+  ],
+  "runtime": {
+    "transport": "builtin"
+  }
+}

package/fixtures/manifest/invalid/ipc-empty-entrypoint.json

@@ -7,9 +7,7 @@
     {
       "id": "echo",
       "name": "Echo",
-      "resources": [],
-      "capabilities": []
-    }
+      "resources": []}
   ],
   "runtime": {
     "transport": "ipc",

package/fixtures/manifest/invalid/plugin-version-leading-zero-prerelease.json

@@ -7,9 +7,7 @@
     {
       "id": "echo",
       "name": "Echo",
-      "resources": [],
-      "capabilities": []
-    }
+      "resources": []}
   ],
   "runtime": {
     "transport": "builtin"

package/fixtures/manifest/invalid/plugin-version-not-semver.json

@@ -7,9 +7,7 @@
     {
       "id": "echo",
       "name": "Echo",
-      "resources": [],
-      "capabilities": []
-    }
+      "resources": []}
   ],
   "runtime": {
     "transport": "builtin"

package/fixtures/manifest/invalid/semver-empty-build-metadata.json

@@ -7,9 +7,7 @@
     {
       "id": "echo",
       "name": "Echo",
-      "resources": [],
-      "capabilities": []
-    }
+      "resources": []}
   ],
   "runtime": {
     "transport": "builtin"

package/fixtures/manifest/invalid/stdio-missing-entrypoint.json

@@ -7,9 +7,7 @@
     {
       "id": "echo",
       "name": "Echo",
-      "resources": [],
-      "capabilities": []
-    }
+      "resources": []}
   ],
   "runtime": {
     "transport": "stdio"

package/fixtures/manifest/invalid/user-authored-lifecycle.json

@@ -7,9 +7,7 @@
     {
       "id": "notes",
       "name": "Notes",
-      "resources": [],
-      "capabilities": []
-    }
+      "resources": []}
   ],
   "data": [
     {

package/fixtures/manifest/valid/localized-product-metadata.json

@@ -0,0 +1,25 @@
+{
+  "pluginId": "com.example.localized-metadata",
+  "version": "1.0.0",
+  "contractVersion": "0.1.0-beta.13",
+  "name": "Localized metadata fixture",
+  "description": {
+    "default": "Describe this plugin for agents and people.",
+    "translations": {
+      "zh-CN": "向 Agent 和用户介绍这个插件。"
+    }
+  },
+  "icon": {
+    "type": "svg",
+    "src": "assets/icon.svg"
+  },
+  "features": [
+    {
+      "id": "main",
+      "name": "Main",
+      "resources": []}
+  ],
+  "runtime": {
+    "transport": "builtin"
+  }
+}

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

@@ -7,9 +7,7 @@
     {
       "id": "echo",
       "name": "Echo",
-      "resources": [],
-      "capabilities": []
-    }
+      "resources": []}
   ],
   "runtime": {
     "transport": "builtin"

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

@@ -8,9 +8,7 @@
     {
       "id": "lifecycle-baseline",
       "name": "Lifecycle baseline",
-      "resources": [],
-      "capabilities": []
-    }
+      "resources": []}
   ],
   "runtime": {
     "transport": "builtin"

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

@@ -7,9 +7,7 @@
     {
       "id": "echo",
       "name": "Echo",
-      "resources": [],
-      "capabilities": []
-    }
+      "resources": []}
   ],
   "runtime": {
     "transport": "builtin"

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

@@ -7,9 +7,7 @@
     {
       "id": "echo",
       "name": "Echo",
-      "resources": [],
-      "capabilities": []
-    }
+      "resources": []}
   ],
   "runtime": {
     "transport": "stdio",

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

@@ -18,7 +18,7 @@
           "audience": {
             "kind": "public"
           },
-          "occurredAt": "2026-07-15T02:42:00Z",
+          "occurredAt": "2026-07-15T02:42:00.000Z",
           "payload": {
             "provenance": {
               "origin": {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@clowder-ai/plugin-contract",
-  "version": "0.1.0-beta.9",
+  "version": "0.3.0",
   "private": false,
-  "description": "Clowder AI plugin contract — the single machine-readable truth source for plugin schema, types, capability table, and conformance fixtures (P15)",
+  "description": "Clowder AI plugin schemas, bidirectional protocol and conformance fixtures",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -14,11 +14,24 @@
       "types": "./dist/conformance/index.d.ts",
       "import": "./dist/conformance/index.js"
     },
+    "./docx-materialization": {
+      "types": "./dist/docx-materialization.d.ts",
+      "import": "./dist/docx-materialization.js"
+    },
+    "./variant": {
+      "types": "./dist/variant.d.ts",
+      "import": "./dist/variant.js"
+    },
     "./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"
+    "./schemas/docx-materialization": "./src/schemas/docx-materialization.schema.json",
+    "./schemas/companion-bridge": "./src/schemas/companion-bridge.schema.json",
+    "./schemas/behavior-fixture": "./src/schemas/behavior-fixture.schema.json",
+    "./fixtures/behavior/messaging/adversarial-invariants": "./fixtures/behavior/messaging/adversarial-invariants.json"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -35,7 +48,7 @@
     "generate:check": "node --import tsx src/codegen/generate-contract.ts --check",
     "build": "pnpm clean && tsc -p tsconfig.build.json && node --test scripts/conformance-public-boundary.test.mjs",
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test src/**/*.test.ts src/**/**/*.test.ts",
+    "test": "node --import tsx --test \"src/**/*.test.ts\"",
     "conformance": "node --import tsx src/conformance/runner.ts",
     "lint": "tsc --noEmit",
     "clean": "rm -rf dist",