@xemahq/kernel-contracts 0.38.0 → 0.40.0

package/dist/canonical-object/index.d.ts

@@ -0,0 +1,3 @@
+export * from './lib/canonical-object-type';
+export * from './lib/canonical-object-type-contribution';
+//# sourceMappingURL=index.d.ts.map

package/dist/canonical-object/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/canonical-object/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,0CAA0C,CAAC"}

package/dist/canonical-object/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./lib/canonical-object-type"), exports);
+__exportStar(require("./lib/canonical-object-type-contribution"), exports);
+//# sourceMappingURL=index.js.map

package/dist/canonical-object/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/canonical-object/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8DAA4C;AAC5C,2EAAyD"}

package/dist/canonical-object/lib/canonical-object-type-contribution.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { type CanonicalObjectTypeRef } from './canonical-object-type';
+export interface CanonicalObjectTypeContributionManifest {
+    readonly key: CanonicalObjectTypeRef;
+    readonly version: string;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly schema: Record<string, unknown>;
+    readonly naturalKeyFields: readonly string[];
+    readonly titleField?: string;
+    readonly category?: string;
+}
+export declare const CanonicalObjectTypeContributionManifestSchema: z.ZodType<CanonicalObjectTypeContributionManifest>;
+//# sourceMappingURL=canonical-object-type-contribution.d.ts.map

package/dist/canonical-object/lib/canonical-object-type-contribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-object-type-contribution.d.ts","sourceRoot":"","sources":["../../../src/canonical-object/lib/canonical-object-type-contribution.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,yBAAyB,CAAC;AAsBjC,MAAM,WAAW,uCAAuC;IAOtD,QAAQ,CAAC,GAAG,EAAE,sBAAsB,CAAC;IAErC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAO9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAMzC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,6CAA6C,EAAE,CAAC,CAAC,OAAO,CAAC,uCAAuC,CA0BtC,CAAC"}

package/dist/canonical-object/lib/canonical-object-type-contribution.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CanonicalObjectTypeContributionManifestSchema = void 0;
+const zod_1 = require("zod");
+const canonical_object_type_1 = require("./canonical-object-type");
+const CANONICAL_OBJECT_STRING_MAX = 200;
+const NATURAL_KEY_FIELDS_MAX = 8;
+const FieldNameSchema = zod_1.z
+    .string()
+    .min(1)
+    .max(CANONICAL_OBJECT_STRING_MAX)
+    .regex(/^[A-Za-z][A-Za-z0-9_]*$/, 'field name must be an identifier-like property of the object schema');
+exports.CanonicalObjectTypeContributionManifestSchema = zod_1.z
+    .object({
+    key: canonical_object_type_1.CanonicalObjectTypeRefSchema,
+    version: canonical_object_type_1.CanonicalObjectTypeVersionSchema,
+    displayName: zod_1.z.string().min(1).max(CANONICAL_OBJECT_STRING_MAX),
+    description: zod_1.z.string().max(2000).optional(),
+    schema: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.unknown())
+        .refine((s) => Object.keys(s).length > 0, 'schema must be a non-empty JSON Schema object'),
+    naturalKeyFields: zod_1.z
+        .array(FieldNameSchema)
+        .min(1, 'at least one natural-key field is required')
+        .max(NATURAL_KEY_FIELDS_MAX),
+    titleField: FieldNameSchema.optional(),
+    category: zod_1.z
+        .string()
+        .min(1)
+        .max(CANONICAL_OBJECT_STRING_MAX)
+        .regex(/^[a-z][a-z0-9-]*$/, 'category must be lower-kebab')
+        .optional(),
+});
+//# sourceMappingURL=canonical-object-type-contribution.js.map

package/dist/canonical-object/lib/canonical-object-type-contribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-object-type-contribution.js","sourceRoot":"","sources":["../../../src/canonical-object/lib/canonical-object-type-contribution.ts"],"names":[],"mappings":";;;AAoBA,6BAAwB;AAExB,mEAIiC;AAGjC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAGxC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAGjC,MAAM,eAAe,GAAG,OAAC;KACtB,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,2BAA2B,CAAC;KAChC,KAAK,CACJ,yBAAyB,EACzB,qEAAqE,CACtE,CAAC;AAuCS,QAAA,6CAA6C,GACxD,OAAC;KACE,MAAM,CAAC;IACN,GAAG,EAAE,oDAA4B;IACjC,OAAO,EAAE,wDAAgC;IACzC,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,2BAA2B,CAAC;IAC/D,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;IAG5C,MAAM,EAAE,OAAC;SACN,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC;SAC/B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,+CAA+C,CAAC;IAC5F,gBAAgB,EAAE,OAAC;SAChB,KAAK,CAAC,eAAe,CAAC;SACtB,GAAG,CAAC,CAAC,EAAE,4CAA4C,CAAC;SACpD,GAAG,CAAC,sBAAsB,CAAC;IAI9B,UAAU,EAAE,eAAe,CAAC,QAAQ,EAAE;IACtC,QAAQ,EAAE,OAAC;SACR,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,2BAA2B,CAAC;SAChC,KAAK,CAAC,mBAAmB,EAAE,8BAA8B,CAAC;SAC1D,QAAQ,EAAE;CACd,CAAkE,CAAC"}

package/dist/canonical-object/lib/canonical-object-type.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+export type CanonicalObjectTypeRef = string;
+export declare const CanonicalObjectTypeRefSchema: z.ZodType<CanonicalObjectTypeRef>;
+export declare const CanonicalObjectTypeVersionSchema: z.ZodString;
+//# sourceMappingURL=canonical-object-type.d.ts.map

package/dist/canonical-object/lib/canonical-object-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-object-type.d.ts","sourceRoot":"","sources":["../../../src/canonical-object/lib/canonical-object-type.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAE5C,eAAO,MAAM,4BAA4B,EAAE,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAOxE,CAAC;AAGJ,eAAO,MAAM,gCAAgC,aAE0B,CAAC"}

package/dist/canonical-object/lib/canonical-object-type.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CanonicalObjectTypeVersionSchema = exports.CanonicalObjectTypeRefSchema = void 0;
+const zod_1 = require("zod");
+const CANONICAL_OBJECT_TYPE_KEY_MAX = 100;
+exports.CanonicalObjectTypeRefSchema = zod_1.z
+    .string()
+    .min(1)
+    .max(CANONICAL_OBJECT_TYPE_KEY_MAX)
+    .regex(/^[a-z][a-z0-9_]*$/, 'a canonical-object-type key must be lower_snake (e.g. sales_opportunity)');
+exports.CanonicalObjectTypeVersionSchema = zod_1.z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/, 'version must be semver MAJOR.MINOR.PATCH');
+//# sourceMappingURL=canonical-object-type.js.map

