@xemahq/kernel-contracts 0.39.0 → 0.40.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/kernel-contracts",
-  "version": "0.39.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/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).',
+      });
+    }
   });
 
 /**