feat: enhance state machine support with parallel lifecycles

- Updated JSON schema for CreateObjectOperation and MigrationOperation to support multiple state machines via `stateMachines` property.
- Added detailed structure for state machines including states, transitions, and actions.
- Modified ObjectSchema to allow coexistence of legacy single state machine and new parallel state machines.
- Enhanced tests to validate the new state machine functionality, ensuring correct initialization and transitions for multiple machines.

Author: hotlong

content/docs/objectql/state-machine.mdx

@@ -145,6 +145,49 @@ import { LeadStateMachine } from './lead.state';
 export const Lead = ObjectSchema.create({
   name: 'lead',
   // ... fields ...
-  stateMachine: LeadStateMachine // Imported config
+  stateMachines: {
+    lifecycle: LeadStateMachine, // Named key for the primary lifecycle
+  }
 });
 ```
+
+## Multiple State Machines (Parallel Lifecycles)
+
+In real enterprise systems, a single object often has **multiple independent state lines**. For example, an `Order` has:
+
+- **`lifecycle`** — `draft → submitted → confirmed → shipped → delivered`
+- **`payment`** — `unpaid → partial → paid → refunded`
+- **`approval`** — `pending → approved → rejected`
+
+Use the `stateMachines` (plural) property to define them:
+
+```typescript
+// src/domains/sales/order.object.ts
+import { ObjectSchema } from '@objectstack/spec/data';
+import { OrderLifecycle } from './order-lifecycle.state';
+import { OrderPayment } from './order-payment.state';
+import { OrderApproval } from './order-approval.state';
+
+export const Order = ObjectSchema.create({
+  name: 'order',
+  fields: {
+    status: Field.select({ options: ['draft', 'submitted', 'confirmed', 'shipped', 'delivered'] }),
+    payment_status: Field.select({ options: ['unpaid', 'partial', 'paid', 'refunded'] }),
+    approval_status: Field.select({ options: ['pending', 'approved', 'rejected'] }),
+  },
+  stateMachines: {
+    lifecycle: OrderLifecycle,
+    payment: OrderPayment,
+    approval: OrderApproval,
+  }
+});
+```
+
+### `stateMachine` vs `stateMachines`
+
+| Property | Type | Use Case |
+|:---|:---|:---|
+| `stateMachine` | `StateMachineConfig` | Simple objects with a single lifecycle (shorthand) |
+| `stateMachines` | `Record<string, StateMachineConfig>` | Complex objects with parallel state lines |
+
+Both can coexist on the same object. The kernel merges them at runtime.

examples/app-crm/src/domains/sales/lead.object.ts

@@ -161,9 +161,13 @@ export const Lead = ObjectSchema.create({
     }),
   },
 
-  // Lifecycle State Machine
+  // Lifecycle State Machine(s)
   // Enforces valid status transitions to prevent AI hallucinations
-  stateMachine: LeadStateMachine,
+  // Using `stateMachines` (plural) for future extensibility.
+  // For simple objects with one lifecycle, `stateMachine` (singular) is also supported.
+  stateMachines: {
+    lifecycle: LeadStateMachine,
+  },
 
   // Database indexes for performance
   indexes: [

examples/app-crm/test/lead.test.ts

@@ -9,19 +9,24 @@ describe('CRM Domain - Lead', () => {
     expect(() => ObjectSchema.parse(Lead)).not.toThrow();
   });
 
-  it('should have a configured state machine', () => {
-    expect(Lead.stateMachine).toBeDefined();
-    expect(Lead.stateMachine?.id).toBe('lead_process');
-    expect(Lead.stateMachine?.initial).toBe('new');
-    expect(Lead.stateMachine?.states['new']).toBeDefined();
-    expect(Lead.stateMachine?.states['converted'].type).toBe('final');
+  it('should have a configured state machine via stateMachines (plural)', () => {
+    expect(Lead.stateMachines).toBeDefined();
+    
+    const lifecycle = Lead.stateMachines!.lifecycle;
+    expect(lifecycle).toBeDefined();
+    expect(lifecycle.id).toBe('lead_process');
+    expect(lifecycle.initial).toBe('new');
+    expect(lifecycle.states['new']).toBeDefined();
+    expect(lifecycle.states['converted'].type).toBe('final');
   });
 
   it('should have strict AI instructions in states', () => {
-    const newMeta = Lead.stateMachine?.states['new'].meta;
+    const lifecycle = Lead.stateMachines!.lifecycle;
+    
+    const newMeta = lifecycle.states['new'].meta;
     expect(newMeta?.aiInstructions).toContain('Verify email');
 
-    const qualifiedMeta = Lead.stateMachine?.states['qualified'].meta;
+    const qualifiedMeta = lifecycle.states['qualified'].meta;
     expect(qualifiedMeta?.aiInstructions).toContain('Prepare for conversion');
   });
 });