Merge pull request #627 from objectstack-ai/copilot/evaluate-protocol-spec-details

Author: hotlong

packages/spec/src/automation/approval.test.ts

@@ -216,3 +216,85 @@ describe('ApprovalProcess.create', () => {
     expect(result).toEqual(config);
   });
 });
+
+// ============================================================================
+// Protocol Improvement Tests: Approval escalation
+// ============================================================================
+
+describe('ApprovalProcessSchema - escalation', () => {
+  it('should accept approval process with escalation config', () => {
+    const result = ApprovalProcessSchema.parse({
+      name: 'escalated_approval',
+      label: 'Escalated Approval',
+      object: 'purchase_order',
+      steps: [{
+        name: 'manager_review',
+        label: 'Manager Review',
+        approvers: [{ type: 'manager', value: 'direct_manager' }],
+      }],
+      escalation: {
+        enabled: true,
+        timeoutHours: 48,
+        action: 'reassign',
+        escalateTo: 'vp_operations',
+        notifySubmitter: true,
+      },
+    });
+    expect(result.escalation?.enabled).toBe(true);
+    expect(result.escalation?.timeoutHours).toBe(48);
+    expect(result.escalation?.action).toBe('reassign');
+    expect(result.escalation?.escalateTo).toBe('vp_operations');
+  });
+
+  it('should accept escalation with auto_approve action', () => {
+    const result = ApprovalProcessSchema.parse({
+      name: 'auto_escalate',
+      label: 'Auto Escalate',
+      object: 'expense_report',
+      steps: [{
+        name: 'review',
+        label: 'Review',
+        approvers: [{ type: 'user', value: 'finance_team' }],
+      }],
+      escalation: {
+        enabled: true,
+        timeoutHours: 72,
+        action: 'auto_approve',
+      },
+    });
+    expect(result.escalation?.action).toBe('auto_approve');
+  });
+
+  it('should default escalation action to notify', () => {
+    const result = ApprovalProcessSchema.parse({
+      name: 'default_escalation',
+      label: 'Default',
+      object: 'request',
+      steps: [{
+        name: 'step_one',
+        label: 'Step 1',
+        approvers: [{ type: 'role', value: 'approver' }],
+      }],
+      escalation: {
+        enabled: true,
+        timeoutHours: 24,
+      },
+    });
+    expect(result.escalation?.action).toBe('notify');
+    expect(result.escalation?.notifySubmitter).toBe(true);
+  });
+
+  it('should accept approval process without escalation (optional)', () => {
+    const result = ApprovalProcessSchema.parse({
+      name: 'no_escalation',
+      label: 'No Escalation',
+      object: 'task',
+      steps: [{
+        name: 'approve',
+        label: 'Approve',
+        approvers: [{ type: 'user', value: 'admin' }],
+      }],
+    });
+    expect(result.escalation).toBeUndefined();
+  });
+});

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

@@ -91,6 +91,15 @@ export const ApprovalProcessSchema = z.object({
 
   /** Steps */
   steps: z.array(ApprovalStepSchema).min(1).describe('Sequence of approval steps'),
+
+  /** Escalation Configuration (SLA-based auto-escalation) */
+  escalation: z.object({
+    enabled: z.boolean().default(false).describe('Enable SLA-based escalation'),
+    timeoutHours: z.number().min(1).describe('Hours before escalation triggers'),
+    action: z.enum(['reassign', 'auto_approve', 'auto_reject', 'notify']).default('notify').describe('Action to take on escalation timeout'),
+    escalateTo: z.string().optional().describe('User ID, role, or manager level to escalate to'),
+    notifySubmitter: z.boolean().default(true).describe('Notify the original submitter on escalation'),
+  }).optional().describe('SLA escalation configuration for pending approval steps'),
 
   /** Global Actions */
   onSubmit: z.array(ApprovalActionSchema).optional().describe('Actions on initial submission'),

packages/spec/src/automation/flow.test.ts

@@ -525,3 +525,75 @@ describe('FlowSchema', () => {
     });
   });
 });
