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

package/dist/index.js

@@ -0,0 +1,36 @@
+/**
+ * @clowder-ai/plugin-contract
+ *
+ * The single machine-readable truth source for the Clowder AI plugin
+ * ecosystem (P15).  Schema, types, capability table, and conformance
+ * utilities all ship from this package — the host (clowder-ai) and
+ * plugin SDK both consume it; neither redefines structures.
+ *
+ * ## Version strategy (pre-1.0)
+ *
+ * - `0.x.0-candidate.N`: work-in-progress, NOT published to registry,
+ *   no implementation may consume.
+ * - `0.x.0`: published after dual-sign merge (CODEOWNERS) + CI publish.
+ *   Registry must show exact version + digest before any gate proceeds.
+ * - Breaking changes are expected before 1.0 (P3).
+ * - v1.0.0 = public compatibility commitment; breaking window closes.
+ *
+ * ## Domains (v0.1 candidate)
+ *
+ * - **messaging**: MessagePayload, MessageDraft, MessageEnvelope,
+ *   MessageOutputEvent, AppendElementsRequest, SendReceipt
+ * - **manifest**: PluginManifest, PluginFeature, DataDeclaration,
+ *   RuntimeDeclaration (v0.1 scope — signals/tasks/windows deferred)
+ * - **capability**: L0/L1/L2 capability table (`@signed(G-0 2026-07-15)`)
+ * - **data-class**: DataClass × DataStrategy validation
+ * - **generated projection**: all public structural types and contract tables
+ *   are deterministically generated from the JSON Schemas
+ * - **validation**: shared semantic checks for constraints JSON Schema cannot
+ *   express, including UTF-8 payload byte budgets
+ *
+ * @packageDocumentation
+ */
+// Re-export everything from the types barrel
+export * from './types/index.js';
+export * from './validation/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,6CAA6C;AAC7C,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC"}

package/dist/types/capability.d.ts

@@ -0,0 +1,4 @@
+import { type AuthorizationLayer } from '../generated/contract.generated.js';
+/** Return the schema-owned authorization layer for a capability identifier. */
+export declare function getCapabilityLayer(capability: string): AuthorizationLayer | undefined;
+//# sourceMappingURL=capability.d.ts.map

package/dist/types/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/types/capability.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,oCAAoC,CAAC;AAE5C,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAOrF"}

package/dist/types/capability.js

