@clowder-ai/plugin-contract 0.1.0-beta.2 → 0.1.0-beta.20

package/dist/wire/wire-uint53.d.ts

@@ -0,0 +1,26 @@
+/**
+ * WireUInt53 — the single contract-owned numeric profile.
+ * Mechanized from the #1165 frozen shape.
+ *
+ * Raw JSON lexeme: canonical decimal digits 0|[1-9][0-9]*
+ * No sign, no decimal point, no exponent, no leading zeros.
+ * Raw token length ≤ 16 characters.
+ * Parsed value: non-negative safe integer.
+ */
+/** Maximum safe integer (2^53 - 1). */
+export declare const WIRE_UINT53_MAX: 9007199254740991;
+/** Pattern for canonical decimal integer raw tokens. */
+export declare const WIRE_UINT53_RAW_PATTERN: RegExp;
+/** Maximum raw token length (digit count of 2^53-1). */
+export declare const WIRE_UINT53_MAX_RAW_LENGTH: 16;
+/**
+ * Validate a parsed number as a WireUInt53.
+ * Checks Number.isSafeInteger and non-negative.
+ */
+export declare function isWireUInt53(value: number, min?: number, max?: number): boolean;
+/**
+ * Validate a raw JSON token as a canonical WireUInt53 lexeme.
+ * Must be checked BEFORE JSON.parse (pre-dispatch).
+ */
+export declare function isCanonicalUInt53Token(rawToken: string): boolean;
+//# sourceMappingURL=wire-uint53.d.ts.map

package/dist/wire/wire-uint53.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-uint53.d.ts","sourceRoot":"","sources":["../../src/wire/wire-uint53.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,uCAAuC;AACvC,eAAO,MAAM,eAAe,EAAG,gBAA8B,CAAC;AAE9D,wDAAwD;AACxD,eAAO,MAAM,uBAAuB,QAAwB,CAAC;AAE7D,wDAAwD;AACxD,eAAO,MAAM,0BAA0B,EAAG,EAAW,CAAC;AAEtD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,MAAU,EAAE,GAAG,GAAE,MAAwB,GAAG,OAAO,CAEnG;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGhE"}

package/dist/wire/wire-uint53.js

@@ -0,0 +1,32 @@
+/**
+ * WireUInt53 — the single contract-owned numeric profile.
+ * Mechanized from the #1165 frozen shape.
+ *
+ * Raw JSON lexeme: canonical decimal digits 0|[1-9][0-9]*
+ * No sign, no decimal point, no exponent, no leading zeros.
+ * Raw token length ≤ 16 characters.
+ * Parsed value: non-negative safe integer.
+ */
+/** Maximum safe integer (2^53 - 1). */
+export const WIRE_UINT53_MAX = 9_007_199_254_740_991;
+/** Pattern for canonical decimal integer raw tokens. */
+export const WIRE_UINT53_RAW_PATTERN = /^(?:0|[1-9][0-9]*)$/;
+/** Maximum raw token length (digit count of 2^53-1). */
+export const WIRE_UINT53_MAX_RAW_LENGTH = 16;
+/**
+ * Validate a parsed number as a WireUInt53.
+ * Checks Number.isSafeInteger and non-negative.
+ */
+export function isWireUInt53(value, min = 0, max = WIRE_UINT53_MAX) {
+    return Number.isSafeInteger(value) && value >= min && value <= max;
+}
+/**
+ * Validate a raw JSON token as a canonical WireUInt53 lexeme.
+ * Must be checked BEFORE JSON.parse (pre-dispatch).
+ */
+export function isCanonicalUInt53Token(rawToken) {
+    if (rawToken.length === 0 || rawToken.length > WIRE_UINT53_MAX_RAW_LENGTH)
+        return false;
+    return WIRE_UINT53_RAW_PATTERN.test(rawToken);
+}
+//# sourceMappingURL=wire-uint53.js.map

package/dist/wire/wire-uint53.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-uint53.js","sourceRoot":"","sources":["../../src/wire/wire-uint53.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,uCAAuC;AACvC,MAAM,CAAC,MAAM,eAAe,GAAG,qBAA8B,CAAC;AAE9D,wDAAwD;AACxD,MAAM,CAAC,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAE7D,wDAAwD;AACxD,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAW,CAAC;AAEtD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,MAAc,CAAC,EAAE,MAAc,eAAe;IACxF,OAAO,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK,IAAI,GAAG,CAAC;AACrE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAgB;IACrD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,MAAM,GAAG,0BAA0B;QAAE,OAAO,KAAK,CAAC;IACxF,OAAO,uBAAuB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AAChD,CAAC"}

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

