┌─────────────Rust Orchestrator──────────────┐
              │                                            │
       WorkflowParser          WorkflowRepository          │
       (YAML → domain)         (PostgreSQL)                │
              │                                            │
              └──────── StartWorkflowUseCase ──────────────┘
                                  │
               ┌──────────────────┴───────────────────┐
               │                                      │
   HTTP POST /register-workflow          gRPC StartWorkflowExecution
               │                                      │
               ▼                                      ▼
     TypeScript Worker (:3000)           Temporal Server (:7233)
   workflow_definitions (PostgreSQL)              │
               │                         task queue: aegis-agents
               └──────────────────────────────────┘
                                  │
                          aegis_workflow()
                       (single generic FSM interpreter)
                                  │
         ┌────────────────────────┼────────────────────────┐
         │                        │                        │
 executeAgentActivity  executeSystemCommandActivity  validateOutputActivity
         │                        │                        │
         └────────────────────────┴────────────────────────┘
                                  │
                   gRPC AegisRuntime (:50051)  ←── Rust Orchestrator
                   ExecuteAgent (streaming)
                   ExecuteSystemCommand (unary)
                   ValidateWithJudges (unary)
                                  │
                HTTP POST /v1/temporal-events  ──► Rust EventBus
                (WorkflowExecution event store)

struct Workflow {
    id: WorkflowId,
    metadata: WorkflowMetadata,   // name, version, labels
    scope: WorkflowScope,         // Global | Tenant | User
    spec: WorkflowSpec,
    created_at: DateTime<Utc>,
}

struct WorkflowSpec {
    initial_state: String,                      // entry state name
    context: HashMap<String, Value>,            // default Blackboard values (spec.context)
    states: HashMap<String, WorkflowState>,
}

// The Workflow aggregate includes a `scope` field (WorkflowScope) that controls visibility.
// Scope can be Global (platform-wide, tenant_id = "aegis-system"), Tenant (default, visible
// to all users in the tenant), or User (private to the owning user). Name-based lookups
// resolve using narrowest-first precedence: User → Tenant → Global.
enum WorkflowScope {
    Global,   // tenant_id = "aegis-system"; visible to all tenants
    Tenant,   // visible to all users within the owning tenant (default)
    User,     // visible only to the owning user within their tenant
}

struct WorkflowState {
    kind: StateKind,
    timeout: Option<Duration>,
    transitions: Vec<TransitionRule>,
}

// All state-specific config is carried inside the StateKind variant.
enum StateKind {
    Agent {
        agent: String,                          // deployed agent name
        input: String,                          // Handlebars input template
        isolation: Option<IsolationMode>,
    },
    System {
        command: String,                        // shell command (Handlebars-rendered)
        env: HashMap<String, String>,
        workdir: Option<String>,
    },
    Human {
        prompt: String,                         // shown to operator (Handlebars-rendered)
        default_response: Option<String>,       // used when timeout elapses with no signal
    },
    ParallelAgents {
        agents: Vec<ParallelAgentConfig>,       // concurrent agent configs
        consensus: ConsensusConfig,             // aggregation strategy
    },
    ContainerRun {
        name: Option<String>,                   // human-readable label for Synapse UI
        image: String,                          // registry/repo:tag or standard runtime reference
        image_pull_policy: ImagePullPolicy,     // Always | IfNotPresent | Never
        command: Vec<String>,                   // exec-form command; joined under sh -c if shell=true
        shell: bool,                            // wrap in /bin/sh -c
        env: HashMap<String, String>,
        workdir: Option<String>,
        volumes: Vec<ContainerVolumeMount>,
        resources: Option<ContainerResources>,  // cpu millicores, memory, timeout
        registry_credentials: Option<String>,   // OpenBao path resolved by orchestrator
        retry: Option<RetryConfig>,
    },
    ParallelContainerRun {
        steps: Vec<ContainerRunConfig>,         // concurrent container steps
        completion: ParallelCompletionStrategy, // AllSucceed | AnySucceed | BestEffort
    },
    Subworkflow {
        workflow_id: String,                    // deployed child workflow name or UUID
        mode: SubworkflowMode,                  // Blocking | FireAndForget
        result_key: Option<String>,             // Blackboard key for child's final output (blocking)
        input: Option<String>,                  // Handlebars template passed as child's start input
    },
}

enum SubworkflowMode {
    Blocking,       // parent waits for child completion
    FireAndForget,  // parent continues immediately
}

struct TransitionRule {
    condition: Option<TransitionCondition>,     // None = unconditional (always)
    target: String,                             // target state name
    feedback: Option<String>,                   // Handlebars string; available as {{state.feedback}}
}

enum TransitionCondition {
    Always,
    OnSuccess, OnFailure,
    ScoreAbove { threshold: f64 },
    ScoreBelow { threshold: f64 },
    ScoreBetween { min: f64, max: f64 },
    ScoreAndConfidenceAbove { score: f64, confidence: f64 },
    ConfidenceAbove { threshold: f64 },
    Consensus { threshold: f64, agreement: f64 },
    AllApproved, AnyRejected,
    InputEquals { value: String },
    InputEqualsYes, InputEqualsNo,
    ExitCodeZero, ExitCodeNonZero,
    ExitCode { code: i32 },
    Custom { expression: String },              // Handlebars boolean expression
}