@@ -0,0 +1,11 @@
+import { CAPABILITY_TABLE, } from '../generated/contract.generated.js';
+/** Return the schema-owned authorization layer for a capability identifier. */
+export function getCapabilityLayer(capability) {
+    for (const layer of Object.keys(CAPABILITY_TABLE)) {
+        if (CAPABILITY_TABLE[layer].includes(capability)) {
+            return layer;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=capability.js.map

package/dist/types/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../src/types/capability.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,GAEjB,MAAM,oCAAoC,CAAC;AAE5C,+EAA+E;AAC/E,MAAM,UAAU,kBAAkB,CAAC,UAAkB;IACnD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAyB,EAAE,CAAC;QAC1E,IAAK,gBAAgB,CAAC,KAAK,CAAuB,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YACxE,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/types/data-class.d.ts

@@ -0,0 +1,3 @@
+/** Validate a schema-owned (dataClass, strategy) combination. */
+export declare function isValidDataClassStrategy(dataClass: unknown, strategy: unknown): boolean;
+//# sourceMappingURL=data-class.d.ts.map

package/dist/types/data-class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-class.d.ts","sourceRoot":"","sources":["../../src/types/data-class.ts"],"names":[],"mappings":"AAMA,iEAAiE;AACjE,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,OAAO,EAClB,QAAQ,EAAE,OAAO,GAChB,OAAO,CAOT"}

package/dist/types/data-class.js

@@ -0,0 +1,12 @@
+import { DATA_CLASS_ALLOWED_STRATEGIES } from '../generated/contract.generated.js';
+const STRATEGIES_BY_DATA_CLASS = DATA_CLASS_ALLOWED_STRATEGIES;
+/** Validate a schema-owned (dataClass, strategy) combination. */
+export function isValidDataClassStrategy(dataClass, strategy) {
+    if (typeof dataClass !== 'string' || typeof strategy !== 'string')
+        return false;
+    const allowed = STRATEGIES_BY_DATA_CLASS[dataClass];
+    if (allowed === undefined)
+        return false;
+    return allowed.includes(strategy);
+}
+//# sourceMappingURL=data-class.js.map

package/dist/types/data-class.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-class.js","sourceRoot":"","sources":["../../src/types/data-class.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AAEnF,MAAM,wBAAwB,GAAG,6BAEhC,CAAC;AAEF,iEAAiE;AACjE,MAAM,UAAU,wBAAwB,CACtC,SAAkB,EAClB,QAAiB;IAEjB,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAEhF,MAAM,OAAO,GAAG,wBAAwB,CAAC,SAAS,CAAC,CAAC;IACpD,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAExC,OAAO,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACpC,CAAC"}

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+/** Schema-generated contract types and tables plus handwritten runtime helpers. */
+export * from '../generated/contract.generated.js';
+export { getCapabilityLayer } from './capability.js';
+export { isValidDataClassStrategy } from './data-class.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,cAAc,oCAAoC,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,5 @@
+/** Schema-generated contract types and tables plus handwritten runtime helpers. */
+export * from '../generated/contract.generated.js';
+export { getCapabilityLayer } from './capability.js';
+export { isValidDataClassStrategy } from './data-class.js';
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,cAAc,oCAAoC,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/validation/index.d.ts

@@ -0,0 +1,2 @@
+export { validateMessagingSemantics, type SemanticValidationError, type SemanticValidationResult, } from './messaging-semantic.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/validation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,GAC9B,MAAM,yBAAyB,CAAC"}

package/dist/validation/index.js

@@ -0,0 +1,2 @@
+export { validateMessagingSemantics, } from './messaging-semantic.js';
+//# sourceMappingURL=index.js.map

package/dist/validation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,GAG3B,MAAM,yBAAyB,CAAC"}

package/dist/validation/messaging-semantic.d.ts

@@ -0,0 +1,10 @@
+export interface SemanticValidationError {
+    readonly path: string;
+    readonly message: string;
+}
+export interface SemanticValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly SemanticValidationError[];
+}
+export declare function validateMessagingSemantics(schemaRef: string, value: unknown): SemanticValidationResult;
+//# sourceMappingURL=messaging-semantic.d.ts.map

package/dist/validation/messaging-semantic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messaging-semantic.d.ts","sourceRoot":"","sources":["../../src/validation/messaging-semantic.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,uBAAuB,EAAE,CAAC;CACrD;AAuFD,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,GACb,wBAAwB,CAoC1B"}

package/dist/validation/messaging-semantic.js

@@ -0,0 +1,99 @@
+import { MESSAGING_BOUNDS } from '../generated/contract.generated.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function payloadBytes(payload) {
+    try {
+        const serialized = JSON.stringify(payload);
+        return serialized === undefined
+            ? undefined
+            : Buffer.byteLength(serialized, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function elementGroups(schemaRef, value) {
+    if (!isRecord(value))
+        return [];
+    if (schemaRef === 'MessageDraft' || schemaRef === 'MessageEnvelope') {
+        const payload = value['payload'];
+        return isRecord(payload) && Array.isArray(payload['elements'])
+            ? [payload['elements']]
+            : [];
+    }
+    if (schemaRef === 'AppendElementsRequest' ||
+        schemaRef === 'MessageElementsAppendEvent') {
+        return Array.isArray(value['elements']) ? [value['elements']] : [];
+    }
+    if (schemaRef === 'MessagePublishEvent') {
+        const envelope = value['envelope'];
+        return isRecord(envelope)
+            ? elementGroups('MessageEnvelope', envelope)
+            : [];
+    }
+    if (schemaRef === 'MessageOutputEvent') {
+        return value['type'] === 'message.publish'
+            ? elementGroups('MessagePublishEvent', value)
+            : elementGroups('MessageElementsAppendEvent', value);
+    }
+    if (schemaRef === 'SubscriptionReadResponse' && Array.isArray(value['events'])) {
+        return value['events'].flatMap((event) => elementGroups('MessageOutputEvent', event));
+    }
+    if (schemaRef === 'SnapshotResponse' && Array.isArray(value['envelopes'])) {
+        return value['envelopes'].flatMap((envelope) => elementGroups('MessageEnvelope', envelope));
+    }
+    if (schemaRef === 'root') {
+        if ('address' in value && 'payload' in value) {
+            return elementGroups('MessageDraft', value);
+        }
+        if ('occurredAt' in value && 'payload' in value) {
+            return elementGroups('MessageEnvelope', value);
+        }
+        if ('handle' in value && 'elements' in value) {
+            return elementGroups('AppendElementsRequest', value);
+        }
+        if (typeof value['type'] === 'string') {
+            return elementGroups('MessageOutputEvent', value);
+        }
+        if ('events' in value) {
+            return elementGroups('SubscriptionReadResponse', value);
+        }
+        if ('envelopes' in value) {
+            return elementGroups('SnapshotResponse', value);
+        }
+    }
+    return [];
+}
+export function validateMessagingSemantics(schemaRef, value) {
+    const errors = [];
+    for (const [groupIndex, elements] of elementGroups(schemaRef, value).entries()) {
+        let totalBytes = 0;
+        for (const [elementIndex, rawElement] of elements.entries()) {
+            const path = `/elementGroups/${groupIndex}/${elementIndex}/payload`;
+            const payload = isRecord(rawElement)
+                ? rawElement.payload
+                : undefined;
+            const bytes = payloadBytes(payload);
+            if (bytes === undefined) {
+                errors.push({ path, message: 'element payload must be JSON-serializable' });
+                continue;
+            }
+            totalBytes += bytes;
+            if (bytes > MESSAGING_BOUNDS.maxElementPayloadBytes) {
+                errors.push({
+                    path,
+                    message: `element payload exceeds ${MESSAGING_BOUNDS.maxElementPayloadBytes} bytes`,
+                });
+            }
+        }
+        if (totalBytes > MESSAGING_BOUNDS.maxTotalPayloadBytes) {
+            errors.push({
+                path: `/elementGroups/${groupIndex}`,
+                message: `total element payload exceeds ${MESSAGING_BOUNDS.maxTotalPayloadBytes} bytes`,
+            });
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+//# sourceMappingURL=messaging-semantic.js.map

package/dist/validation/messaging-semantic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messaging-semantic.js","sourceRoot":"","sources":["../../src/validation/messaging-semantic.ts"],"names":[],"mappings":"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"}