feat(shared): add shared field mapping protocol template

Add shared/mapping.zod.ts as a template for field mapping across the stack.
Individual domains (ETL, Sync, Connector, External Lookup) maintain their specific
implementations for backward compatibility but can reference the shared pattern.

Task 1.3 partially complete - shared protocol created but domains retain specific schemas.

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/spec/src/automation/sync.zod.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { FieldMappingSchema } from '../shared/mapping.zod';
 
 /**
  * Data Sync Protocol - LEVEL 1: Simple Synchronization
@@ -98,42 +99,13 @@ export const ConflictResolutionSchema = z.enum([
 export type ConflictResolution = z.infer<typeof ConflictResolutionSchema>;
 
 /**
- * Field Mapping Schema
+ * Field Mapping for Data Sync
  * 
- * Maps fields between source and destination systems.
+ * Uses the canonical field mapping protocol from shared/mapping.zod.ts
+ * for simple 1:1 field transformations.
+ * 
+ * @see {@link FieldMappingSchema} for the base field mapping schema
  */
-export const FieldMappingSchema = z.object({
-  /**
-   * Source field name
-   */
-  sourceField: z.string().describe('Source field name'),
-
-  /**
-   * Destination field name
-   */
-  destinationField: z.string().describe('Destination field name'),
-
-  /**
-   * Transformation formula
-   * JavaScript expression to transform the value
-   * 
-   * @example "value.toUpperCase()"
-   * @example "new Date(value).toISOString()"
-   */
-  transform: z.string().optional().describe('Transformation formula'),
-
-  /**
-   * Default value if source is null/undefined
-   */
-  default: z.any().optional().describe('Default value'),
-
-  /**
-   * Whether to sync null values
-   */
-  syncNull: z.boolean().default(false).describe('Sync null values'),
-});
-
-export type FieldMapping = z.infer<typeof FieldMappingSchema>;
 
 /**
  * Data Source Configuration

packages/spec/src/data/external-lookup.zod.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { FieldMappingSchema as BaseFieldMappingSchema } from '../shared/mapping.zod';
 
 /**
  * External Data Source Schema
@@ -63,36 +64,27 @@ export const ExternalDataSourceSchema = z.object({
 });
 
 /**
- * Field Mapping Schema
+ * Field Mapping Schema for External Lookups
  * 
- * Maps external system fields to local object fields.
- * Defines data type and read/write permissions.
+ * Extends the base field mapping with external lookup specific features.
+ * Uses the canonical field mapping protocol from shared/mapping.zod.ts.
+ * 
+ * @see {@link BaseFieldMappingSchema} for the base field mapping schema
  * 
  * @example
  * ```json
  * {
- *   "externalField": "AccountName",
- *   "localField": "name",
- *   "type": "text",
+ *   "source": "AccountName",
+ *   "target": "name",
  *   "readonly": true
  * }
  * ```
  */
