Naming Conventions for ABS Platform

Overview

This document establishes consistent naming conventions for FSM states, inputs, outputs, and Z-Agent callback functions across the ABS Platform. These conventions ensure readability, maintainability, and consistency in the codebase.

FSM Naming Conventions

1. States (snake_case, UPPER_CASE)

Format: snake_case with UPPER_CASE for emphasis

Examples:

// Payment States
'UP_TO_DATE'           // All payments current
'PAR_30'               // Payment 30+ days past due
'PAR_60'               // Payment 60+ days past due
'PAR_90'               // Payment 90+ days past due
'OVERDUE'              // Payment severely overdue

// Service States
'PENDING_ACTIVATION'   // Service plan created, awaiting payment
'ACTIVE'               // Service is operational and available
'SUSPENDED_PAYMENT'    // Service suspended due to payment issues
'SUSPENDED_QUOTA'      // Service suspended due to quota exhaustion
'EXPIRED'              // Service plan has expired
'CANCELLED'            // Service has been cancelled

// System States
'IDLE'                 // System idle state
'RUNNING'              // System running state
'PAUSED'               // System paused state
'ERROR'                // System error state
'MAINTENANCE'          // System maintenance state
'OFFLINE'              // System offline state

Rules: - Use UPPER_CASE with snake_case separators - Use descriptive, action-oriented names - Avoid abbreviations unless universally understood - Group related states with common prefixes

2. Inputs (snake_case, UPPER_CASE)

Format: snake_case with UPPER_CASE for emphasis

Examples:

// Payment Inputs
'PAYMENT_RECEIVED'     // Payment was received
'PAYMENT_FAILED'       // Payment attempt failed
'PAYMENT_OVERDUE'      // Payment is overdue
'SERVICE_ACTIVATED'    // Service was activated

// Service Inputs
'QUOTA_EXHAUSTED'      // Service quota has been exhausted
'SERVICE_ACCESSED'     // Service was accessed
'SERVICE_EXPIRED'      // Service has expired
'PAYMENT_OVERDUE'      // Payment is overdue

// System Inputs
'START'                // Start the system
'STOP'                 // Stop the system
'PAUSE'                // Pause the system
'RESUME'               // Resume the system
'ERROR'                // System error occurred
'FIX'                  // Fix the system
'RESET'                // Reset the system (wildcard)
'EMERGENCY_STOP'       // Emergency stop (wildcard)
'SHUTDOWN'             // System shutdown (wildcard)

Rules: - Use UPPER_CASE with snake_case separators - Use present tense, action-oriented verbs - Be specific about the action being performed - Use consistent verb forms across related inputs

3. Outputs (snake_case, UPPER_CASE)

Format: snake_case with UPPER_CASE for emphasis

Examples:

// Payment Outputs
'PAYMENT_RECEIVED'     // Payment received signal
'PAYMENT_OVERDUE'      // Payment overdue signal
'PAYMENT_FAILED'       // Payment failed signal
'SERVICE_SUSPENDED'    // Service suspended signal
'SERVICE_RESUMED'      // Service resumed signal

// Service Outputs
'SERVICE_ACTIVATED'    // Service activated signal
'SERVICE_SUSPENDED'    // Service suspended signal
'SERVICE_RESUMED'      // Service resumed signal
'SERVICE_EXPIRED'      // Service expired signal

// System Outputs
'ENABLE'               // Enable system signal
'DISABLE'              // Disable system signal
'PAUSE_SIGNAL'         // Pause system signal
'RESUME_SIGNAL'        // Resume system signal
'ERROR_ALARM'          // Error alarm signal
'FIX_SIGNAL'           // Fix system signal
'RESET_SIGNAL'         // Reset system signal
'EMERGENCY_STOP'       // Emergency stop signal
'SHUTDOWN_SIGNAL'      // Shutdown system signal
'SAVE_STATE'           // Save system state signal

Rules: - Use UPPER_CASE with snake_case separators - Use noun forms or past tense verbs - Be descriptive about the signal being emitted - Use consistent naming patterns across related outputs

Z-Agent Naming Conventions

1. Z-Agent Types (PascalCase)

Format: PascalCase with descriptive type names

Examples:

