FSM Initial State Enforcement¶

Overview¶

The ABS Platform enforces that ServicePlan instances must initialize their FSM states (service_state and payment_state) to match the initial_state defined in their respective FSM definitions. This ensures system integrity and prevents invalid state transitions.

Problem Statement¶

Before Enforcement: - ServicePlan creation could set arbitrary initial states - No validation that states exist in FSM definitions - Risk of runtime errors when FSM engine encounters invalid states - Inconsistent behavior across different ServicePlan instances

After Enforcement: - ServicePlan states are automatically initialized to FSM initial_state - Comprehensive validation during creation - Guaranteed system integrity - Consistent behavior across all ServicePlan instances

Implementation¶

1. Schema Definition¶

type MealyFSM {
  id: ID!
  name: String!
  description: String
  states: [String!]!
  inputs: [String!]!
  outputs: [String!]!
  initial_state: String!  # ← REQUIRED field
  transitions: [MealyTransition!]!
}

type ServicePlan {
  # ... other fields ...
  service_state: String!  # ← Must match service_cycle_fsm.initial_state
  payment_state: String!  # ← Must match payment_cycle_fsm.initial_state
}

2. ServicePlan Creation Flow¶

// ServicePlanService.createServicePlan()
async function createServicePlan(input: ServicePlanCreationInput) {
  // 1. Load template
  const template = await loadTemplate(input.template_id);

  // 2. Load FSM definitions
  const serviceFSM = await loadFSM(template.service_cycle_fsm_id);
  const paymentFSM = await loadFSM(template.payment_cycle_fsm_id);

  // 3. Validate FSM initial states
  validateFSMInitialStates(serviceFSM, paymentFSM);

  // 4. Create ServicePlan with enforced initial states
  const servicePlan = {
    // ... other fields ...
    service_state: serviceFSM.initial_state,  // ← ENFORCED
    payment_state: paymentFSM.initial_state,  // ← ENFORCED
  };

  // 5. Validate the created ServicePlan
  validateServicePlanStates(servicePlan, serviceFSM, paymentFSM);

  return servicePlan;
}

3. Validation Rules¶

FSM Definition Validation¶

initial_state must be defined
initial_state must exist in states array
FSM must be loadable and valid

ServicePlan State Validation¶

service_state must equal service_cycle_fsm.initial_state
payment_state must equal payment_cycle_fsm.initial_state
Both states must exist in their respective FSM definitions

Template Validation¶

Template must reference valid FSM definitions
FSM references must be resolvable
Template version pinning ensures consistency

Error Handling¶

Validation Errors (Block Creation)¶

// FSM missing initial_state
"Service FSM missing initial_state: bss-service-v1"

// Invalid initial_state
"Service FSM initial_state 'INVALID_STATE' not found in states list: INITIAL, ACTIVE, SUSPENDED"

// Template references invalid FSM
"Service FSM not found: bss-service-v1"

Warnings (Allow Creation)¶

// Same initial states (potential confusion)
"Service and Payment FSMs have same initial state: INITIAL"

Example Usage¶

Creating ServicePlan from Template¶

mutation {
  createServicePlanFromTemplate(input: {
    template_id: "template-bss-v1"
    customer_id: "customer-123"
  }) {
    cloned_plan {
      id
      service_state    # ← Will be "INITIAL" (from FSM definition)
      payment_state    # ← Will be "INITIAL" (from FSM definition)
      template_id
      template_version
    }
  }
}

Expected Result¶

{
  "data": {
    "createServicePlanFromTemplate": {
      "cloned_plan": {
        "id": "plan-1234567890-abc123def",
        "service_state": "INITIAL",    # ← Enforced from FSM
        "payment_state": "INITIAL",    # ← Enforced from FSM
        "template_id": "template-bss-v1",
        "template_version": "1.0.0"
      }
    }
  }
}

FSM Definition Example¶

{
  "payment_cycle": {
    "id": "bss-payment-v1",
    "name": "BSS Payment Cycle",
    "states": ["INITIAL", "CURRENT", "OVERDUE", "COMPLETE"],
    "initial_state": "INITIAL",  # ← ServicePlan payment_state will be "INITIAL"
    "inputs": ["PAYMENT_RECEIVED", "PAYMENT_OVERDUE", "FINAL_PAYMENT"],
    "outputs": ["PAYMENT_CONFIRMED", "PAYMENT_OVERDUE_SIGNAL", "PAYMENT_COMPLETED"],
    "transitions": [...]
  },
  "service_cycle": {
    "id": "bss-service-v1", 
    "name": "BSS Service Cycle",
    "states": ["INITIAL", "ACTIVE", "SUSPENDED", "COMPLETE"],
    "initial_state": "INITIAL",  # ← ServicePlan service_state will be "INITIAL"
    "inputs": ["ACTIVATE", "SUSPEND", "RESUME", "COMPLETE"],
    "outputs": ["SERVICE_ACTIVATED", "SERVICE_SUSPENDED", "SERVICE_RESUMED", "SERVICE_COMPLETED"],
    "transitions": [...]
  }
}

Benefits¶

1. System Integrity¶

Prevents invalid state transitions
Ensures FSM engine always has valid states
Eliminates runtime state-related errors

2. Consistency¶

All ServicePlan instances start in same state
Predictable behavior across system
Easier debugging and monitoring

3. Validation¶

Early detection of FSM definition issues
Clear error messages for developers
Prevents deployment of invalid configurations

4. Maintainability¶

Clear separation of concerns
FSM definitions drive ServicePlan behavior
Template version pinning ensures stability

Testing¶

Unit Tests¶

FSM initial state validation
ServicePlan state enforcement
Error handling scenarios
Warning generation

Integration Tests¶

End-to-end ServicePlan creation
Real FSM definition loading
Template validation flow

Example Test¶

test('should enforce FSM initial states during ServicePlan creation', async () => {
  const result = await ServicePlanService.createServicePlan(input);

  expect(result.service_plan.service_state).toBe('INITIAL');  // ← ENFORCED
  expect(result.service_plan.payment_state).toBe('INITIAL');  // ← ENFORCED
});

Migration Considerations¶

Existing ServicePlans¶

No automatic migration required
Existing plans continue to work
New plans will use enforced initial states

FSM Definition Updates¶

Adding initial_state to existing FSMs
Validating all existing FSM definitions
Updating templates to reference valid FSMs

Template Versioning¶

New template versions can reference updated FSMs
Existing ServicePlans remain on original template version
Gradual migration through template updates

Future Enhancements¶

1. State Migration¶

Tools to migrate existing ServicePlans to correct initial states
Validation of existing ServicePlan states against FSM definitions

2. Enhanced Validation¶

Cross-FSM state compatibility checking
State transition path validation
Performance impact analysis

3. Monitoring¶

Alerting on ServicePlan state mismatches
Metrics on FSM state transitions
Health checks for FSM definitions

Conclusion¶

FSM initial state enforcement ensures that ServicePlan instances are always created with valid, consistent states that match their FSM definitions. This provides a solid foundation for reliable state machine operation and prevents a wide range of potential runtime errors.

The implementation is comprehensive, providing both validation during creation and clear error messages for developers. The system maintains backward compatibility while ensuring all new ServicePlans follow the enforced pattern.