package/dist/canonical-object/lib/canonical-object-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-object-type.js","sourceRoot":"","sources":["../../../src/canonical-object/lib/canonical-object-type.ts"],"names":[],"mappings":";;;AAuBA,6BAAwB;AAGxB,MAAM,6BAA6B,GAAG,GAAG,CAAC;AAU7B,QAAA,4BAA4B,GAAsC,OAAC;KAC7E,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,6BAA6B,CAAC;KAClC,KAAK,CACJ,mBAAmB,EACnB,0EAA0E,CAC3E,CAAC;AAGS,QAAA,gCAAgC,GAAG,OAAC;KAC9C,MAAM,EAAE;KACR,KAAK,CAAC,iBAAiB,EAAE,0CAA0C,CAAC,CAAC"}

package/dist/connector/index.d.ts

@@ -3,6 +3,7 @@ export * from './lib/connector-adapter-kind';
 export * from './lib/connector-http-request';
 export * from './lib/capability';
 export * from './lib/credential-kind';
+export * from './lib/canonical-operation-binding';
 export * from './lib/credential-strategy-contribution';
 export * from './lib/onboarding-manifest';
 export * from './lib/provider-descriptor';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/connector/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wCAAwC,CAAC;AACvD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yCAAyC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/connector/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mCAAmC,CAAC;AAClD,cAAc,wCAAwC,CAAC;AACvD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yCAAyC,CAAC"}

package/dist/connector/index.js

@@ -19,6 +19,7 @@ __exportStar(require("./lib/connector-adapter-kind"), exports);
 __exportStar(require("./lib/connector-http-request"), exports);
 __exportStar(require("./lib/capability"), exports);
 __exportStar(require("./lib/credential-kind"), exports);
+__exportStar(require("./lib/canonical-operation-binding"), exports);
 __exportStar(require("./lib/credential-strategy-contribution"), exports);
 __exportStar(require("./lib/onboarding-manifest"), exports);
 __exportStar(require("./lib/provider-descriptor"), exports);

package/dist/connector/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/connector/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,+DAA6C;AAC7C,+DAA6C;AAC7C,mDAAiC;AACjC,wDAAsC;AACtC,yEAAuD;AACvD,4DAA0C;AAC1C,4DAA0C;AAC1C,wDAAsC;AACtC,6DAA2C;AAC3C,wDAAsC;AACtC,oDAAkC;AAClC,2DAAyC;AACzC,6DAA2C;AAC3C,0EAAwD"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/connector/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,+DAA6C;AAC7C,+DAA6C;AAC7C,mDAAiC;AACjC,wDAAsC;AACtC,oEAAkD;AAClD,yEAAuD;AACvD,4DAA0C;AAC1C,4DAA0C;AAC1C,wDAAsC;AACtC,6DAA2C;AAC3C,wDAAsC;AACtC,oDAAkC;AAClC,2DAAyC;AACzC,6DAA2C;AAC3C,0EAAwD"}

package/dist/connector/lib/canonical-operation-binding.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { type CanonicalObjectTypeRef } from '../../canonical-object/lib/canonical-object-type';
+export declare enum CanonicalMappingDirection {
+    Read = "read",
+    Write = "write"
+}
+export declare const CanonicalMappingDirectionSchema: z.ZodEnum<typeof CanonicalMappingDirection>;
+export interface CanonicalOperationBinding {
+    readonly objectType: CanonicalObjectTypeRef;
+    readonly direction: CanonicalMappingDirection;
+    readonly fieldMap?: Readonly<Record<string, string>>;
+}
+export declare const CanonicalOperationBindingSchema: z.ZodType<CanonicalOperationBinding>;
+export declare function getByPath(source: unknown, path: string): unknown;
+export declare function setByPath(target: Record<string, unknown>, path: string, value: unknown): void;
+export declare function projectProviderToCanonical(providerRecord: unknown, fieldMap: Readonly<Record<string, string>>): Record<string, unknown>;
+export declare function projectCanonicalToProvider(canonicalObject: Readonly<Record<string, unknown>>, fieldMap: Readonly<Record<string, string>>): Record<string, unknown>;
+//# sourceMappingURL=canonical-operation-binding.d.ts.map

package/dist/connector/lib/canonical-operation-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-operation-binding.d.ts","sourceRoot":"","sources":["../../../src/connector/lib/canonical-operation-binding.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,kDAAkD,CAAC;AAG1D,oBAAY,yBAAyB;IAEnC,IAAI,SAAS;IAEb,KAAK,UAAU;CAChB;AAED,eAAO,MAAM,+BAA+B,6CAA0C,CAAC;AAqCvF,MAAM,WAAW,yBAAyB;IAExC,QAAQ,CAAC,UAAU,EAAE,sBAAsB,CAAC;IAE5C,QAAQ,CAAC,SAAS,EAAE,yBAAyB,CAAC;IAM9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtD;AAED,eAAO,MAAM,+BAA+B,EAAE,CAAC,CAAC,OAAO,CAAC,yBAAyB,CAK1B,CAAC;AAGxD,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAShE;AAGD,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACb,IAAI,CAYN;AAOD,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,OAAO,EACvB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACzC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB;AAMD,wBAAgB,0BAA0B,CACxC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAClD,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACzC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB"}