// Specific Z-Agent Types
NumberZAgent           // For numeric state management
StringZAgent           // For string state management
StringArrayZAgent      // For string array state management
BooleanZAgent          // For boolean state management
DateTimeZAgent         // For datetime state management
CountZAgent            // For count/integer state management

// Custom Z-Agent Types
TimeoutAgent           // For timeout management
RetryCounterAgent      // For retry counting
PaymentBufferAgent     // For payment history tracking
QuotaTrackerAgent      // For quota tracking

2. Z-Agent Instances (camelCase)

Format: camelCase with descriptive names

Examples:

// Z-Agent Instance Names
timeoutAgent           // Timeout management agent
retryCounterAgent      // Retry counting agent
paymentBufferAgent     // Payment history agent
quotaTrackerAgent      // Quota tracking agent
sessionTimeoutAgent    // Session timeout agent
billingCycleAgent      // Billing cycle agent

3. Z-Agent Callback Functions (camelCase)

Format: camelCase with descriptive, action-oriented names

Examples:

// Transition Callback Functions (ψ₁ functions)
handleTimeoutTransition        // Handle timeout state transition
processRetryCountTransition    // Process retry count changes
updatePaymentBufferTransition  // Update payment buffer on transition
trackQuotaUsageTransition      // Track quota usage changes
manageSessionTimeoutTransition // Manage session timeout logic

// Direct Set Callback Functions (ψ₀ functions)
generateTimeoutSignal          // Generate timeout signal
emitRetryExceededSignal        // Emit retry exceeded signal
triggerPaymentPatternSignal    // Trigger payment pattern detection
sendQuotaExhaustedSignal       // Send quota exhausted signal
broadcastSessionExpiredSignal  // Broadcast session expired signal

// State Update Functions (φ functions)
updateTimeoutState             // Update timeout state
incrementRetryCount            // Increment retry counter
appendPaymentRecord            // Append payment to buffer
decrementQuotaRemaining        // Decrement remaining quota
extendSessionTimeout           // Extend session timeout

Rules: - Use camelCase for function names - Use descriptive, action-oriented verbs - Include the type of operation (transition, signal, update) - Be specific about what the callback does

Implementation Examples

1. FSM Template with Proper Naming

const paymentFSMTemplate = {
  id: 'payment_fsm_template',
  name: 'Standard Payment Cycle FSM',
  description: 'Handles payment status transitions',
  states: [
    'UP_TO_DATE',
    'PAR_30',
    'PAR_60', 
    'PAR_90',
    'OVERDUE'
  ],
  inputs: [
    'PAYMENT_RECEIVED',
    'PAYMENT_FAILED',
    'PAYMENT_OVERDUE',
    'SERVICE_ACTIVATED'
  ],
  outputs: [
    'PAYMENT_RECEIVED',
    'PAYMENT_OVERDUE',
    'PAYMENT_FAILED',
    'SERVICE_SUSPENDED',
    'SERVICE_RESUMED'
  ],
  initial: 'UP_TO_DATE',
  transitions: [
    {
      id: 'payment_overdue_30',
      from: 'UP_TO_DATE',
      input: 'PAYMENT_OVERDUE',
      to: 'PAR_30',
      outputs: ['PAYMENT_OVERDUE'],
      description: 'Payment becomes 30 days past due',
      priority: 1
    },
    {
      id: 'payment_received_reset',
      from: 'PAR_30',
      input: 'PAYMENT_RECEIVED',
      to: 'UP_TO_DATE',
      outputs: ['PAYMENT_RECEIVED', 'SERVICE_RESUMED'],
      description: 'Payment received, return to up to date',
      priority: 1
    }
  ]
};

2. Z-Agent with Proper Callback Naming

// Z-Agent Configuration
const timeoutAgentConfig: ZAgentConfig<number, string, string> = {
  name: 'Timeout Agent',
  description: 'Manages timeout countdown logic',
  initial: 0,
  update: updateTimeoutState,  // φ function
  test: checkTimeoutCondition  // Test function
};

// State Update Function (φ)
function updateTimeoutState(z: number, output: string): number {
  if (output === 'START_TIMEOUT') return 30;
  if (output === 'DECREMENT_RETRY') return Math.max(0, z - 1);
  if (output === 'RESET_RETRY') return 0;
  return z;
}