@@ -10,6 +10,11 @@
     {
       "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"],
@@ -40,6 +45,11 @@
     {
       "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"],
@@ -73,6 +83,11 @@
     {
       "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"],
@@ -103,6 +118,11 @@
     {
       "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"],
@@ -135,6 +155,11 @@
     {
       "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"],
@@ -165,6 +190,11 @@
     {
       "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"],
@@ -189,6 +219,11 @@
     {
       "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"],
@@ -214,6 +249,11 @@
     {
       "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"],
@@ -247,6 +287,11 @@
     {
       "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"],
@@ -277,6 +322,10 @@
     {
       "id": "preset-l2-rejected",
       "invariant": "First-party presets are derived from L1 and cannot silently grant L2 capabilities.",
+      "execution": {
+        "plane": "host-control",
+        "verdictOracle": { "kind": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "first-party-plugin" },
         "grants": ["messaging.send"],
@@ -298,6 +347,10 @@
     {
       "id": "preset-visible-revocable",
       "invariant": "A first-party L1 preset remains visible and independently revocable.",
+      "execution": {
+        "plane": "host-control",
+        "verdictOracle": { "kind": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "first-party-plugin" },
         "grants": ["messaging.send"],
@@ -318,6 +371,11 @@
     {
       "id": "whisper-target-beyond-default-empty-grant-rejected",
       "invariant": "The default whisper target grant is empty; messaging.send alone cannot add a target.",
+      "execution": {
+        "plane": "plugin-to-host-wire",
+        "method": "messaging.send",
+        "verdictOracle": { "kind": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "plugin-a" },
         "grants": ["messaging.send"],
@@ -351,6 +409,11 @@
     {
       "id": "append-without-grant-rejected",
       "invariant": "A valid message handle does not bypass the messaging.appendElements grant.",
+      "execution": {
+        "plane": "plugin-to-host-wire",
+        "method": "messaging.appendElements",
+        "verdictOracle": { "kind": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "plugin-a" },
         "grants": [],
@@ -381,6 +444,11 @@
     {
       "id": "denied-on-message-rejected",
       "invariant": "The Host cannot deliver an onMessage envelope without an explicit scoped L2 grant.",
+      "execution": {
+        "plane": "host-to-plugin-delivery",
+        "method": "host.messaging.deliver",
+        "verdictOracle": { "kind": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "plugin-a" },
         "grants": [],
@@ -408,6 +476,10 @@
     {
       "id": "permission-matrix-complete",
       "invariant": "The loopback policy matrix covers every signed capability and presets only L1 for first-party plugins.",
+      "execution": {
+        "plane": "host-control",
+        "verdictOracle": { "kind": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "policy-auditor" },
         "grants": [],
@@ -448,6 +520,10 @@
     {
       "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"],
@@ -474,6 +550,11 @@
     {
       "id": "snapshot-without-grant-rejected",
       "invariant": "A subscription identifier cannot bypass the message.event.subscribe grant for snapshots.",
+      "execution": {
+        "plane": "wire-admission",
+        "method": "messaging.snapshot",
+        "verdictOracle": { "kind": "json-rpc-error", "code": -32602, "sideEffects": "behavior-expectation" }
+      },
       "given": {
         "caller": { "pluginInstanceId": "plugin-a" },
         "grants": [],
@@ -498,6 +579,10 @@
     {
       "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"],

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

@@ -0,0 +1,33 @@
+{
+  "pluginId": "example.duplicate-signal",
+  "version": "1.0.0",
+  "contractVersion": "0.1.0",
+  "name": "Duplicate Signal Type",
+  "features": [
+    {
+      "id": "meeting-intake",
+      "name": "Meeting intake",
+      "resources": [],
+      "capabilities": ["events.publish"]
+    }
+  ],
+  "signals": {
+    "provides": [
+      {
+        "type": "feishu.meeting_artifact.generated.v1",
+        "schemaRef": "schemas/meeting-a.schema.json",
+        "epistemicStatus": "observation",
+        "privacyClass": "content-adjacent",
+        "sourceClass": "remote-service"
+      },
+      {
+        "type": "feishu.meeting_artifact.generated.v1",
+        "schemaRef": "schemas/meeting-b.schema.json",
+        "epistemicStatus": "inference",
+        "privacyClass": "content",
+        "sourceClass": "remote-service"
+      }
+    ]
+  },
+  "runtime": { "transport": "builtin" }
+}

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

@@ -0,0 +1,22 @@
+{
+  "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": [],
+      "capabilities": []
+    }
+  ],
+  "runtime": {
+    "transport": "builtin"
+  }
+}

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

@@ -0,0 +1,27 @@
+{
+  "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": [],
+      "capabilities": []
+    }
+  ],
+  "runtime": {
+    "transport": "builtin"
+  }
+}

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/fixtures/signals/invalid/destination-injection.json

@@ -0,0 +1,15 @@
+{
+  "_meta": {
+    "schemaRef": "EventsPublishInput"
+  },
+  "signalType": "feishu.meeting_artifact.generated.v1",
+  "eventId": "feishu-minute-om_abc123-v7",
+  "idempotencyKey": "feishu:minute:om_abc123:7",
+  "occurredAt": "2026-08-09T04:12:31Z",
+  "payload": {
+    "artifactId": "om_abc123"
+  },
+  "destination": {
+    "threadId": "thread_user_selected"
+  }
+}

package/fixtures/signals/invalid/dynamic-schema-url.json

@@ -0,0 +1,10 @@
+{
+  "_meta": {
+    "schemaRef": "SignalDeclaration"
+  },
+  "type": "feishu.meeting_artifact.generated.v1",
+  "schemaRef": "https://attacker.example/schemas/meeting.json",
+  "epistemicStatus": "observation",
+  "privacyClass": "content-adjacent",
+  "sourceClass": "remote-service"
+}

package/fixtures/signals/invalid/forbidden-raw-privacy.json

@@ -0,0 +1,10 @@
+{
+  "_meta": {
+    "schemaRef": "SignalDeclaration"
+  },
+  "type": "local.microphone.frame.v1",
+  "schemaRef": "schemas/microphone-frame.schema.json",
+  "epistemicStatus": "observation",
+  "privacyClass": "av-raw",
+  "sourceClass": "os-metadata"
+}

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

@@ -0,0 +1,12 @@
+{
+  "_meta": {
+    "schemaRef": "EventsPublishInput"
+  },
+  "signalType": "feishu.meeting_artifact.generated.v1",
+  "eventId": "feishu-minute-om_abc123-v7",
+  "idempotencyKey": "feishu:minute:om_abc123:7",
+  "occurredAt": "2026-08-09T12:12:31+08:00",
+  "payload": {
+    "artifactId": "om_abc123"
+  }
+}

package/fixtures/signals/valid/feishu-meeting-artifact.json

@@ -0,0 +1,18 @@
+{
+  "_meta": {
+    "schemaRef": "EventsPublishInput"
+  },
+  "signalType": "feishu.meeting_artifact.generated.v1",
+  "eventId": "feishu-minute-om_abc123-v7",
+  "idempotencyKey": "feishu:minute:om_abc123:7",
+  "occurredAt": "2026-08-09T04:12:31Z",
+  "payload": {
+    "artifactId": "om_abc123",
+    "artifactKind": "minute",
+    "revision": "7",
+    "title": "F292 design review"
+  },
+  "source": {
+    "handle": "feishu://meeting-artifacts/minute/om_abc123?revision=7"
+  }
+}

package/fixtures/signals/valid/remote-service-declaration.json

@@ -0,0 +1,10 @@
+{
+  "_meta": {
+    "schemaRef": "SignalDeclaration"
+  },
+  "type": "feishu.meeting_artifact.generated.v1",
+  "schemaRef": "schemas/feishu-meeting-artifact.schema.json",
+  "epistemicStatus": "observation",
+  "privacyClass": "content-adjacent",
+  "sourceClass": "remote-service"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clowder-ai/plugin-contract",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.20",
   "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",
@@ -14,9 +14,20 @@
       "types": "./dist/conformance/index.d.ts",
       "import": "./dist/conformance/index.js"
     },
+    "./docx-materialization": {
+      "types": "./dist/docx-materialization.d.ts",
+      "import": "./dist/docx-materialization.js"
+    },
     "./schemas/messaging": "./src/schemas/messaging.schema.json",
     "./schemas/manifest": "./src/schemas/manifest.schema.json",
-    "./schemas/behavior-fixture": "./src/schemas/behavior-fixture.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/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",
@@ -31,9 +42,9 @@
   "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",
+    "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",
+    "test": "node --import tsx --test src/**/*.test.ts src/**/**/*.test.ts",
     "conformance": "node --import tsx src/conformance/runner.ts",
     "lint": "tsc --noEmit",
     "clean": "rm -rf dist",
@@ -41,11 +52,13 @@
   },
   "devDependencies": {
     "@types/node": "^20.17.0",
-    "ajv": "^8.17.0",
-    "ajv-formats": "^3.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0"
   },
+  "dependencies": {
+    "ajv": "^8.17.0",
+    "ajv-formats": "^3.0.0"
+  },
   "publishConfig": {
     "access": "public"
   },