package/dist/connector/lib/canonical-operation-binding.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CanonicalOperationBindingSchema = exports.CanonicalMappingDirectionSchema = exports.CanonicalMappingDirection = void 0;
+exports.getByPath = getByPath;
+exports.setByPath = setByPath;
+exports.projectProviderToCanonical = projectProviderToCanonical;
+exports.projectCanonicalToProvider = projectCanonicalToProvider;
+const zod_1 = require("zod");
+const canonical_object_type_1 = require("../../canonical-object/lib/canonical-object-type");
+var CanonicalMappingDirection;
+(function (CanonicalMappingDirection) {
+    CanonicalMappingDirection["Read"] = "read";
+    CanonicalMappingDirection["Write"] = "write";
+})(CanonicalMappingDirection || (exports.CanonicalMappingDirection = CanonicalMappingDirection = {}));
+exports.CanonicalMappingDirectionSchema = zod_1.z.nativeEnum(CanonicalMappingDirection);
+const CANONICAL_FIELD_MAP_MAX = 100;
+const CanonicalFieldMapSchema = zod_1.z
+    .record(zod_1.z
+    .string()
+    .min(1)
+    .max(200)
+    .regex(/^[A-Za-z][A-Za-z0-9_]*$/, 'canonical field name must be identifier-like'), zod_1.z
+    .string()
+    .min(1)
+    .max(400)
+    .regex(/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/, 'provider path must be a dot-path of identifier segments'))
+    .refine((m) => Object.keys(m).length <= CANONICAL_FIELD_MAP_MAX, `at most ${CANONICAL_FIELD_MAP_MAX} mapped fields`);
+exports.CanonicalOperationBindingSchema = zod_1.z.strictObject({
+    objectType: canonical_object_type_1.CanonicalObjectTypeRefSchema,
+    direction: exports.CanonicalMappingDirectionSchema,
+    fieldMap: CanonicalFieldMapSchema.optional(),
+});
+function getByPath(source, path) {
+    let cursor = source;
+    for (const segment of path.split('.')) {
+        if (cursor === null || typeof cursor !== 'object') {
+            return undefined;
+        }
+        cursor = cursor[segment];
+    }
+    return cursor;
+}
+function setByPath(target, path, value) {
+    const segments = path.split('.');
+    let cursor = target;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const key = segments[i];
+        const next = cursor[key];
+        if (next === null || typeof next !== 'object' || Array.isArray(next)) {
+            cursor[key] = {};
+        }
+        cursor = cursor[key];
+    }
+    cursor[segments[segments.length - 1]] = value;
+}
+function projectProviderToCanonical(providerRecord, fieldMap) {
+    const out = {};
+    for (const [canonicalField, providerPath] of Object.entries(fieldMap)) {
+        const value = getByPath(providerRecord, providerPath);
+        if (value !== undefined) {
+            out[canonicalField] = value;
+        }
+    }
+    return out;
+}
+function projectCanonicalToProvider(canonicalObject, fieldMap) {
+    const out = {};
+    for (const [canonicalField, providerPath] of Object.entries(fieldMap)) {
+        const value = canonicalObject[canonicalField];
+        if (value !== undefined) {
+            setByPath(out, providerPath, value);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=canonical-operation-binding.js.map

package/dist/connector/lib/canonical-operation-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-operation-binding.js","sourceRoot":"","sources":["../../../src/connector/lib/canonical-operation-binding.ts"],"names":[],"mappings":"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"}

package/dist/connector/lib/connector-descriptor.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { type CapabilityRef } from '../../capability';
+import { type CanonicalOperationBinding } from './canonical-operation-binding';
 import { type CredentialKindRef } from './credential-kind';
 import { ConnectorAdapterKind } from './connector-adapter-kind';
 import { type ConnectorHttpRequestTemplate } from './connector-http-request';
@@ -10,6 +11,7 @@ export interface ConnectorOperationDescriptor {
     readonly scopes: readonly string[];
     readonly requiresConnection: boolean;
     readonly httpRequest?: ConnectorHttpRequestTemplate;
+    readonly canonical?: CanonicalOperationBinding;
 }
 export declare const ConnectorOperationDescriptorSchema: z.ZodObject<{
     capabilityRef: z.ZodType<CapabilityRef, unknown, z.core.$ZodTypeInternals<CapabilityRef, unknown>>;
@@ -29,6 +31,7 @@ export declare const ConnectorOperationDescriptorSchema: z.ZodObject<{
             queryParamName: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
     }, z.core.$strict>>;
+    canonical: z.ZodOptional<z.ZodType<CanonicalOperationBinding, unknown, z.core.$ZodTypeInternals<CanonicalOperationBinding, unknown>>>;
 }, z.core.$strict>;
 export interface ConnectorDescriptor {
     readonly connectorKey: string;
@@ -68,6 +71,7 @@ export declare const ConnectorDescriptorSchema: z.ZodObject<{
                 queryParamName: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>;
         }, z.core.$strict>>;
+        canonical: z.ZodOptional<z.ZodType<CanonicalOperationBinding, unknown, z.core.$ZodTypeInternals<CanonicalOperationBinding, unknown>>>;
     }, z.core.$strict>>>>;
 }, z.core.$strict>;
 type AssertExtends<T extends U, U> = T;

package/dist/connector/lib/connector-descriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connector-descriptor.d.ts","sourceRoot":"","sources":["../../../src/connector/lib/connector-descriptor.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE3E,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,oBAAoB,EAErB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAkBrD,MAAM,WAAW,4BAA4B;IAO3C,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IAKtC,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAQ3C,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAQnC,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IASrC,QAAQ,CAAC,WAAW,CAAC,EAAE,4BAA4B,CAAC;CACrD;AAOD,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;kBA2B3C,CAAC;AASL,MAAM,WAAW,mBAAmB;IAElC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAG1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAU7B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAanC,QAAQ,CAAC,wBAAwB,EAAE,iBAAiB,CAAC;IAOrD,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC;IAQrC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,4BAA4B,EAAE,CAAC;CAC/D;AASD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAUpC,CAAC;AAOH,KAAK,aAAa,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;AACvC,KAAK,uBAAuB,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAC5D,SAAS,uBAAuB,CAAC,CAAC,CAAC,EAAE,GACrC,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS;CAAE,GAC7D,CAAC,CAAC;AACR,MAAM,MAAM,+CAA+C,GAAG;IAC5D,aAAa,CACX,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,EAClD,uBAAuB,CAAC,4BAA4B,CAAC,CACtD;IACD,aAAa,CACX,4BAA4B,EAC5B,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CACnD;CACF,CAAC;AACF,MAAM,MAAM,sCAAsC,GAAG;IACnD,aAAa,CACX,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,EACzC,uBAAuB,CAAC,mBAAmB,CAAC,CAC7C;IACD,aAAa,CAAC,mBAAmB,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;CAC9E,CAAC"}
+{"version":3,"file":"connector-descriptor.d.ts","sourceRoot":"","sources":["../../../src/connector/lib/connector-descriptor.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE3E,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,oBAAoB,EAErB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAkBrD,MAAM,WAAW,4BAA4B;IAO3C,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IAKtC,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAQ3C,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAQnC,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IASrC,QAAQ,CAAC,WAAW,CAAC,EAAE,4BAA4B,CAAC;IASpD,QAAQ,CAAC,SAAS,CAAC,EAAE,yBAAyB,CAAC;CAChD;AAOD,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;kBA2C3C,CAAC;AASL,MAAM,WAAW,mBAAmB;IAElC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAG1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAU7B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAanC,QAAQ,CAAC,wBAAwB,EAAE,iBAAiB,CAAC;IAOrD,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC;IAQrC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,4BAA4B,EAAE,CAAC;CAC/D;AASD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAUpC,CAAC;AAOH,KAAK,aAAa,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;AACvC,KAAK,uBAAuB,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAC5D,SAAS,uBAAuB,CAAC,CAAC,CAAC,EAAE,GACrC,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS;CAAE,GAC7D,CAAC,CAAC;AACR,MAAM,MAAM,+CAA+C,GAAG;IAC5D,aAAa,CACX,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,EAClD,uBAAuB,CAAC,4BAA4B,CAAC,CACtD;IACD,aAAa,CACX,4BAA4B,EAC5B,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CACnD;CACF,CAAC;AACF,MAAM,MAAM,sCAAsC,GAAG;IACnD,aAAa,CACX,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,EACzC,uBAAuB,CAAC,mBAAmB,CAAC,CAC7C;IACD,aAAa,CAAC,mBAAmB,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;CAC9E,CAAC"}

package/dist/connector/lib/connector-descriptor.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConnectorDescriptorSchema = exports.ConnectorOperationDescriptorSchema = void 0;
 const zod_1 = require("zod");
 const capability_1 = require("../../capability");
+const canonical_operation_binding_1 = require("./canonical-operation-binding");
 const credential_kind_1 = require("./credential-kind");
 const connector_adapter_kind_1 = require("./connector-adapter-kind");
 const connector_http_request_1 = require("./connector-http-request");
@@ -13,6 +14,7 @@ exports.ConnectorOperationDescriptorSchema = zod_1.z
     scopes: zod_1.z.array(zod_1.z.string()).readonly(),
     requiresConnection: zod_1.z.boolean(),
     httpRequest: connector_http_request_1.ConnectorHttpRequestTemplateSchema.optional(),
+    canonical: canonical_operation_binding_1.CanonicalOperationBindingSchema.optional(),
 })
     .superRefine((op, ctx) => {
     const isDeclarative = op.adapterKind === connector_adapter_kind_1.ConnectorAdapterKind.DeclarativeHttp;
@@ -31,6 +33,16 @@ exports.ConnectorOperationDescriptorSchema = zod_1.z
             message: `httpRequest is only valid for adapterKind="declarative-http" (got "${op.adapterKind}").`,
         });
     }
