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

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

@@ -0,0 +1,475 @@
+{
+  "_meta": {
+    "executor": "loopback",
+    "domain": "messaging",
+    "contractVersion": "0.1.0",
+    "source": "K-1 mirror adversarial tests plus G-0 signed values (2026-07-15)",
+    "description": "Host and SDK loopback scenarios shipped with the contract; P-2 supplies the executor. Signed policy cases remain executable data rather than prose-only obligations."
+  },
+  "cases": [
+    {
+      "id": "raw-thread-id-rejection",
+      "invariant": "Plugins cannot address threads by raw threadId.",
+      "given": {
+        "caller": { "pluginInstanceId": "plugin-a" },
+        "grants": ["messaging.send"],
+        "handles": {},
+        "state": { "threads": [{ "threadId": "thread-1" }] }
+      },
+      "when": {
+        "operation": "send",
+        "input": {
+          "address": { "kind": "thread_id", "threadId": "thread-1" },
+          "idempotencyKey": "raw-thread-id-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": "system-audience-dual-rejection",
+      "invariant": "Drafts cannot express the host-only system audience.",
+      "given": {
+        "caller": { "pluginInstanceId": "plugin-a" },
+        "grants": ["messaging.send"],
+        "handles": {
+          "target": { "kind": "thread_handle", "token": "thread-handle-a", "ownerPluginInstanceId": "plugin-a", "threadId": "thread-1" }
+        },
+        "state": {}
+      },
+      "when": {
+        "operation": "send",
+        "input": {
+          "address": { "kind": "thread_handle", "handle": "thread-handle-a" },
+          "draftAudience": { "kind": "system" },
+          "idempotencyKey": "system-audience-1",
+          "payload": {
+            "provenance": { "epistemicStatus": "inference" },
+            "elements": [{ "elementId": "text-1", "kind": "text", "payload": { "text": "blocked" } }]
+          }
+        }
+      },
+      "expect": {
+        "status": "error",
+        "errorCode": "VALIDATION",
+        "sideEffects": [
+          { "target": "messages", "assertion": "unchanged" },
+          { "target": "output_events", "assertion": "none" },
+          { "target": "idempotency_ledger", "assertion": "unchanged" }
+        ]
+      }
+    },
+    {
+      "id": "cross-instance-handle-rejection",
+      "invariant": "A message handle issued to one plugin instance cannot authorize another.",
+      "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" }
+        },
+        "state": { "messages": [{ "messageId": "message-1", "revision": 1 }] }
+      },
+      "when": {
+        "operation": "appendElements",
+        "input": {
+          "handle": { "kind": "message", "token": "message-handle-b" },
+          "operationId": "cross-instance-append-1",
+          "baseRevision": 1,
+          "elements": [{ "elementId": "text-2", "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": "origin-forgery-rejection",
+      "invariant": "A thread-handle send may only declare the caller's own plugin origin.",
+      "given": {
+        "caller": { "pluginInstanceId": "plugin-a" },
+        "grants": ["messaging.send"],
+        "handles": {
+          "target": { "kind": "thread_handle", "token": "thread-handle-a", "ownerPluginInstanceId": "plugin-a", "threadId": "thread-1" }
+        },
+        "state": {}
+      },
+      "when": {
+        "operation": "send",
+        "input": {
+          "address": { "kind": "thread_handle", "handle": "thread-handle-a" },
+          "idempotencyKey": "origin-forgery-1",
+          "payload": {
+            "provenance": { "origin": { "kind": "plugin", "instanceId": "plugin-b" }, "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": "provenance", "assertion": "unchanged" }
+        ]
+      }
+    },
+    {
+      "id": "base-revision-conflict-zero-change",
+      "invariant": "A stale baseRevision produces CONFLICT and no mutation.",
+      "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" }
+        },
+        "state": { "messages": [{ "messageId": "message-1", "revision": 2 }] }
+      },
+      "when": {
+        "operation": "appendElements",
+        "input": {
+          "handle": { "kind": "message", "token": "message-handle-a" },
+          "operationId": "stale-revision-1",
+          "baseRevision": 1,
+          "elements": [{ "elementId": "text-2", "kind": "text", "payload": { "text": "blocked" } }]
+        }
+      },
+      "expect": {
+        "status": "error",
+        "errorCode": "CONFLICT",
+        "sideEffects": [
+          { "target": "messages", "assertion": "unchanged" },
+          { "target": "output_events", "assertion": "none" },
+          { "target": "idempotency_ledger", "assertion": "unchanged" }
+        ]
+      }
+    },
+    {
+      "id": "stale-cursor-snapshot-roundtrip",
+      "invariant": "A stale cursor reports stale and snapshot catch-up supplies an exact resume point.",
+      "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" }
+        },
+        "state": { "subscription": { "cursorSequence": 4 }, "eventWindow": { "oldestSequence": 8, "headSequence": 12 } }
+      },
+      "when": {
+        "operation": "read",
+        "input": { "subscriptionId": "subscription-a", "limit": 32 }
+      },
+      "expect": {
+        "status": "success",
+        "sideEffects": [
+          { "target": "subscription", "assertion": "state_equals", "value": { "stale": true, "ackToken": null, "events": [] } },
+          { "target": "snapshot", "assertion": "round_trip", "value": { "operation": "snapshot", "resumeSequence": 12, "nextReadStartsAfter": 12 } },
+          { "target": "output_events", "assertion": "unchanged" }
+        ]
+      }
+    },
+    {
+      "id": "cross-subscription-ack-rejection",
+      "invariant": "Ack tokens are subscription-local and cannot cross subscriptions.",
+      "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" }
+        },
+        "state": { "subscriptions": [{ "subscriptionId": "subscription-a", "ackedSequence": 1 }, { "subscriptionId": "subscription-b", "ackedSequence": 2 }] }
+      },
+      "when": {
+        "operation": "ack",
+        "input": { "subscriptionId": "subscription-b", "ackToken": "ack-from-a" }
+      },
+      "expect": {
+        "status": "error",
+        "errorCode": "VALIDATION",
+        "sideEffects": [
+          { "target": "subscription", "assertion": "unchanged" },
+          { "target": "output_events", "assertion": "unchanged" }
+        ]
+      }
+    },
+    {
+      "id": "reply-to-cross-thread-leakage",
+      "invariant": "replyTo cannot reference a message from another thread.",
+      "given": {
+        "caller": { "pluginInstanceId": "plugin-a" },
+        "grants": ["messaging.send"],
+        "handles": {
+          "target": { "kind": "thread_handle", "token": "thread-handle-a", "ownerPluginInstanceId": "plugin-a", "threadId": "thread-1" }
+        },
+        "state": { "messages": [{ "messageId": "message-other", "threadId": "thread-2", "text": "secret" }] }
+      },
+      "when": {
+        "operation": "send",
+        "input": {
+          "address": { "kind": "thread_handle", "handle": "thread-handle-a" },
+          "replyTo": "message-other",
+          "idempotencyKey": "cross-thread-reply-1",
+          "payload": {
+            "provenance": { "epistemicStatus": "inference" },
+            "elements": [{ "elementId": "text-1", "kind": "text", "payload": { "text": "blocked" } }]
+          }
+        }
+      },
+      "expect": {
+        "status": "error",
+        "errorCode": "VALIDATION",
+        "sideEffects": [
+          { "target": "messages", "assertion": "unchanged" },
+          { "target": "reply_preview", "assertion": "none" },
+          { "target": "output_events", "assertion": "none" }
+        ]
+      }
+    },
+    {
+      "id": "epistemic-status-upgrade-rejection",
+      "invariant": "Derived content cannot claim a stronger epistemic status than its source.",
+      "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" }
+        },
+        "state": { "messages": [{ "messageId": "message-1", "revision": 1, "elements": [{ "elementId": "source-1", "epistemicStatus": "inference" }] }] }
+      },
+      "when": {
+        "operation": "appendElements",
+        "input": {
+          "handle": { "kind": "message", "token": "message-handle-a" },
+          "operationId": "epistemic-upgrade-1",
+          "baseRevision": 1,
+          "elements": [{ "elementId": "derived-1", "kind": "text", "payload": { "text": "blocked" }, "derivedFromElementId": "source-1", "epistemicStatus": "user_intent" }]
+        }
+      },
+      "expect": {
+        "status": "error",
+        "errorCode": "VALIDATION",
+        "sideEffects": [
+          { "target": "messages", "assertion": "unchanged" },
+          { "target": "output_events", "assertion": "none" },
+          { "target": "provenance", "assertion": "unchanged" }
+        ]
+      }
+    },
+    {
+      "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", "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" } }]
+        }
+      },
+      "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" }
+        },
+        "state": {}
+      },
+      "when": {
+        "operation": "deliverOnMessage",
+        "input": {
+          "threadHandle": "thread-handle-a",
+          "envelope": { "messageId": "message-1", "threadId": "thread-1" }
+        }
+      },
+      "expect": {
+        "status": "error",
+        "errorCode": "PERMISSION",
+        "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.",
+      "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" }
+        },
+        "state": {
+          "messages": [{ "messageId": "message-1", "threadId": "thread-1" }],
+          "replayEvents": [{ "eventId": "event-1", "sequence": 1 }]
+        }
+      },
+      "when": {
+        "operation": "deleteReplayEvents",
+        "input": { "subscriptionId": "subscription-a", "throughSequence": 1 }
+      },
+      "expect": {
+        "status": "success",
+        "sideEffects": [
+          { "target": "replay_events", "assertion": "none" },
+          { "target": "messages", "assertion": "unchanged" }
+        ]
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,17 @@
+{
+  "pluginId": "dev.clowder.fixture.invalid-contract-prerelease",
+  "version": "1.0.0",
+  "contractVersion": "0.1.0-01",
+  "name": "Invalid contract prerelease fixture",
+  "features": [
+    {
+      "id": "echo",
+      "name": "Echo",
+      "resources": [],
+      "capabilities": []
+    }
+  ],
+  "runtime": {
+    "transport": "builtin"
+  }
+}

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

@@ -0,0 +1,17 @@
+{
+  "pluginId": "dev.clowder.fixture.invalid-contract-range",
+  "version": "0.1.0",
+  "contractVersion": "^0.1.0",
+  "name": "Invalid contract range fixture",
+  "features": [
+    {
+      "id": "echo",
+      "name": "Echo",
+      "resources": [],
+      "capabilities": []
+    }
+  ],
+  "runtime": {
+    "transport": "builtin"
+  }
+}

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

@@ -0,0 +1,18 @@
+{
+  "pluginId": "dev.clowder.fixture.ipc-empty-entrypoint",
+  "version": "0.1.0",
+  "contractVersion": "0.1.0",
+  "name": "Invalid IPC fixture plugin",
+  "features": [
+    {
+      "id": "echo",
+      "name": "Echo",
+      "resources": [],
+      "capabilities": []
+    }
+  ],
+  "runtime": {
+    "transport": "ipc",
+    "entrypoint": ""
+  }
+}

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

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

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

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

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

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

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

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

package/fixtures/manifest/invalid/unknown-capability.json

@@ -0,0 +1,19 @@
+{
+  "pluginId": "dev.clowder.fixture.unknown-capability",
+  "version": "0.1.0",
+  "contractVersion": "0.1.0",
+  "name": "Unknown capability fixture",
+  "features": [
+    {
+      "id": "escape",
+      "name": "Escape",
+      "resources": [],
+      "capabilities": [
+        "host.unrestricted"
+      ]
+    }
+  ],
+  "runtime": {
+    "transport": "builtin"
+  }
+}

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

@@ -0,0 +1,24 @@
+{
+  "pluginId": "dev.clowder.fixture.invalid-lifecycle",
+  "version": "0.1.0",
+  "contractVersion": "0.1.0",
+  "name": "Invalid lifecycle fixture",
+  "features": [
+    {
+      "id": "notes",
+      "name": "Notes",
+      "resources": [],
+      "capabilities": []
+    }
+  ],
+  "data": [
+    {
+      "name": "notes",
+      "dataClass": "user-authored",
+      "strategy": "lifecycle"
+    }
+  ],
+  "runtime": {
+    "transport": "builtin"
+  }
+}