Add SystemIdentifierSchema and update core schemas to enforce lowercase naming

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

Author: Copilot

packages/spec/src/auth/role.test.ts

@@ -13,12 +13,12 @@ describe('RoleSchema', () => {
     });
 
     it('should enforce snake_case for role name', () => {
-      const validNames = ['ceo', 'vp_sales', 'sales_manager', 'account_exec', '_internal'];
+      const validNames = ['ceo', 'vp_sales', 'sales_manager', 'account_exec'];
       validNames.forEach(name => {
         expect(() => RoleSchema.parse({ name, label: 'Test' })).not.toThrow();
       });
 
-      const invalidNames = ['CEO', 'VP-Sales', 'salesManager', '123role'];
+      const invalidNames = ['CEO', 'VP-Sales', 'salesManager', '123role', '_internal'];
       invalidNames.forEach(name => {
         expect(() => RoleSchema.parse({ name, label: 'Test' })).toThrow();
       });

packages/spec/src/auth/role.zod.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { SnakeCaseIdentifierSchema } from '../shared/identifiers.zod';
 
 /**
  * Role Schema (aka Business Unit / Org Unit)
@@ -11,10 +12,24 @@ import { z } from 'zod';
  * 
  * ROLES IN OBJECTSTACK:
  * Used primarily for "Reporting Structure" - Managers see subordinates' data.
+ * 
+ * **NAMING CONVENTION:**
+ * Role names MUST be lowercase snake_case to prevent security issues.
+ * 
+ * @example Good role names
+ * - 'sales_manager'
+ * - 'ceo'
+ * - 'region_east_vp'
+ * - 'engineering_lead'
+ * 
+ * @example Bad role names (will be rejected)
+ * - 'SalesManager' (camelCase)
+ * - 'CEO' (uppercase)
+ * - 'Region East VP' (spaces and uppercase)
  */
 export const RoleSchema = z.object({
   /** Identity */
-  name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Unique role name'),
+  name: SnakeCaseIdentifierSchema.describe('Unique role name (lowercase snake_case)'),
   label: z.string().describe('Display label (e.g. VP of Sales)'),
 
   /** Hierarchy */

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

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { SnakeCaseIdentifierSchema } from '../shared/identifiers.zod';
 
 /**
  * Webhook Trigger Event
@@ -14,10 +15,22 @@ export const WebhookTriggerType = z.enum([
 
 /**
  * Webhook Schema
- * outbound Integration: Push data to external URL when events happen.
+ * Outbound Integration: Push data to external URL when events happen.
+ * 
+ * **NAMING CONVENTION:**
+ * Webhook names are machine identifiers and must be lowercase snake_case.
+ * 
+ * @example Good webhook names
+ * - 'stripe_payment_sync'
+ * - 'slack_notification'
+ * - 'crm_lead_export'
+ * 
+ * @example Bad webhook names (will be rejected)
+ * - 'StripePaymentSync' (PascalCase)
+ * - 'slackNotification' (camelCase)
  */
 export const WebhookSchema = z.object({
-  name: z.string().regex(/^[a-z_][a-z0-9_]*$/),
+  name: SnakeCaseIdentifierSchema.describe('Webhook unique name (lowercase snake_case)'),
   label: z.string().optional(),
 
   /** Scope */
@@ -44,9 +57,20 @@ export const WebhookSchema = z.object({
 /**
  * Webhook Receiver Schema (Inbound)
  * Handling incoming HTTP hooks from Stripe, Slack, etc.
+ * 
+ * **NAMING CONVENTION:**
+ * Webhook receiver names are machine identifiers and must be lowercase snake_case.
+ * 
+ * @example Good names
+ * - 'stripe_webhook_handler'
+ * - 'github_events'
+ * - 'twilio_status_callback'
+ * 
+ * @example Bad names (will be rejected)
+ * - 'StripeWebhookHandler' (PascalCase)
  */
 export const WebhookReceiverSchema = z.object({
-  name: z.string().regex(/^[a-z_][a-z0-9_]*$/),
+  name: SnakeCaseIdentifierSchema.describe('Webhook receiver unique name (lowercase snake_case)'),
   path: z.string().describe('URL Path (e.g. /webhooks/stripe)'),
 
   /** Verification */

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

@@ -527,7 +527,7 @@ describe('WorkflowRuleSchema', () => {
     });
 
     it('should enforce snake_case for workflow name', () => {
-      const validNames = ['auto_approve', 'send_notification', 'update_status', '_internal'];
+      const validNames = ['auto_approve', 'send_notification', 'update_status'];
       validNames.forEach(name => {
         expect(() => WorkflowRuleSchema.parse({
           name,
@@ -536,7 +536,7 @@ describe('WorkflowRuleSchema', () => {
         })).not.toThrow();
       });
 
-      const invalidNames = ['autoApprove', 'Auto-Approve', '123workflow'];
+      const invalidNames = ['autoApprove', 'Auto-Approve', '123workflow', '_internal'];
       invalidNames.forEach(name => {
         expect(() => WorkflowRuleSchema.parse({
           name,

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

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { SnakeCaseIdentifierSchema } from '../shared/identifiers.zod';
 
 /**
  * Trigger events for workflow automation
@@ -182,10 +183,24 @@ export const TimeTriggerSchema = z.object({
 
 /**
  * Schema for Workflow Rules (Automation)
+ * 
+ * **NAMING CONVENTION:**
+ * Workflow names are machine identifiers and must be lowercase snake_case.
+ * 
+ * @example Good workflow names
+ * - 'send_welcome_email'
+ * - 'update_lead_status'
+ * - 'notify_manager_on_close'
+ * - 'calculate_discount'
+ * 
+ * @example Bad workflow names (will be rejected)
+ * - 'SendWelcomeEmail' (PascalCase)
+ * - 'updateLeadStatus' (camelCase)
+ * - 'Send Welcome Email' (spaces)
  */
 export const WorkflowRuleSchema = z.object({
   /** Machine name */
-  name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Unique workflow name'),
+  name: SnakeCaseIdentifierSchema.describe('Unique workflow name (lowercase snake_case)'),
 
   /** Target Object */
   objectName: z.string().describe('Target Object'),

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

@@ -429,7 +429,7 @@ describe('Field Factory Helpers', () => {
       expect(selectField.type).toBe('select');
       expect(selectField.label).toBe('Priority');
       expect(selectField.options).toHaveLength(3);
-      expect(selectField.options[0]).toEqual({ label: 'High', value: 'High' });
+      expect(selectField.options[0]).toEqual({ label: 'High', value: 'high' });
     });
 
     it('should create select field with SelectOption array in config (new API)', () => {
@@ -461,8 +461,8 @@ describe('Field Factory Helpers', () => {
       expect(selectField.type).toBe('select');
       expect(selectField.options).toHaveLength(3);
       expect(selectField.options[0]).toEqual({ label: 'Active', value: 'active', color: '#00AA00' });
-      expect(selectField.options[1]).toEqual({ label: 'Inactive', value: 'Inactive' });
-      expect(selectField.options[2]).toEqual({ label: 'Pending', value: 'Pending' });
+      expect(selectField.options[1]).toEqual({ label: 'Inactive', value: 'inactive' });
+      expect(selectField.options[2]).toEqual({ label: 'Pending', value: 'pending' });
     });
   });
 

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

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { SystemIdentifierSchema } from '../shared/identifiers.zod';
 
 /**
  * Field Type Enum
@@ -38,10 +39,25 @@ export type FieldType = z.infer<typeof FieldType>;
 
 /**
  * Select Option Schema
+ * 
+ * Defines option values for select/picklist fields.
+ * 
+ * **CRITICAL RULE**: The `value` field is a machine identifier that gets stored in the database.
+ * It MUST be lowercase to avoid case-sensitivity issues in queries and comparisons.
+ * 
+ * @example Good
+ * { label: 'New', value: 'new' }
+ * { label: 'In Progress', value: 'in_progress' }
+ * { label: 'Closed Won', value: 'closed_won' }
+ * 
+ * @example Bad (will be rejected)
+ * { label: 'New', value: 'New' } // uppercase
+ * { label: 'In Progress', value: 'In Progress' } // spaces and uppercase
+ * { label: 'Closed Won', value: 'Closed_Won' } // mixed case
  */
 export const SelectOptionSchema = z.object({
-  label: z.string().describe('Display label'),
-  value: z.string().describe('Stored value'),
+  label: z.string().describe('Display label (human-readable, any case allowed)'),
+  value: SystemIdentifierSchema.describe('Stored value (lowercase machine identifier)'),
   color: z.string().optional().describe('Color code for badges/charts'),
   default: z.boolean().optional().describe('Is default option'),
 });
@@ -230,13 +246,28 @@ export const Field = {
   /**
    * Select field helper with backward-compatible API
    * 
-   * @example Old API (array first)
+   * Automatically converts option values to lowercase to enforce naming conventions.
+   * 
+   * @example Old API (array first) - auto-converts to lowercase
    * Field.select(['High', 'Low'], { label: 'Priority' })
+   * // Results in: [{ label: 'High', value: 'high' }, { label: 'Low', value: 'low' }]
    * 
-   * @example New API (config object)
+   * @example New API (config object) - enforces lowercase
    * Field.select({ options: [{label: 'High', value: 'high'}], label: 'Priority' })
+   * 
+   * @example Multi-word values - converts to snake_case
+   * Field.select(['In Progress', 'Closed Won'], { label: 'Status' })
+   * // Results in: [{ label: 'In Progress', value: 'in_progress' }, { label: 'Closed Won', value: 'closed_won' }]
    */
   select: (optionsOrConfig: SelectOption[] | string[] | FieldInput & { options: SelectOption[] | string[] }, config?: FieldInput) => {
+    // Helper function to convert string to lowercase snake_case
+    const toSnakeCase = (str: string): string => {
+      return str
+        .toLowerCase()
+        .replace(/\s+/g, '_')  // Replace spaces with underscores
+        .replace(/[^a-z0-9_.]/g, ''); // Remove invalid characters
+    };
+
     // Support both old and new signatures:
     // Old: Field.select(['a', 'b'], { label: 'X' })
     // New: Field.select({ options: [{label: 'A', value: 'a'}], label: 'X' })
@@ -245,11 +276,19 @@ export const Field = {
 
     if (Array.isArray(optionsOrConfig)) {
       // Old signature: array as first param
-      options = optionsOrConfig.map(o => typeof o === 'string' ? { label: o, value: o } : o);
+      options = optionsOrConfig.map(o => 
+        typeof o === 'string' 
+          ? { label: o, value: toSnakeCase(o) }  // Auto-convert string to snake_case
+          : { ...o, value: o.value.toLowerCase() }  // Ensure value is lowercase
+      );
       finalConfig = config || {};
     } else {
       // New signature: config object with options
-      options = (optionsOrConfig.options || []).map(o => typeof o === 'string' ? { label: o, value: o } : o);
+      options = (optionsOrConfig.options || []).map(o => 
+        typeof o === 'string' 
+          ? { label: o, value: toSnakeCase(o) }  // Auto-convert string to snake_case
+          : { ...o, value: o.value.toLowerCase() }  // Ensure value is lowercase
+      );
       // Remove options from config to avoid confusion
       const { options: _, ...restConfig } = optionsOrConfig;
       finalConfig = restConfig;

packages/spec/src/index.ts

@@ -42,6 +42,7 @@
 // ============================================================================
 // Export protocol domains as namespaces to prevent naming conflicts
 // and establish clear boundaries between different protocol layers.
+export * as Shared from './shared';
 export * as Data from './data';
 export * as Driver from './driver';
 export * as Permission from './permission';

packages/spec/src/permission/permission.zod.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { SnakeCaseIdentifierSchema } from '../shared/identifiers.zod';
 
 /**
  * Entity (Object) Level Permissions
@@ -57,10 +58,24 @@ export const FieldPermissionSchema = z.object({
  * - Profile: The ONE primary functional definition of a user (e.g. Standard User).
  * - Permission Set: Add-on capabilities assigned to users (e.g. Export Reports).
  * - Role: (Defined in src/system/role.zod.ts) Defines data visibility hierarchy.
+ * 
+ * **NAMING CONVENTION:**
+ * Permission set names MUST be lowercase snake_case to prevent security issues.
+ * 
+ * @example Good permission set names
+ * - 'read_only'
+ * - 'system_admin'
+ * - 'standard_user'
+ * - 'api_access'
+ * 
+ * @example Bad permission set names (will be rejected)
+ * - 'ReadOnly' (camelCase)
+ * - 'SystemAdmin' (mixed case)
+ * - 'Read Only' (spaces)
  */
 export const PermissionSetSchema = z.object({
   /** Unique permission set name */
-  name: z.string().describe('Permission set unique name'),
+  name: SnakeCaseIdentifierSchema.describe('Permission set unique name (lowercase snake_case)'),
 
   /** Display label */
   label: z.string().optional().describe('Display label'),