+    if (isDeclarative &&
+        op.canonical !== undefined &&
+        op.canonical.fieldMap === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['canonical', 'fieldMap'],
+            message: 'A declarative-http operation bound to a canonical type MUST declare ' +
+                'canonical.fieldMap (there is no code path to map records).',
+        });
+    }
 });
 exports.ConnectorDescriptorSchema = zod_1.z.strictObject({
     connectorKey: zod_1.z.string().min(1),

package/dist/connector/lib/connector-descriptor.js.map

@@ -1 +1 @@
-{"version":3,"file":"connector-descriptor.js","sourceRoot":"","sources":["../../../src/connector/lib/connector-descriptor.ts"],"names":[],"mappings":";;;AAoBA,6BAAwB;AAExB,iDAA2E;AAE3E,uDAG2B;AAC3B,qEAGkC;AAClC,qEAGkC;AAiErB,QAAA,kCAAkC,GAAG,OAAC;KAChD,YAAY,CAAC;IACZ,aAAa,EAAE,gCAAmB;IAClC,WAAW,EAAE,mDAA0B;IACvC,MAAM,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACtC,kBAAkB,EAAE,OAAC,CAAC,OAAO,EAAE;IAC/B,WAAW,EAAE,2DAAkC,CAAC,QAAQ,EAAE;CAC3D,CAAC;KACD,WAAW,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE;IACvB,MAAM,aAAa,GACjB,EAAE,CAAC,WAAW,KAAK,6CAAoB,CAAC,eAAe,CAAC;IAC1D,IAAI,aAAa,IAAI,EAAE,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAClD,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,aAAa,CAAC;YACrB,OAAO,EACL,qEAAqE;gBACrE,6CAA6C;SAChD,CAAC,CAAC;IACL,CAAC;IACD,IAAI,CAAC,aAAa,IAAI,EAAE,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACnD,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,aAAa,CAAC;YACrB,OAAO,EAAE,sEAAsE,EAAE,CAAC,WAAW,KAAK;SACnG,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC,CAAC;AAoEQ,QAAA,yBAAyB,GAAG,OAAC,CAAC,YAAY,CAAC;IACtD,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/B,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,MAAM,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACtC,wBAAwB,EAAE,yCAAuB;IACjD,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,UAAU,EAAE,OAAC,CAAC,KAAK,CAAC,0CAAkC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC9E,CAAC,CAAC"}
+{"version":3,"file":"connector-descriptor.js","sourceRoot":"","sources":["../../../src/connector/lib/connector-descriptor.ts"],"names":[],"mappings":";;;AAoBA,6BAAwB;AAExB,iDAA2E;AAE3E,+EAGuC;AACvC,uDAG2B;AAC3B,qEAGkC;AAClC,qEAGkC;AA0ErB,QAAA,kCAAkC,GAAG,OAAC;KAChD,YAAY,CAAC;IACZ,aAAa,EAAE,gCAAmB;IAClC,WAAW,EAAE,mDAA0B;IACvC,MAAM,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACtC,kBAAkB,EAAE,OAAC,CAAC,OAAO,EAAE;IAC/B,WAAW,EAAE,2DAAkC,CAAC,QAAQ,EAAE;IAC1D,SAAS,EAAE,6DAA+B,CAAC,QAAQ,EAAE;CACtD,CAAC;KACD,WAAW,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE;IACvB,MAAM,aAAa,GACjB,EAAE,CAAC,WAAW,KAAK,6CAAoB,CAAC,eAAe,CAAC;IAC1D,IAAI,aAAa,IAAI,EAAE,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAClD,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,aAAa,CAAC;YACrB,OAAO,EACL,qEAAqE;gBACrE,6CAA6C;SAChD,CAAC,CAAC;IACL,CAAC;IACD,IAAI,CAAC,aAAa,IAAI,EAAE,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACnD,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,aAAa,CAAC;YACrB,OAAO,EAAE,sEAAsE,EAAE,CAAC,WAAW,KAAK;SACnG,CAAC,CAAC;IACL,CAAC;IAGD,IACE,aAAa;QACb,EAAE,CAAC,SAAS,KAAK,SAAS;QAC1B,EAAE,CAAC,SAAS,CAAC,QAAQ,KAAK,SAAS,EACnC,CAAC;QACD,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC;YAC/B,OAAO,EACL,sEAAsE;gBACtE,4DAA4D;SAC/D,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC,CAAC;AAoEQ,QAAA,yBAAyB,GAAG,OAAC,CAAC,YAAY,CAAC;IACtD,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/B,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,MAAM,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACtC,wBAAwB,EAAE,yCAAuB;IACjD,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,UAAU,EAAE,OAAC,CAAC,KAAK,CAAC,0CAAkC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC9E,CAAC,CAAC"}

package/dist/connector/lib/integration-provider-contribution.d.ts

@@ -81,6 +81,7 @@ export declare const IntegrationProviderContributionManifestSchema: z.ZodObject<
                     queryParamName: z.ZodOptional<z.ZodString>;
                 }, z.core.$strict>;
             }, z.core.$strict>>;
+            canonical: z.ZodOptional<z.ZodType<import("./canonical-operation-binding").CanonicalOperationBinding, unknown, z.core.$ZodTypeInternals<import("./canonical-operation-binding").CanonicalOperationBinding, unknown>>>;
         }, z.core.$strict>>>>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;

