role.zod.ts

import { z } from 'zod';
import { SnakeCaseIdentifierSchema } from '../shared/identifiers.zod';

/**
 * Role Schema (aka Business Unit / Org Unit)
 * Defines the organizational hierarchy (Reporting Structure).
 * 
 * COMPARISON:
 * - Salesforce: "Role" (Hierarchy for visibility rollup)
 * - Microsoft: "Business Unit" (Structural container for data)
 * - Kubernetes/AWS: "Role" usually refers to Permissions (we use PermissionSet for that)
 * 
 * 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: SnakeCaseIdentifierSchema.describe('Unique role name (lowercase snake_case)'),
  label: z.string().describe('Display label (e.g. VP of Sales)'),
  
  /** Hierarchy */
  parent: z.string().optional().describe('Parent Role ID (Reports To)'),
  
  /** Description */
  description: z.string().optional(),
});

export type Role = z.infer<typeof RoleSchema>;