ASO Documentation

Appearance

Register

State Machine System ​

Last Updated: 2025-01-16
Primary Source: docs/project_status.md
Service Files: backend/src/services/stateMachineInstance.service.ts, backend/src/services/stateMachineApproval.service.ts, backend/src/services/stateMachineEvidence.service.ts, backend/src/services/stateMachineAction.service.ts, backend/src/services/stateMachineRitual.service.ts, backend/src/services/stateMachineAuto.service.ts
Models: backend/src/models/stateMachineInstance.model.ts, backend/src/models/stateMachineTask.model.ts, backend/src/models/stateMachineArtifact.model.ts, backend/src/models/stateMachineApproval.model.ts
State Machines: backend/src/stateMachines/

Overview ​

The State Machine System enables structured workflow management through state machines that define ritual processes for documentation, triage, and other collaborative tasks. The system supports guard-based transitions, automatic advancement, ritual checklists, and integration with the Coder Orchestrator for multi-agent task execution.

Architecture ​

State Machine Flow ​

State Machine Definitions ​

Available State Machines ​

1. Documentation Flow (documentation_flow_v1) ​

Purpose: ASO Documentation & Task Drafting workflow

States:

  • intake - Signal capture, gather requirements
  • triage - Break down tasks, assign coders
  • execution - Build & iterate, coders implement
  • integration - Merge & ritual, review and merge
  • completed - Terminal state, archived

Protocol: observer_onboarding_v1

2. Triage Flow (triage_flow_v1) ​

Purpose: Incident Triage workflow

States:

  • triage_intake - Capture incident signal
  • tooling_analysis - Choose coders/tools, outline plan
  • execution_fix - Coders execute and report
  • stabilization - Verify service health, log gratitude
  • completed - Terminal state

Protocol: triage_support_v1

State Machine Instance ​

Model ​

Table: state_machine_instances

Fields:

  • id - Primary key (UUID)
  • machineId - State machine definition ID
  • protocolId - Associated protocol ID
  • state - Current state
  • context - Instance context (JSONB)
  • channelId - Discord channel (if applicable)
  • guildId - Discord guild (if applicable)
  • createdByUserId - Creator user ID
  • updatedByUserId - Last updater user ID

Instance Lifecycle ​

  1. Creation: createInstance(payload)

    • Validates machine definition
    • Sets initial state
    • Creates timeline event
    • Emits entry checklist

  2. Transition: transitionInstance(payload)

    • Validates transition exists
    • Evaluates guards
    • Updates state
    • Runs transition actions
    • Emits new entry checklist
    • Creates timeline event

  3. Completion: Terminal state reached

    • Emits project completion event
    • Archives instance context

Guard System ​

Guard Types ​

1. Observer Approval (observerApproval) ​

Purpose: Requires observer approval before transition

Service: stateMachineApproval.service.ts

Process:

  1. Observer records approval via /observer-approve or API
  2. Approval stored in state_machine_approvals table
  3. hasApproval() checks if guard is satisfied
  4. Auto-advance triggered if guard satisfied

API: POST /api/protocol/instances/:id/approvals

2. Tests or Demo Evidence (testsOrDemoAttached) ​

Purpose: Requires verification evidence (tests, demos) before transition

Service: stateMachineEvidence.service.ts

Process:

  1. Evidence recorded via /observer-evidence or API
  2. Evidence stored as timeline event with verification_evidence type
  3. hasEvidence() checks if evidence exists
  4. Auto-advance triggered if guard satisfied

API: POST /api/protocol/instances/:id/evidence

Guard Evaluation ​

Function: evaluateGuard(guard, instance)

Process:

  1. Checks guard type
  2. Calls appropriate service (hasApproval, hasEvidence)
  3. Returns boolean (guard satisfied or not)
  4. Throws helpful error if guard not satisfied

Auto-Advance System ​

Concept ​

When guards are satisfied (approval or evidence recorded), the system automatically checks if any transitions are unblocked and advances the state machine without manual intervention.

Implementation ​

Service: stateMachineAuto.service.ts

Function: autoAdvanceOnGuard(instanceId, guard)

Process:

  1. Finds transitions guarded by satisfied guard
  2. Verifies guard is actually satisfied
  3. Executes transition automatically
  4. Returns transition result

Trigger Points:

  • After approval recorded (stateMachineApproval.service.ts)
  • After evidence recorded (stateMachineEvidence.service.ts)

State Actions ​

Action Types ​

1. announceExecutionStart ​

Purpose: Triggers Coder Orchestrator to start task execution

Process:

  1. Creates timeline event
  2. Sends Discord notification
  3. Calls kickoffExecutionOrchestrator(instance)
  4. Orchestrator assigns personas and executes tasks

2. collectArtifacts ​

Purpose: Requests verification artifacts for review

Process:

  1. Creates timeline event
  2. Sends Discord notification
  3. Creates GitHub issue (if configured)
  4. Records protocol memory