package/dist/connector/lib/integration-provider-contribution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integration-provider-contribution.d.ts","sourceRoot":"","sources":["../../../src/connector/lib/integration-provider-contribution.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AA0BhE,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;;;;;;;kBACK,CAAC;AAEtD,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CACjD,OAAO,mCAAmC,CAC3C,CAAC;AAQF,eAAO,MAAM,6CAA6C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAqEtD,CAAC;AAEL,MAAM,MAAM,uCAAuC,GAAG,CAAC,CAAC,KAAK,CAC3D,OAAO,6CAA6C,CACrD,CAAC"}
+{"version":3,"file":"integration-provider-contribution.d.ts","sourceRoot":"","sources":["../../../src/connector/lib/integration-provider-contribution.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AA0BhE,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;;;;;;;kBACK,CAAC;AAEtD,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CACjD,OAAO,mCAAmC,CAC3C,CAAC;AAQF,eAAO,MAAM,6CAA6C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAqEtD,CAAC;AAEL,MAAM,MAAM,uCAAuC,GAAG,CAAC,CAAC,KAAK,CAC3D,OAAO,6CAA6C,CACrD,CAAC"}

package/dist/contribution/lib/contribution-kind.d.ts

@@ -31,7 +31,8 @@ export declare enum ContributionKind {
     ResourceOwnership = "resource-ownership",
     StageMachine = "stage-machine",
     SearchType = "search-type",
-    CredentialStrategy = "credential-strategy"
+    CredentialStrategy = "credential-strategy",
+    CanonicalObjectType = "canonical-object-type"
 }
 export declare const ContributionKindSchema: z.ZodEnum<typeof ContributionKind>;
 export type ContributionKindValue = `${ContributionKind}`;

package/dist/contribution/lib/contribution-kind.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contribution-kind.d.ts","sourceRoot":"","sources":["../../../src/contribution/lib/contribution-kind.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkDxB,oBAAY,gBAAgB;IAS1B,WAAW,iBAAiB;IAO5B,OAAO,aAAa;IACpB,YAAY,kBAAkB;IAQ9B,UAAU,gBAAgB;IAK1B,YAAY,kBAAkB;IAC9B,UAAU,gBAAgB;IAC1B,WAAW,iBAAiB;IAS5B,wBAAwB,+BAA+B;IACvD,UAAU,gBAAgB;IAQ1B,YAAY,kBAAkB;IAM9B,WAAW,iBAAiB;IAW5B,cAAc,oBAAoB;IAMlC,kBAAkB,yBAAyB;IAK3C,IAAI,SAAS;IAEb,UAAU,gBAAgB;IAM1B,oBAAoB,0BAA0B;IAK9C,oBAAoB,2BAA2B;IAK/C,yBAAyB,gCAAgC;IAGzD,mBAAmB,yBAAyB;IAI5C,cAAc,oBAAoB;IAElC,eAAe,qBAAqB;IAEpC,iBAAiB,uBAAuB;IAMxC,yBAAyB,gCAAgC;IAEzD,WAAW,iBAAiB;IAI5B,UAAU,gBAAgB;IAO1B,YAAY,kBAAkB;IAM9B,cAAc,oBAAoB;IAgBlC,UAAU,eAAe;IAezB,iBAAiB,uBAAuB;IAcxC,YAAY,kBAAkB;IAkB9B,UAAU,gBAAgB;IAoB1B,kBAAkB,wBAAwB;CAC3C;AAMD,eAAO,MAAM,sBAAsB,oCAAiC,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,GAAG,gBAAgB,EAAE,CAAC"}
+{"version":3,"file":"contribution-kind.d.ts","sourceRoot":"","sources":["../../../src/contribution/lib/contribution-kind.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkDxB,oBAAY,gBAAgB;IAS1B,WAAW,iBAAiB;IAO5B,OAAO,aAAa;IACpB,YAAY,kBAAkB;IAQ9B,UAAU,gBAAgB;IAK1B,YAAY,kBAAkB;IAC9B,UAAU,gBAAgB;IAC1B,WAAW,iBAAiB;IAS5B,wBAAwB,+BAA+B;IACvD,UAAU,gBAAgB;IAQ1B,YAAY,kBAAkB;IAM9B,WAAW,iBAAiB;IAW5B,cAAc,oBAAoB;IAMlC,kBAAkB,yBAAyB;IAK3C,IAAI,SAAS;IAEb,UAAU,gBAAgB;IAM1B,oBAAoB,0BAA0B;IAK9C,oBAAoB,2BAA2B;IAK/C,yBAAyB,gCAAgC;IAGzD,mBAAmB,yBAAyB;IAI5C,cAAc,oBAAoB;IAElC,eAAe,qBAAqB;IAEpC,iBAAiB,uBAAuB;IAMxC,yBAAyB,gCAAgC;IAEzD,WAAW,iBAAiB;IAI5B,UAAU,gBAAgB;IAO1B,YAAY,kBAAkB;IAM9B,cAAc,oBAAoB;IAgBlC,UAAU,eAAe;IAezB,iBAAiB,uBAAuB;IAcxC,YAAY,kBAAkB;IAkB9B,UAAU,gBAAgB;IAoB1B,kBAAkB,wBAAwB;IAmB1C,mBAAmB,0BAA0B;CAC9C;AAMD,eAAO,MAAM,sBAAsB,oCAAiC,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,GAAG,gBAAgB,EAAE,CAAC"}

package/dist/contribution/lib/contribution-kind.js

@@ -36,6 +36,7 @@ var ContributionKind;
     ContributionKind["StageMachine"] = "stage-machine";
     ContributionKind["SearchType"] = "search-type";
     ContributionKind["CredentialStrategy"] = "credential-strategy";
+    ContributionKind["CanonicalObjectType"] = "canonical-object-type";
 })(ContributionKind || (exports.ContributionKind = ContributionKind = {}));
 exports.ContributionKindSchema = zod_1.z.nativeEnum(ContributionKind);
 //# sourceMappingURL=contribution-kind.js.map

package/dist/contribution/lib/contribution-kind.js.map