-export const FieldMappingSchema = z.object({
-  /**
-   * Field name in the external system
-   */
-  externalField: z.string().describe('External field name'),
-
-  /**
-   * Corresponding local field name (snake_case)
-   */
-  localField: z.string().describe('Local field name'),
-
+export const FieldMappingSchema = BaseFieldMappingSchema.extend({
   /**
-   * Data type of the field
+   * Field data type
    */
-  type: z.string().describe('Field type'),
+  type: z.string().optional().describe('Field type'),
 
   /**
    * Whether the field is read-only

packages/spec/src/integration/connector.zod.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { WebhookSchema } from '../automation/webhook.zod';
 import { AuthConfigSchema as ConnectorAuthConfigSchema } from '../auth/config.zod';
+import { FieldMappingSchema as BaseFieldMappingSchema, TransformTypeSchema } from '../shared/mapping.zod';
 
 /**
  * Connector Protocol - LEVEL 3: Enterprise Connector
@@ -55,10 +56,14 @@ export type Authentication = z.infer<typeof ConnectorAuthConfigSchema>;
 
 // ============================================================================
 // Field Mapping Schema
+// Uses the canonical field mapping protocol from shared/mapping.zod.ts
+// Extended with connector-specific features
 // ============================================================================
 
 /**
- * Field Transformation Function
+ * Field Transformation Function (Connector-specific)
+ * 
+ * @deprecated Use TransformTypeSchema from shared/mapping.zod.ts instead
  */
 export const FieldTransformSchema = z.object({
   type: z.enum([
@@ -78,22 +83,14 @@ export const FieldTransformSchema = z.object({
 export type FieldTransform = z.infer<typeof FieldTransformSchema>;
 
 /**
- * Field Mapping Configuration
- * Maps fields between ObjectStack and external system
+ * Connector Field Mapping Configuration
+ * 
+ * Extends the base field mapping with connector-specific features
+ * like bidirectional sync modes and data type mapping.
  */
-export const FieldMappingSchema = z.object({
-  /**
-   * Source field name (in external system)
-   */
-  sourceField: z.string().describe('Field name in external system'),
-  
-  /**
-   * Target field name (in ObjectStack)
-   */
-  targetField: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Field name in ObjectStack (snake_case)'),
-  
+export const FieldMappingSchema = BaseFieldMappingSchema.extend({
   /**
-   * Data type mapping
+   * Data type mapping (connector-specific)
    */
   dataType: z.enum([
     'string',
@@ -111,17 +108,7 @@ export const FieldMappingSchema = z.object({
   required: z.boolean().default(false).describe('Field is required'),
 
   /**
-   * Default value if source is empty
-   */
-  defaultValue: z.any().optional().describe('Default value'),
-  
-  /**
-   * Field transformation rules
-   */
-  transform: FieldTransformSchema.optional().describe('Field transformation'),
-  
-  /**
-   * Bidirectional sync mode
+   * Bidirectional sync mode (connector-specific)
    */
   syncMode: z.enum([
     'read_only',      // Only sync from external to ObjectStack

packages/spec/src/shared/index.ts

@@ -4,3 +4,4 @@
  */
 
 export * from './identifiers.zod';
+export * from './mapping.zod';

packages/spec/src/shared/mapping.zod.ts

@@ -0,0 +1,114 @@
+import { z } from 'zod';
+
+/**
+ * Base Field Mapping Protocol
+ * 
+ * Shared by: ETL, Sync, Connector, External Lookup
+ * 
+ * This module provides the canonical field mapping schema used across
+ * ObjectStack for data transformation and synchronization.
+ * 
+ * **Use Cases:**
+ * - ETL pipelines (data/mapping.zod.ts)
+ * - Data synchronization (automation/sync.zod.ts)
+ * - Integration connectors (integration/connector.zod.ts)
+ * - External lookups (data/external-lookup.zod.ts)
+ * 
+ * @example Basic field mapping
+ * ```typescript
+ * const mapping: FieldMapping = {
+ *   source: 'external_user_id',
+ *   target: 'user_id',
+ * };
+ * ```
+ * 
+ * @example With transformation
+ * ```typescript
+ * const mapping: FieldMapping = {
+ *   source: 'user_name',
+ *   target: 'name',
+ *   transform: { type: 'cast', targetType: 'string' },
+ *   defaultValue: 'Unknown'
+ * };
+ * ```
+ */
+
+/**
+ * Transform Type Schema
+ * 
+ * Defines the type of transformation to apply to a field value.
+ * Implementations can extend this for domain-specific transforms.
+ */
+export const TransformTypeSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('constant'),
+    value: z.any().describe('Constant value to use'),
+  }).describe('Set a constant value'),
+  
+  z.object({
+    type: z.literal('cast'),
+    targetType: z.enum(['string', 'number', 'boolean', 'date']).describe('Target data type'),
+  }).describe('Cast to a specific data type'),
+  
+  z.object({
+    type: z.literal('lookup'),
+    table: z.string().describe('Lookup table name'),
+    keyField: z.string().describe('Field to match on'),
+    valueField: z.string().describe('Field to retrieve'),
+  }).describe('Lookup value from another table'),
+  
+  z.object({
+    type: z.literal('javascript'),
+    expression: z.string().describe('JavaScript expression (e.g., "value.toUpperCase()")'),
+  }).describe('Custom JavaScript transformation'),
+  
+  z.object({
+    type: z.literal('map'),
+    mappings: z.record(z.any()).describe('Value mappings (e.g., {"Active": "active"})'),
+  }).describe('Map values using a dictionary'),
+]);
+
+export type TransformType = z.infer<typeof TransformTypeSchema>;
+
+/**
+ * Field Mapping Schema
+ * 
+ * Base schema for mapping fields between source and target systems.
+ * 
+ * **NAMING CONVENTION:**
+ * - source: Field name in the source system
+ * - target: Field name in the target system (should be snake_case for ObjectStack)
+ * 
+ * @example
+ * ```typescript
+ * {
+ *   source: 'FirstName',
+ *   target: 'first_name',
+ *   transform: { type: 'cast', targetType: 'string' },
+ *   defaultValue: ''
+ * }
+ * ```
+ */
+export const FieldMappingSchema = z.object({
+  /**
+   * Source field name
+   */
+  source: z.string().describe('Source field name'),
+  
+  /**
+   * Target field name (should be snake_case for ObjectStack)
+   */
+  target: z.string().describe('Target field name'),
+  
+  /**
+   * Transformation to apply
+   */
+  transform: TransformTypeSchema.optional().describe('Transformation to apply'),
+  
+  /**
+   * Default value if source is null/undefined
+   */
+  defaultValue: z.any().optional().describe('Default if source is null/undefined'),
+});
+
+export type FieldMapping = z.infer<typeof FieldMappingSchema>;