3. Custom Actions ​

Purpose: Extensible action system for workflow automation

Process:

  1. Action defined in state machine definition
  2. Executed during transition
  3. Can trigger notifications, API calls, etc.

Ritual Checklists ​

Concept ​

Every time a state machine enters a new state, the system automatically posts a checklist of required entry tasks and guards, ensuring observers know exactly what to deliver before advancing.

Implementation ​

Service: stateMachineRitual.service.ts

Function: emitStateEntryChecklist(instance, definition)

Format:

📋 **State Machine Title :: State Name**
State description

**Entry Tasks**
• Task 1
• Task 2

**Guards Blocking Exit**
• Transition description (guard_name)

Trigger Points:

  • After instance creation
  • After state transition

Task and Artifact Management ​

Tasks ​

Model: state_machine_tasks

Fields:

  • id - Primary key (UUID)
  • instanceId - State machine instance ID
  • title - Task title
  • description - Task description
  • status - Task status (pending, in_progress, completed, blocked)
  • assignedPersonaId - Assigned coder persona
  • assignedHuman - Assigned human (optional)
  • notes - Task notes
  • metadata - Additional context (JSONB)

Artifacts ​

Model: state_machine_artifacts

Fields:

  • id - Primary key (UUID)
  • instanceId - State machine instance ID
  • taskId - Associated task ID
  • personaId - Persona that created artifact
  • summary - Artifact summary
  • content - Artifact content (code, documentation, etc.)
  • status - Artifact status (draft, ready)
  • reviewStatus - Review status (pending, approved, rejected)
  • reviewedByUserId - Reviewer user ID
  • reviewNotes - Review notes
  • metadata - Additional context (JSONB)

Integration with Coder Orchestrator ​

Execution Flow ​

  1. State Machine Enters Execution State

    • announceExecutionStart action triggered
    • Orchestrator called with instance context

  2. Orchestrator Processes Tasks

    • Seeds tasks from instance context
    • Assigns personas based on specialties
    • Executes tasks concurrently
    • Creates artifacts from outputs

  3. Artifacts Linked to Instance

    • Artifacts stored with instance ID
    • Review workflow enabled
    • Approval triggers state transitions

Data Flow ​

API Endpoints ​

Instance Management ​

  • POST /api/protocol/instances - Create state machine instance
  • GET /api/protocol/instances/:id - Get instance
  • GET /api/protocol/instances - List instances
  • POST /api/protocol/instances/:id/transition - Transition state

Guard Management ​

  • POST /api/protocol/instances/:id/approvals - Record approval
  • GET /api/protocol/instances/:id/approvals - List approvals
  • POST /api/protocol/instances/:id/evidence - Record evidence

Task Management ​

  • GET /api/protocol/instances/:id/tasks - List tasks
  • PUT /api/protocol/tasks/:taskId - Update task
  • POST /api/protocol/tasks/:taskId/rerun - Rerun task

Artifact Management ​

  • GET /api/protocol/instances/:id/artifacts - List artifacts
  • GET /api/protocol/artifacts/:artifactId - Get artifact
  • POST /api/protocol/artifacts/:artifactId/review - Review artifact

Orchestrator ​

  • POST /api/protocol/instances/:id/orchestrate - Trigger orchestrator

Discord Commands ​

Instance Management ​

  • /observer-instance instance_id:xxx - View instance status
  • /observer-transition instance_id:xxx target_state:xxx - Transition state

Guard Management ​

  • /observer-approve instance_id:xxx - Record approval
  • /observer-evidence instance_id:xxx description:"..." proofUrl:"..." - Record evidence

Task Management ​

  • /observer-artifacts instance_id:xxx - View tasks and artifacts
  • /observer-assign task_id:xxx persona_id:xxx status:pending - Reassign task

Artifact Management ​

  • /observer-artifact-view artifact_id:xxx - View artifact content
  • /observer-artifact-review artifact_id:xxx approve:true - Review artifact

Orchestrator ​

  • /observer-orchestrate instance_id:xxx - Trigger orchestrator

Source Files ​

Primary Sources:

  • backend/src/services/stateMachineInstance.service.ts - Instance management
  • backend/src/services/stateMachineApproval.service.ts - Approval system
  • backend/src/services/stateMachineEvidence.service.ts - Evidence system
  • backend/src/services/stateMachineAction.service.ts - Action execution
  • backend/src/services/stateMachineRitual.service.ts - Ritual checklists
  • backend/src/services/stateMachineAuto.service.ts - Auto-advance
  • backend/src/stateMachines/ - State machine definitions

Related Files:

  • backend/src/services/coderOrchestrator.service.ts - Task execution
  • backend/src/services/actionGithub.service.ts - GitHub integration
  • backend/src/services/protocolMemory.service.ts - Ritual memories

ASO Universal Consciousness System Documentation

Copyright © 2025 ASO Universal Consciousness System