@@ -1 +1 @@
-{"version":3,"file":"contribution-kind.js","sourceRoot":"","sources":["../../../src/contribution/lib/contribution-kind.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAkDxB,IAAY,gBAwNX;AAxND,WAAY,gBAAgB;IAS1B,gDAA4B,CAAA;IAO5B,wCAAoB,CAAA;IACpB,kDAA8B,CAAA;IAQ9B,8CAA0B,CAAA;IAK1B,kDAA8B,CAAA;IAC9B,8CAA0B,CAAA;IAC1B,gDAA4B,CAAA;IAS5B,2EAAuD,CAAA;IACvD,8CAA0B,CAAA;IAQ1B,kDAA8B,CAAA;IAM9B,gDAA4B,CAAA;IAW5B,sDAAkC,CAAA;IAMlC,+DAA2C,CAAA;IAK3C,iCAAa,CAAA;IAEb,8CAA0B,CAAA;IAM1B,kEAA8C,CAAA;IAK9C,mEAA+C,CAAA;IAK/C,6EAAyD,CAAA;IAGzD,gEAA4C,CAAA;IAI5C,sDAAkC,CAAA;IAElC,wDAAoC,CAAA;IAEpC,4DAAwC,CAAA;IAMxC,6EAAyD,CAAA;IAEzD,gDAA4B,CAAA;IAI5B,8CAA0B,CAAA;IAO1B,kDAA8B,CAAA;IAM9B,sDAAkC,CAAA;IAgBlC,6CAAyB,CAAA;IAezB,4DAAwC,CAAA;IAcxC,kDAA8B,CAAA;IAkB9B,8CAA0B,CAAA;IAoB1B,8DAA0C,CAAA;AAC5C,CAAC,EAxNW,gBAAgB,gCAAhB,gBAAgB,QAwN3B;AAMY,QAAA,sBAAsB,GAAG,OAAC,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC"}
+{"version":3,"file":"contribution-kind.js","sourceRoot":"","sources":["../../../src/contribution/lib/contribution-kind.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAkDxB,IAAY,gBA2OX;AA3OD,WAAY,gBAAgB;IAS1B,gDAA4B,CAAA;IAO5B,wCAAoB,CAAA;IACpB,kDAA8B,CAAA;IAQ9B,8CAA0B,CAAA;IAK1B,kDAA8B,CAAA;IAC9B,8CAA0B,CAAA;IAC1B,gDAA4B,CAAA;IAS5B,2EAAuD,CAAA;IACvD,8CAA0B,CAAA;IAQ1B,kDAA8B,CAAA;IAM9B,gDAA4B,CAAA;IAW5B,sDAAkC,CAAA;IAMlC,+DAA2C,CAAA;IAK3C,iCAAa,CAAA;IAEb,8CAA0B,CAAA;IAM1B,kEAA8C,CAAA;IAK9C,mEAA+C,CAAA;IAK/C,6EAAyD,CAAA;IAGzD,gEAA4C,CAAA;IAI5C,sDAAkC,CAAA;IAElC,wDAAoC,CAAA;IAEpC,4DAAwC,CAAA;IAMxC,6EAAyD,CAAA;IAEzD,gDAA4B,CAAA;IAI5B,8CAA0B,CAAA;IAO1B,kDAA8B,CAAA;IAM9B,sDAAkC,CAAA;IAgBlC,6CAAyB,CAAA;IAezB,4DAAwC,CAAA;IAcxC,kDAA8B,CAAA;IAkB9B,8CAA0B,CAAA;IAoB1B,8DAA0C,CAAA;IAmB1C,iEAA6C,CAAA;AAC/C,CAAC,EA3OW,gBAAgB,gCAAhB,gBAAgB,QA2O3B;AAMY,QAAA,sBAAsB,GAAG,OAAC,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/kernel-contracts",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Consolidated Xema OS kernel wire contracts — pure types + zod schemas for the kernel protocol surfaces. One package, one npm scope, wildcard per-surface subpath exports. No framework/runtime deps.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",

package/src/canonical-object/index.ts

@@ -0,0 +1,2 @@
+export * from './lib/canonical-object-type';
+export * from './lib/canonical-object-type-contribution';

package/src/canonical-object/lib/canonical-object-type-contribution.ts

@@ -0,0 +1,108 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────
+ * Canonical-object-type contribution — the DECLARATIVE CDM registration
+ *
+ * A biome that owns a slice of the enterprise domain contributes one
+ * `ContributionKind.CanonicalObjectType` envelope per canonical business object
+ * it defines. It is pure DATA: the object's key, a versioned JSON-Schema shape,
+ * and its identity/title fields — NO executable code. The receiving service
+ * (the CDM registry in `connector-gateway-api`, the Enterprise-Context / CDM
+ * Adapter) stores it and exposes it so connectors can bind reads/writes to it
+ * and agents can read/write normalized objects of that type.
+ *
+ * Mirrors `CapabilityContributionManifest` / `CredentialStrategyContribution
+ * Manifest`: a value-identical subset of the wire body the owning service
+ * accepts, validated fail-fast at biome-discovery time. Provenance
+ * (`biome.id`, `biome.version`) is NOT a field here — the parser stamps it from
+ * the discovering biome's manifest. Validation is fail-fast; no silent coercion.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+
+import { z } from 'zod';
+
+import {
+  CanonicalObjectTypeRefSchema,
+  CanonicalObjectTypeVersionSchema,
+  type CanonicalObjectTypeRef,
+} from './canonical-object-type';
+
+/** Bound on human-facing strings, keeping envelopes small. */
+const CANONICAL_OBJECT_STRING_MAX = 200;
+
+/** Hard cap on the number of natural-key fields. */
+const NATURAL_KEY_FIELDS_MAX = 8;
+
+/** A field-name of the canonical object (a JSON-Schema property key). */
+const FieldNameSchema = z
+  .string()
+  .min(1)
+  .max(CANONICAL_OBJECT_STRING_MAX)
+  .regex(
+    /^[A-Za-z][A-Za-z0-9_]*$/,
+    'field name must be an identifier-like property of the object schema',
+  );
+
+/**
+ * Manifest shape carried by every `ContributionKind.CanonicalObjectType`
+ * envelope. One contribution = one canonical business-object type.
+ */
+export interface CanonicalObjectTypeContributionManifest {
+  /**
+   * The OPEN canonical-object-type key (lower_snake, e.g. `sales_opportunity`).
+   * Unique across the registry — a second biome contributing the same key is a
+   * conflict the CDM registry rejects (first-writer / owner-scoped, enforced by
+   * the receiving service).
+   */
+  readonly key: CanonicalObjectTypeRef;
+  /** Semver of THIS shape. A breaking field change bumps MAJOR. */
+  readonly version: string;
+  /** Human-readable object-type name for catalog/admin surfaces. */
+  readonly displayName: string;
+  /** Optional longer description of what the object represents. */
+  readonly description?: string;
+  /**
+   * The canonical object's field SHAPE as an opaque JSON Schema (stored as
+   * JSON by the registry; validated structurally only — a JSON object — here,
+   * exactly like `CapabilityContributionManifest.inputSchema`). Connector
+   * mappers and agents validate normalized objects against it.
+   */
+  readonly schema: Record<string, unknown>;
+  /**
+   * The field(s) that form the object's stable natural/identity key (≥1). The
+   * CDM registry + connector mappers use these to dedup/upsert a canonical
+   * object across sources and runs.
+   */
+  readonly naturalKeyFields: readonly string[];
+  /** Which schema field is the human-facing title (defaults to the first natural key). */
+  readonly titleField?: string;
+  /** Optional grouping label for catalog surfaces (e.g. `crm`, `field-service`). */
+  readonly category?: string;
+}
+
+export const CanonicalObjectTypeContributionManifestSchema: z.ZodType<CanonicalObjectTypeContributionManifest> =
+  z
+    .object({
+      key: CanonicalObjectTypeRefSchema,
+      version: CanonicalObjectTypeVersionSchema,
+      displayName: z.string().min(1).max(CANONICAL_OBJECT_STRING_MAX),
+      description: z.string().max(2000).optional(),
+      // Opaque JSON Schema — structural check only (a non-empty object), matching
+      // how capability input/output schemas are typed and stored.
+      schema: z
+        .record(z.string(), z.unknown())
+        .refine((s) => Object.keys(s).length > 0, 'schema must be a non-empty JSON Schema object'),
+      naturalKeyFields: z
+        .array(FieldNameSchema)
+        .min(1, 'at least one natural-key field is required')
+        .max(NATURAL_KEY_FIELDS_MAX),
+      // `titleField` may be any schema property (not necessarily a natural key);
+      // the JSON Schema body is opaque here, so the property-existence check for
+      // both titleField and naturalKeyFields happens in the receiving service.
+      titleField: FieldNameSchema.optional(),
+      category: z
+        .string()
+        .min(1)
+        .max(CANONICAL_OBJECT_STRING_MAX)
+        .regex(/^[a-z][a-z0-9-]*$/, 'category must be lower-kebab')
+        .optional(),
+    }) as unknown as z.ZodType<CanonicalObjectTypeContributionManifest>;

package/src/canonical-object/lib/canonical-object-type.ts

@@ -0,0 +1,49 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────
+ * Canonical business-object type — the Enterprise Context / CDM plane
+ *
+ * A `CanonicalObjectTypeRef` names a SYSTEM-AGNOSTIC business object in the
+ * shared "Common Data Model" (Account, Contact, Opportunity, Visit, Case, …).
+ * It is the counterpart to `XemaObjectKind` (which is the CLOSED, kernel-owned
+ * taxonomy of PLATFORM primitives — biome/agent/skill/workflow/…): this ref is
+ * the OPEN, biome-declarable taxonomy of BUSINESS-DOMAIN objects.
+ *
+ * The point of the CDM plane is that AI/agents read a NORMALIZED enterprise
+ * context and write NORMALIZED objects, while connectors map those canonical
+ * objects to/from the individual systems (IFS, CMS, SharePoint, …). Nothing is
+ * connected point-to-point. Canonical object TYPES are declared by a biome via
+ * a `ContributionKind.CanonicalObjectType` contribution; connectors then bind
+ * their reads/writes to a canonical type through the mapping seams.
+ *
+ * Keys are lower_snake and open — there is no curated set to shadow. The value
+ * is a WIRE CONTRACT (it appears in canonical refs and mapping bindings): never
+ * rename a live key without a migration plan.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+
+import { z } from 'zod';
+
+/** Bound on a canonical-object-type key. */
+const CANONICAL_OBJECT_TYPE_KEY_MAX = 100;
+
+/**
+ * An open, biome-declarable canonical business-object type key. lower_snake,
+ * e.g. `account`, `sales_opportunity`, `visit_report`, `service_case`. Unlike
+ * `CredentialKindRef` there is no curated vocabulary — the whole registry is
+ * contributed.
+ */
+export type CanonicalObjectTypeRef = string;
+
+export const CanonicalObjectTypeRefSchema: z.ZodType<CanonicalObjectTypeRef> = z
+  .string()
+  .min(1)
+  .max(CANONICAL_OBJECT_TYPE_KEY_MAX)
+  .regex(
+    /^[a-z][a-z0-9_]*$/,
+    'a canonical-object-type key must be lower_snake (e.g. sales_opportunity)',
+  );
+
+/** Semver of a canonical object type's shape — a bump means the schema changed. */
+export const CanonicalObjectTypeVersionSchema = z
+  .string()
+  .regex(/^\d+\.\d+\.\d+$/, 'version must be semver MAJOR.MINOR.PATCH');

package/src/connector/index.ts

@@ -3,6 +3,7 @@ export * from './lib/connector-adapter-kind';
 export * from './lib/connector-http-request';
 export * from './lib/capability';
 export * from './lib/credential-kind';
+export * from './lib/canonical-operation-binding';
 export * from './lib/credential-strategy-contribution';
 export * from './lib/onboarding-manifest';
 export * from './lib/provider-descriptor';

package/src/connector/lib/canonical-operation-binding.ts

@@ -0,0 +1,160 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────
+ * Canonical operation binding — the connector↔CDM mapping seam (B1b)
+ *
+ * A connector operation can BIND to a canonical business-object type (declared
+ * via `ContributionKind.CanonicalObjectType`) so the gateway maps between the
+ * provider's shape and the shared Common Data Model:
+ *
+ *   - direction `read`  — the operation FETCHES provider records; the gateway
+ *     projects each provider record → a canonical object (provider → canonical).
+ *   - direction `write` — the operation CREATES/UPDATES; the gateway projects
+ *     the caller's canonical object → the provider payload (canonical → provider).
+ *
+ * For DECLARATIVE-HTTP operations (no code) the mapping is the declarative
+ * `fieldMap`: canonical-field → provider JSON dot-path. For NATIVE code modules
+ * the module's `toCanonical`/`fromCanonical` functions take precedence and the
+ * `fieldMap` is optional. This is the counterpart to the inbound `EventMapper`
+ * (raw event → canonical envelope): here it's raw record ↔ canonical object.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+
+import { z } from 'zod';
+
+import {
+  CanonicalObjectTypeRefSchema,
+  type CanonicalObjectTypeRef,
+} from '../../canonical-object/lib/canonical-object-type';
+
+/** Which way a bound operation maps between provider records and canonical objects. */
+export enum CanonicalMappingDirection {
+  /** Operation reads provider records → gateway emits canonical objects. */
+  Read = 'read',
+  /** Operation writes; caller supplies a canonical object → gateway emits provider payload. */
+  Write = 'write',
+}
+
+export const CanonicalMappingDirectionSchema = z.nativeEnum(CanonicalMappingDirection);
+
+/** Cap on the number of mapped fields, keeping the binding small + bounded. */
+const CANONICAL_FIELD_MAP_MAX = 100;
+
+/**
+ * Declarative field mapping: canonical-object field-name → a dot-path into the
+ * provider record (read) or the provider payload (write). e.g.
+ * `{ "name": "attributes.customer_name", "amount": "value.total" }`.
+ * Dot segments address nested objects; bracket/array indexing is out of scope
+ * (deliberately — keep the DSL deterministic and small).
+ */
+const CanonicalFieldMapSchema = z
+  .record(
+    z
+      .string()
+      .min(1)
+      .max(200)
+      .regex(/^[A-Za-z][A-Za-z0-9_]*$/, 'canonical field name must be identifier-like'),
+    z
+      .string()
+      .min(1)
+      .max(400)
+      .regex(
+        /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/,
+        'provider path must be a dot-path of identifier segments',
+      ),
+  )
+  .refine(
+    (m) => Object.keys(m).length <= CANONICAL_FIELD_MAP_MAX,
+    `at most ${CANONICAL_FIELD_MAP_MAX} mapped fields`,
+  );
+
+/**
+ * Binds a connector operation to a canonical object type + the mapping applied
+ * at the gateway seam.
+ */
+export interface CanonicalOperationBinding {
+  /** The canonical business-object type this operation reads or writes. */
+  readonly objectType: CanonicalObjectTypeRef;
+  /** Read (provider → canonical) or write (canonical → provider). */
+  readonly direction: CanonicalMappingDirection;
+  /**
+   * canonical-field → provider dot-path. REQUIRED for declarative-http
+   * operations (there is no code); OPTIONAL for native modules whose
+   * `toCanonical`/`fromCanonical` map instead.
+   */
+  readonly fieldMap?: Readonly<Record<string, string>>;
+}
+
+export const CanonicalOperationBindingSchema: z.ZodType<CanonicalOperationBinding> =
+  z.strictObject({
+    objectType: CanonicalObjectTypeRefSchema,
+    direction: CanonicalMappingDirectionSchema,
+    fieldMap: CanonicalFieldMapSchema.optional(),
+  }) as unknown as z.ZodType<CanonicalOperationBinding>;
+
+/** Read a dot-path (`a.b.c`) out of a record; `undefined` if any segment is missing. */
+export function getByPath(source: unknown, path: string): unknown {
+  let cursor: unknown = source;
+  for (const segment of path.split('.')) {
+    if (cursor === null || typeof cursor !== 'object') {
+      return undefined;
+    }
+    cursor = (cursor as Record<string, unknown>)[segment];
+  }
+  return cursor;
+}
+
+/** Set a dot-path (`a.b.c`) on a plain object, creating intermediate objects. */
+export function setByPath(
+  target: Record<string, unknown>,
+  path: string,
+  value: unknown,
+): void {
+  const segments = path.split('.');
+  let cursor: Record<string, unknown> = target;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const key = segments[i]!;
+    const next = cursor[key];
+    if (next === null || typeof next !== 'object' || Array.isArray(next)) {
+      cursor[key] = {};
+    }
+    cursor = cursor[key] as Record<string, unknown>;
+  }
+  cursor[segments[segments.length - 1]!] = value;
+}
+
+/**
+ * Project a provider record into a canonical object using a `read` fieldMap.
+ * Deterministic + pure; a missing provider path yields an absent canonical
+ * field (never throws). Centralized so the gateway + any validator agree.
+ */
+export function projectProviderToCanonical(
+  providerRecord: unknown,
+  fieldMap: Readonly<Record<string, string>>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [canonicalField, providerPath] of Object.entries(fieldMap)) {
+    const value = getByPath(providerRecord, providerPath);
+    if (value !== undefined) {
+      out[canonicalField] = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * Project a canonical object into a provider payload using a `write` fieldMap.
+ * Deterministic + pure; an absent canonical field is skipped.
+ */
+export function projectCanonicalToProvider(
+  canonicalObject: Readonly<Record<string, unknown>>,
+  fieldMap: Readonly<Record<string, string>>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [canonicalField, providerPath] of Object.entries(fieldMap)) {
+    const value = canonicalObject[canonicalField];
+    if (value !== undefined) {
+      setByPath(out, providerPath, value);
+    }
+  }
+  return out;
+}

package/src/connector/lib/connector-descriptor.ts

@@ -22,6 +22,10 @@ import { z } from 'zod';
 
 import { CapabilityRefSchema, type CapabilityRef } from '../../capability';
 
+import {
+  CanonicalOperationBindingSchema,
+  type CanonicalOperationBinding,
+} from './canonical-operation-binding';
 import {
   CredentialKindRefSchema,
   type CredentialKindRef,
@@ -91,6 +95,15 @@ export interface ConnectorOperationDescriptor {
    * fails fast at the contribution boundary.
    */
   readonly httpRequest?: ConnectorHttpRequestTemplate;
+  /**
+   * Optional binding to a canonical business-object type (the CDM seam, B1b).
+   * When present, the gateway maps between the provider shape and the canonical
+   * object: `read` projects fetched provider records → canonical objects,
+   * `write` projects a caller's canonical object → the provider payload. A
+   * declarative-http operation with a binding MUST carry a `fieldMap` (there is
+   * no code to map); a native operation may omit it (its module maps).
+   */
+  readonly canonical?: CanonicalOperationBinding;
 }
 
 /**
@@ -105,6 +118,7 @@ export const ConnectorOperationDescriptorSchema = z
     scopes: z.array(z.string()).readonly(),
     requiresConnection: z.boolean(),
     httpRequest: ConnectorHttpRequestTemplateSchema.optional(),
+    canonical: CanonicalOperationBindingSchema.optional(),
   })
   .superRefine((op, ctx) => {
     const isDeclarative =
@@ -125,6 +139,21 @@ export const ConnectorOperationDescriptorSchema = z
         message: `httpRequest is only valid for adapterKind="declarative-http" (got "${op.adapterKind}").`,
       });
     }
+    // A declarative-http operation bound to a canonical type has no code to map
+    // with — it MUST carry a declarative fieldMap.
+    if (
+      isDeclarative &&
+      op.canonical !== undefined &&
+      op.canonical.fieldMap === undefined
+    ) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['canonical', 'fieldMap'],
+        message:
+          'A declarative-http operation bound to a canonical type MUST declare ' +
+          'canonical.fieldMap (there is no code path to map records).',
+      });
+    }
   });
 
 /**

package/src/contribution/lib/contribution-kind.ts

@@ -264,6 +264,25 @@ export enum ContributionKind {
    * token exchange) is the separate code-bearing tier — NOT expressible here.
    */
   CredentialStrategy = 'credential-strategy',
+
+  // -- Enterprise Context / CDM plane ----------------------------------------
+  /**
+   * Category 1 (biome-host `KindParser`). A CANONICAL BUSINESS-OBJECT TYPE in
+   * the shared enterprise Common Data Model — the system-agnostic counterpart
+   * to the closed platform `XemaObjectKind`. A biome declares an OPEN, business-
+   * domain object type (Account, Opportunity, Visit, Case, …) with a versioned
+   * JSON-Schema shape + identity/title fields. The kernel owns this member AND
+   * the manifest schema (`CanonicalObjectTypeContributionManifestSchema`,
+   * exported from `@xemahq/kernel-contracts/canonical-object`), mirroring the
+   * `Capability` / `SearchType` / `CredentialStrategy` kinds: one value-identical
+   * wire shape validated fail-fast by BOTH the biome-host parser
+   * (`canonical-object-type.parser.ts`) and the owning service — the CDM registry
+   * in `connector-gateway-api` (the Enterprise-Context / CDM Adapter). Connectors
+   * then bind their reads/writes to a canonical type through the mapping seams so
+   * AI reads normalized context and writes normalized objects, never point-to-
+   * point. Provenance (`biome.id/version`) is stamped by the parser.
+   */
+  CanonicalObjectType = 'canonical-object-type',
 }
 
 /**