+
+// ============================================================================
+// Protocol Improvement Tests: Flow errorHandling
+// ============================================================================
+
+describe('FlowSchema - errorHandling', () => {
+  it('should accept flow with errorHandling config', () => {
+    const result = FlowSchema.parse({
+      name: 'resilient_flow',
+      label: 'Resilient Flow',
+      type: 'autolaunched',
+      nodes: [
+        { id: 'start', type: 'start', label: 'Start' },
+        { id: 'end', type: 'end', label: 'End' },
+      ],
+      edges: [{ id: 'e1', source: 'start', target: 'end' }],
+      errorHandling: {
+        strategy: 'retry',
+        maxRetries: 3,
+        retryDelayMs: 2000,
+      },
+    });
+    expect(result.errorHandling?.strategy).toBe('retry');
+    expect(result.errorHandling?.maxRetries).toBe(3);
+    expect(result.errorHandling?.retryDelayMs).toBe(2000);
+  });
+
+  it('should default errorHandling strategy to fail', () => {
+    const result = FlowSchema.parse({
+      name: 'default_flow',
+      label: 'Default',
+      type: 'autolaunched',
+      nodes: [
+        { id: 'start', type: 'start', label: 'Start' },
+      ],
+      edges: [],
+      errorHandling: {},
+    });
+    expect(result.errorHandling?.strategy).toBe('fail');
+    expect(result.errorHandling?.maxRetries).toBe(0);
+  });
+
+  it('should accept continue strategy with fallback node', () => {
+    const result = FlowSchema.parse({
+      name: 'fallback_flow',
+      label: 'Fallback',
+      type: 'autolaunched',
+      nodes: [
+        { id: 'start', type: 'start', label: 'Start' },
+        { id: 'fallback', type: 'end', label: 'Fallback' },
+      ],
+      edges: [],
+      errorHandling: {
+        strategy: 'continue',
+        fallbackNodeId: 'fallback',
+      },
+    });
+    expect(result.errorHandling?.strategy).toBe('continue');
+    expect(result.errorHandling?.fallbackNodeId).toBe('fallback');
+  });
+
+  it('should accept flow without errorHandling (optional)', () => {
+    const result = FlowSchema.parse({
+      name: 'simple_flow',
+      label: 'Simple',
+      type: 'autolaunched',
+      nodes: [{ id: 'start', type: 'start', label: 'Start' }],
+      edges: [],
+    });
+    expect(result.errorHandling).toBeUndefined();
+  });
+});

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

@@ -137,6 +137,14 @@ export const FlowSchema = z.object({
   /** Execution Config */
   active: z.boolean().default(false).describe('Is active (Deprecated: use status)'),
   runAs: z.enum(['system', 'user']).default('user').describe('Execution context'),
+
+  /** Error Handling Strategy */
+  errorHandling: z.object({
+    strategy: z.enum(['fail', 'retry', 'continue']).default('fail').describe('How to handle node execution errors'),
+    maxRetries: z.number().int().min(0).max(10).default(0).describe('Number of retry attempts (only for retry strategy)'),
+    retryDelayMs: z.number().int().min(0).default(1000).describe('Delay between retries in milliseconds'),
+    fallbackNodeId: z.string().optional().describe('Node ID to jump to on unrecoverable error'),
+  }).optional().describe('Flow-level error handling configuration'),
 });
 
 export type Flow = z.input<typeof FlowSchema>;

packages/spec/src/automation/workflow.test.ts

@@ -445,3 +445,38 @@ describe('WorkflowRuleSchema', () => {
     expect(() => WorkflowRuleSchema.parse(rule)).toThrow();
   });
 });
+
+// ============================================================================
+// Protocol Improvement Tests: Workflow executionOrder
+// ============================================================================
+
+describe('WorkflowRuleSchema - executionOrder', () => {
+  it('should accept workflow with custom executionOrder', () => {
+    const result = WorkflowRuleSchema.parse({
+      name: 'first_workflow',
+      objectName: 'order',
+      triggerType: 'on_create',
+      executionOrder: 10,
+    });
+    expect(result.executionOrder).toBe(10);
+  });
+
+  it('should default executionOrder to 100', () => {
+    const result = WorkflowRuleSchema.parse({
+      name: 'default_order',
+      objectName: 'order',
+      triggerType: 'on_create',
+    });
+    expect(result.executionOrder).toBe(100);
+  });
+
+  it('should accept executionOrder of 0', () => {
+    const result = WorkflowRuleSchema.parse({
+      name: 'first_ever',
+      objectName: 'lead',
+      triggerType: 'on_update',
+      executionOrder: 0,
+    });
+    expect(result.executionOrder).toBe(0);
+  });
+});

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

@@ -267,6 +267,9 @@ export const WorkflowRuleSchema = z.object({
 
   /** Active status */
   active: z.boolean().default(true).describe('Whether this workflow is active'),
+
+  /** Execution Order */
+  executionOrder: z.number().int().min(0).default(100).describe('Deterministic execution order when multiple workflows match (lower runs first)'),
 
   /** Recursion Control */
   reevaluateOnChange: z.boolean().default(false).describe('Re-evaluate rule if field updates change the record validity'),

packages/spec/src/data/datasource.test.ts

@@ -417,3 +417,60 @@ describe('DatasourceSchema', () => {
     })).toThrow();
   });
 });