// Transition Callback Function (ψ₁)
function handleTimeoutTransition(z: number, output: string | null): Set<string> {
  const signals = new Set<string>();

  if (z === 0 && output === 'DECREMENT_RETRY') {
    signals.add('TIMEOUT');
  }

  return signals;
}

// Direct Set Callback Function (ψ₀)
function generateTimeoutSignal(z: number): Set<string> {
  const signals = new Set<string>();

  if (z === 0) {
    signals.add('TIMEOUT');
  }

  return signals;
}

3. FSM-Z-Agent Integration with Proper Naming

// Create Z-Agent instances with proper naming
const timeoutAgent = createZAgentInstance(timeoutAgentConfig);
const retryCounterAgent = createZAgentInstance(retryCounterAgentConfig);
const paymentBufferAgent = createZAgentInstance(paymentBufferAgentConfig);

// Register callbacks with descriptive names
registerTransitionCallback(timeoutAgent, handleTimeoutTransition);
registerTransitionCallback(retryCounterAgent, processRetryCountTransition);
registerTransitionCallback(paymentBufferAgent, updatePaymentBufferTransition);

// Process FSM outputs through Z-Agents
for (const fsmOutput of fsmResult.outputs) {
  if (['START_TIMEOUT', 'DECREMENT_RETRY', 'RESET_RETRY'].includes(fsmOutput)) {
    const timeoutSignals = processZAgent(timeoutAgent, fsmOutput);
    // Handle timeout signals...
  }
}

Constants and Enums

1. State Constants

// Payment States
export const PAYMENT_STATES = [
  'UP_TO_DATE',
  'PAR_30',
  'PAR_60', 
  'PAR_90',
  'OVERDUE'
] as const;

// Service States
export const SERVICE_STATES = [
  'PENDING_ACTIVATION',
  'ACTIVE',
  'SUSPENDED_PAYMENT',
  'SUSPENDED_QUOTA',
  'EXPIRED',
  'CANCELLED'
] as const;

2. Input Constants

// Payment Inputs
export const PAYMENT_INPUTS = [
  'PAYMENT_RECEIVED',
  'PAYMENT_FAILED',
  'PAYMENT_OVERDUE',
  'SERVICE_ACTIVATED'
] as const;

// Service Inputs
export const SERVICE_INPUTS = [
  'PAYMENT_RECEIVED',
  'PAYMENT_OVERDUE',
  'QUOTA_EXHAUSTED',
  'SERVICE_ACCESSED',
  'SERVICE_EXPIRED'
] as const;

3. Output Constants

// Payment Outputs
export const PAYMENT_OUTPUTS = [
  'PAYMENT_RECEIVED',
  'PAYMENT_OVERDUE',
  'PAYMENT_FAILED',
  'SERVICE_SUSPENDED',
  'SERVICE_RESUMED'
] as const;

// Service Outputs
export const SERVICE_OUTPUTS = [
  'SERVICE_ACTIVATED',
  'SERVICE_SUSPENDED',
  'SERVICE_RESUMED',
  'SERVICE_EXPIRED'
] as const;

Best Practices

1. Consistency

• Use the same naming pattern across all FSM components
• Maintain consistency between states, inputs, and outputs
• Use consistent verb forms and tenses

2. Clarity

• Choose descriptive names that clearly indicate purpose
• Avoid abbreviations unless universally understood
• Use action-oriented names for inputs and outputs

3. Maintainability

• Group related states, inputs, and outputs with common prefixes
• Use constants for frequently used values
• Document any deviations from the standard conventions

4. Extensibility

• Design naming patterns that can accommodate future additions
• Use hierarchical naming for complex systems
• Consider domain-specific terminology

Migration Guidelines

When updating existing code to follow these conventions:

1. States: Convert to UPPER_CASE with snake_case separators
2. Inputs: Convert to UPPER_CASE with snake_case separators
3. Outputs: Convert to UPPER_CASE with snake_case separators
4. Z-Agent Callbacks: Use descriptive camelCase names
5. Update all references to maintain consistency

Conclusion

These naming conventions provide a solid foundation for consistent, readable, and maintainable FSM and Z-Agent implementations across the ABS Platform. Following these conventions will improve code quality and reduce cognitive load for developers working with the system.