Blackboard["REQUIREMENTS"] = {
  "status": "success",
  "output": "...agent's final output text...",
  "score": 0.92,
  "iterations": 2
}

Blackboard["BUILD"] = {
  "exit_code": 0,
  "stdout": "Compiling my-crate v0.1.0\n   Finished release in 12.3s",
  "stderr": "",
  "duration_ms": 12350
}

Blackboard["TEST"] = {
  "unit-tests":   { "exit_code": 0, "stdout": "...", "stderr": "",    "duration_ms": 4200 },
  "lint":         { "exit_code": 0, "stdout": "",    "stderr": "",    "duration_ms": 870  },
  "format-check": { "exit_code": 1, "stdout": "",    "stderr": "...", "duration_ms": 410  }
}

ARCHITECTURE:
  kind: Agent
  agent: architect-agent
  input: |
    Requirements: {{REQUIREMENTS.output}}
    
    Design the architecture.
  transitions:
    - condition: on_success
      target: ARCH_APPROVAL

WorkflowExecution
  state = "approve_requirements"
  status = WAITING_FOR_SIGNAL
         │
         │  Signal arrives via:
         │    POST /v1/workflows/executions/{id}/signal
         │    {"response": "approved"}
         │  or via HTTP API:
         │    POST /v1/human-approvals/{id}/approve
         ▼
  Temporal signal received → Blackboard["approve_requirements"]["decision"] = "approved"
  TransitionRule evaluates → target = "implement"
  Workflow continues

Enter BUILD (ContainerRun)
│
├── executeContainerRunActivity(image, command, volumes, resources)
│     │
│     ├── gRPC AegisRuntime.ExecuteContainerRun
│     │     ├── Pull image (respects image_pull_policy)
│     │     ├── docker run --rm -v <NFS-mount>:/workspace --cpus 2 --memory 4g
│     │     │     └── cargo build --release
│     │     ├── Capture stdout + stderr (up to 1 MB each)
│     │     └── Return { exit_code, stdout, stderr, duration_ms }
│     │
│     └── Blackboard["BUILD"] = { exit_code, stdout, stderr, duration_ms }
│
TransitionRules evaluated on exit_code → next state chosen

Enter TEST (ParallelContainerRun, completion: all_succeed)
│
├── executeContainerRunActivity(unit-tests, ...)
├── executeContainerRunActivity(lint, ...)        (all three run simultaneously)
└── executeContainerRunActivity(format-check, ...)
         │
         └── Promise.allSettled — wait for all three
               │
               completion: all_succeed
                 → all exit_code == 0?  → on_success transition
                 → any exit_code != 0?  → on_failure transition
               │
         Blackboard["TEST"] = {
           "unit-tests":   { exit_code, stdout, stderr, duration_ms },
           "lint":         { exit_code, stdout, stderr, duration_ms },
           "format-check": { exit_code, stdout, stderr, duration_ms }
         }

Enter PARALLEL_REVIEW
│
├── Activity: security-reviewer
├── Activity: performance-reviewer  (all three run simultaneously)
└── Activity: style-reviewer
         │
         └── All three complete
               │
               Blackboard["PARALLEL_REVIEW"] = {
                 "consensus": {
                   "score": 0.91,
                   "confidence": 0.87,
                   "all_succeeded": true
                 },
                 "agents": [
                   {"status": "success", "score": 0.91, "output": "{...}"},
                   {"status": "success", "score": 0.88, "output": "{...}"},
                   {"status": "success", "score": 0.95, "output": "{...}"}
                 ]
               }
               │
         TransitionRules evaluated → next state chosen

Enter TRIGGER_CHILD (Subworkflow, mode: blocking)
│
├── Temporal startChildWorkflowExecution(workflow_id, input)
│     │
│     ├── Child workflow starts as an independent Temporal workflow run
│     ├── Child has its own Blackboard, state machine, and execution history
│     ├── Child runs the same aegis_workflow() generic interpreter
│     │
│     └── Parent waits for child WorkflowExecutionCompleted signal
│           │
│           └── Child's final_blackboard returned to parent
│
├── Blackboard["TRIGGER_CHILD"] = {
│     "status": "success",
│     "result": <child's final output>,
│     "child_execution_id": "wfx-child-..."
│   }
├── Blackboard["pipeline_output"] = <child's final_blackboard>  (via result_key)
│
TransitionRules evaluated → next state chosen

Enter START_BACKGROUND (Subworkflow, mode: fire_and_forget)
│
├── Temporal startChildWorkflowExecution(workflow_id, input)
│     └── Child starts; parent does NOT await completion
│
├── Blackboard["START_BACKGROUND"] = {
│     "status": "success",
│     "child_execution_id": "wfx-child-..."
│   }
│
TransitionRules evaluated → parent continues immediately