+
+// ============================================================================
+// Protocol Improvement Tests: Datasource SSL
+// ============================================================================
+
+describe('DatasourceSchema - ssl', () => {
+  it('should accept datasource with SSL config', () => {
+    const result = DatasourceSchema.parse({
+      name: 'secure_db',
+      driver: 'postgres',
+      config: { host: 'db.example.com', port: 5432 },
+      ssl: {
+        enabled: true,
+        rejectUnauthorized: true,
+        ca: '/path/to/ca.pem',
+      },
+    });
+    expect(result.ssl?.enabled).toBe(true);
+    expect(result.ssl?.rejectUnauthorized).toBe(true);
+    expect(result.ssl?.ca).toBe('/path/to/ca.pem');
+  });
+
+  it('should accept SSL with client certificates', () => {
+    const result = DatasourceSchema.parse({
+      name: 'mtls_db',
+      driver: 'postgres',
+      config: { host: 'db.secure.com' },
+      ssl: {
+        enabled: true,
+        ca: '/certs/ca.pem',
+        cert: '/certs/client.pem',
+        key: '/certs/client-key.pem',
+      },
+    });
+    expect(result.ssl?.cert).toBe('/certs/client.pem');
+    expect(result.ssl?.key).toBe('/certs/client-key.pem');
+  });
+
+  it('should default rejectUnauthorized to true', () => {
+    const result = DatasourceSchema.parse({
+      name: 'ssl_db',
+      driver: 'mysql',
+      config: {},
+      ssl: { enabled: true },
+    });
+    expect(result.ssl?.rejectUnauthorized).toBe(true);
+  });
+
+  it('should accept datasource without SSL (optional)', () => {
+    const result = DatasourceSchema.parse({
+      name: 'local_db',
+      driver: 'sqlite',
+      config: { path: './data.db' },
+    });
+    expect(result.ssl).toBeUndefined();
+  });
+});

packages/spec/src/data/datasource.zod.ts

@@ -139,6 +139,15 @@ export const DatasourceSchema = z.object({
     timeoutMs: z.number().default(5000).describe('Health check timeout in milliseconds'),
   }).optional().describe('Datasource health check configuration'),
 
+  /** SSL/TLS Configuration */
+  ssl: z.object({
+    enabled: z.boolean().default(false).describe('Enable SSL/TLS for database connection'),
+    rejectUnauthorized: z.boolean().default(true).describe('Reject connections with invalid/self-signed certificates'),
+    ca: z.string().optional().describe('CA certificate (PEM format or path to file)'),
+    cert: z.string().optional().describe('Client certificate (PEM format or path to file)'),
+    key: z.string().optional().describe('Client private key (PEM format or path to file)'),
+  }).optional().describe('SSL/TLS configuration for secure database connections'),
+
   /** Retry Policy */
   retryPolicy: z.object({
     maxRetries: z.number().default(3).describe('Maximum number of retry attempts'),

packages/spec/src/data/field.test.ts

@@ -1385,3 +1385,51 @@ describe('Field Factory Helpers', () => {
     });
   });
 });
+
+// ============================================================================
+// Protocol Improvement Tests: Field group and conditionalRequired
+// ============================================================================
+
+describe('FieldSchema - group property', () => {
+  it('should accept a field with group', () => {
+    const result = FieldSchema.parse({
+      type: 'text',
+      group: 'contact_info',
+    });
+    expect(result.group).toBe('contact_info');
+  });
+
+  it('should accept a field without group (optional)', () => {
+    const result = FieldSchema.parse({
+      type: 'text',
+    });
+    expect(result.group).toBeUndefined();
+  });
+});
+
+describe('FieldSchema - conditionalRequired property', () => {
+  it('should accept a field with conditionalRequired formula', () => {
+    const result = FieldSchema.parse({
+      type: 'text',
+      conditionalRequired: "status = 'closed_won'",
+    });
+    expect(result.conditionalRequired).toBe("status = 'closed_won'");
+  });
+
+  it('should accept a field without conditionalRequired (optional)', () => {
+    const result = FieldSchema.parse({
+      type: 'text',
+    });
+    expect(result.conditionalRequired).toBeUndefined();
+  });
+
+  it('should allow combining required and conditionalRequired', () => {
+    const result = FieldSchema.parse({
+      type: 'text',
+      required: false,
+      conditionalRequired: 'amount > 1000',
+    });
+    expect(result.required).toBe(false);
+    expect(result.conditionalRequired).toBe('amount > 1000');
+  });
+});

packages/spec/src/data/field.zod.ts

@@ -449,6 +449,12 @@ export const FieldSchema = z.object({
   // Data quality rules
   dataQuality: DataQualityRulesSchema.optional().describe('Data quality validation and monitoring rules'),
 
+  /** Layout & Grouping */
+  group: z.string().optional().describe('Field group name for organizing fields in forms and layouts (e.g., "contact_info", "billing", "system")'),
+
+  /** Conditional Requirements */
+  conditionalRequired: z.string().optional().describe('Formula expression that makes this field required when TRUE (e.g., "status = \'closed_won\'")'),
+
   /** Security & Visibility */
   hidden: z.boolean().default(false).describe('Hidden from default UI'),
   readonly: z.boolean().default(false).describe('Read-only in UI'),