Spec — Reference Scenarios

Document Status

Draft V1

Purpose

This document defines end-to-end reference scenarios that prove all Cambium layers connect and communicate as a living system.

Each scenario walks through a real workflow touching every major subsystem: Cambium Core, Hypha, Loom, Quorum, Health, Seed, Immune, Stigmergy, Genesis, and the Signal Protocol.

If a scenario can complete end-to-end, the platform works. If it can’t, we know exactly which seam is broken.

Scenario 1: Research Pipeline with Stress and Recovery

Domain: Research and analysis pipeline Purpose: Prove adaptive routing, health response, seed recovery, and operator intervention

Setup

Workflow: “Market Research Analysis”
4 agents: Researcher (RAG), Analyst (LLM), Writer (LLM), Reviewer (LLM)
All agents instantiated via Genesis from templates
Workflow has checkpoint policy at every major node transition

Flow

1. GENESIS
   - Hypha requests 4 agents from Genesis
   - Templates selected based on capability requirements
   - Agents instantiated, activated, heartbeat registered
   - Signals emitted: lifecycle.agent_genesis × 4
   - Stigmergy: each agent places resource.available marker in workflow region

2. WORKFLOW START
   - Operator triggers run from Loom
   - Hypha creates WorkflowRun record
   - Signal: lifecycle.run_started
   - Seed: initial checkpoint created

3. RESEARCH PHASE
   - Hypha routes "gather sources" task to Researcher agent
   - Researcher reads stigmergic markers, finds no danger markers
   - Researcher executes: queries RAG sources, retrieves documents
   - Researcher completes successfully
   - Stigmergy: Researcher places quality.high marker on data sources used
   - Stigmergy: Researcher places path.hot marker on research path
   - Signal: lifecycle node_completed
   - Seed: checkpoint at research completion

4. ANALYSIS PHASE
   - Hypha routes "analyze findings" to Analyst agent
   - Analyst begins processing
   - ** STRESS EVENT: Analyst's LLM provider starts returning slow responses **
   - Analyst latency spikes to 3x normal
   - Health detects: stress.latency_spike (intensity: 0.6)
   - Stigmergy: Health places path.slow marker on analysis path
   - Loom: run status shows "degraded" indicator
   - Analyst completes, but slowly
   - Signal: stress.latency_spike propagates

5. CONTINUED STRESS
   - Hypha routes "draft report" to Writer agent
   - Writer's LLM provider ALSO slow (same provider)
   - Health detects: stress.latency_spike (intensity: 0.8, sustained)
   - Cascade chain activates: sustained stress → immune.anomaly_detected
   - Immune evaluates: two agents hitting same provider, both slow → systemic issue, not agent issue
   - Immune signal: immune.anomaly_detected (severity: 0.5, type: "provider_degradation")
   - Loom: anomaly flag visible on run detail
   - Health recommends: throttle + consider fallback provider

6. PROVIDER FAILURE
   - Writer's task fails: LLM provider returns 503
   - Signal: node_failed
   - Hypha checks retry policy: 2 retries allowed
   - Retry 1: fails again
   - Stigmergy: path.failing marker placed on this execution path
   - Health: stress.error_rate signal (intensity: 0.7)
   - Retry 2: fails again
   - Hypha: all retries exhausted

7. RECOVERY
   - Hypha checks fallback edges: fallback path exists (alternative LLM provider)
   - Hypha reads stigmergic markers: alternative path has no danger markers
   - Hypha routes to fallback path
   - Writer re-executes with alternative provider
   - Writer completes successfully
   - Stigmergy: quality.high on fallback path, path.hot reinforced
   - Seed: checkpoint at draft completion
   - Signal: recovery signals emitted

8. REVIEW WITH GOVERNANCE
   - Hypha routes "review report" to Reviewer agent
   - Node has Quorum policy: "external_publication" requires approval
   - Reviewer completes review, output ready for publication
   - Signal: governance.approval_required
   - Quorum creates pending approval
   - Loom: approval appears in Approvals view with full context
   - ** Hypha pauses run at gate **

9. OPERATOR APPROVAL
   - Operator sees approval in Loom
   - Reviews: report content, run history, anomaly flags, recovery events
   - Operator approves
   - Signal: governance.approval_granted
   - Hypha resumes execution
   - Workflow completes
   - Signal: lifecycle.run_completed

10. COMPOSTING
    - Workflow done, agents no longer needed
    - Agents decommissioned
    - Compost records created:
      - Researcher: high success, good data sources noted
      - Analyst: success but slow — provider latency logged
      - Writer: initial failure, successful fallback — provider reliability data captured
      - Reviewer: clean execution
    - Compost nutrients fed into:
      - Provider reliability scores (routing heuristic update)
      - Template effectiveness metrics
      - Immune baseline calibration

What This Scenario Validates

Genesis instantiation from templates
Heartbeat and liveness monitoring
Stigmergic marker placement and reading
Health stress detection and signal emission
Signal cascade (stress → immune)
Retry and fallback routing
Seed checkpointing
Quorum governance gating
Loom visibility at every stage
Composting on completion
Event trail for full auditability

Scenario 2: Financial Trading Workflow with Immune Response

Domain: Financial / trading Purpose: Prove immune detection, quarantine, governance escalation, and emergency recovery

Setup

Workflow: “Arbitrage Opportunity Execution”
Agents: Scanner (API caller), Analyzer (LLM), Risk Assessor (script), Executor (API caller)
High-sensitivity workflow: all execution nodes require Quorum approval
Checkpoint policy: every node transition + pre-execution snapshot

Flow

1. SCANNING
   - Scanner agent polls market data sources
   - Finds potential arbitrage opportunity
   - Stigmergy: places opportunity.found marker with details
   - Signal: coord.work_available

2. ANALYSIS
   - Analyzer evaluates opportunity
   - Produces: expected edge, confidence score, time sensitivity
   - Stigmergy: quality.high on this opportunity

3. RISK ASSESSMENT
   - Risk Assessor (deterministic script agent) runs:
     - Position sizing (Kelly criterion)
     - Exposure limits check
     - Liquidity validation
   - Risk assessment passes
   - Seed: pre-execution checkpoint created

4. GOVERNANCE GATE
   - Execution requires Quorum approval (financial action)
   - Signal: governance.approval_required
   - Quorum presents: opportunity details, risk assessment, position size, confidence
   - Operator approves in Loom
   - Signal: governance.approval_granted

5. EXECUTION
   - Executor agent begins placing orders
   - ** ANOMALY: Executor places 3 orders in 200ms — normal is 1 per second **
   - Immune detects: abnormal tool frequency
   - Signal: immune.anomaly_detected (severity: 0.85, type: "rapid_execution")

6. IMMUNE RESPONSE
   - Severity > 0.8 → cascade chain: immune.quarantine_requested
   - Auto-approve quarantine (severity > 0.9 threshold not met, but close)
   - Signal sent to Quorum: immune.escalation_required
   - Hypha: pauses remaining execution
   - Seed: emergency checkpoint created
   - Loom: run shows quarantine state with anomaly details

7. INVESTIGATION
   - Operator sees quarantine in Loom
   - Reviews: execution logs, signal trail, anomaly details
   - Determines: API returned batch confirmation (3 fills on 1 order) — false positive
   - Operator overrides quarantine
   - Signal: governance.override_applied (with audit justification)
   - Immune: adjusts detection threshold for batch API responses (learning)

8. RESUMPTION
   - Hypha resumes from emergency checkpoint
   - Remaining workflow completes
   - Execution confirmed
   - Signal: lifecycle.run_completed

9. COMPOSTING + IMMUNE LEARNING
   - Executor agent's compost record includes:
     - False positive anomaly triggered
     - Batch API behavior documented
   - Immune layer absorbs: batch fills ≠ rapid execution anomaly
   - Template for Scanner/Executor updated with API behavior notes

What This Scenario Validates

Financial workflow with real governance requirements
Immune anomaly detection on behavioral patterns
Quarantine mechanism
Emergency checkpoint creation
Operator override with audit trail
Immune learning from false positives (composting feedback loop)
Signal cascades under high-severity conditions

Scenario 3: Product Development Pipeline (MasawaOS-Style)

Domain: Product/service development Purpose: Prove long-running workflows, agent hibernation, multi-phase orchestration, and stigmergic coordination

Setup

Workflow: “Feature Development Cycle”
Phases: Research → Design → Implement → Test → Deploy
Each phase may spawn sub-workflows
Long-running: hours to days
Agents hibernate between phases

Flow

1. RESEARCH PHASE
   - Genesis spawns: Research Agent (RAG), Domain Expert Agent (LLM)
   - Agents research existing codebase, requirements, prior art
   - Stigmergy: agents place quality markers on sources, opportunity markers on findings
   - Phase completes
   - Seed: major checkpoint
   - Agents hibernate (preserve context, release resources)
   - Signal: lifecycle.agent_hibernating × 2

2. DESIGN PHASE (hours later)
   - Genesis spawns: Design Agent (LLM), Architecture Agent (LLM)
   - Agents activated, read stigmergic markers left by Research phase
   - Markers guide design decisions without needing to re-read all research
   - Design agent reads quality.high markers → focuses on vetted sources
   - Design agent reads opportunity.found markers → incorporates discovered patterns
   - Phase completes
   - Seed: checkpoint
   - Agents hibernate

3. IMPLEMENTATION PHASE
   - Genesis spawns: Coder Agent (LLM), Script Runner Agent (deterministic)
   - Research agents re-activated from hibernation (context preserved)
   - Coder reads stigmergic markers from Design phase
   - Coder implements feature
   - Script Runner executes build scripts
   - ** Script Runner encounters build failure **
   - Health: stress.error_rate
   - Coder reads danger.error_prone marker placed by Script Runner
   - Coder adjusts approach, fixes build issue
   - Implementation completes
   - Agents hibernate

4. TEST PHASE
   - Genesis spawns: Test Agent (script + LLM hybrid)
   - Test Agent runs test suite
   - Tests pass
   - Quorum: "deploy to staging" requires approval
   - Operator approves

5. DEPLOY PHASE
   - Genesis spawns: Deploy Agent (script)
   - Deploy Agent executes deployment pipeline
   - Health monitors deployment metrics
   - Deployment succeeds
   - All agents decommissioned and composted
   - Workflow complete

   - LONG-TERM FEEDBACK:
     - Compost records from all phases aggregated
     - Template effectiveness: which agent types worked best for each phase
     - Stigmergic patterns: which marker types were most useful for cross-phase communication
     - Immune baselines: what "normal" looks like for development workflows

What This Scenario Validates

Long-running multi-phase workflows
Agent hibernation and re-activation
Stigmergic markers persisting across phases (cross-phase communication)
Genesis spawning different agent types per phase
Composting aggregation across a full workflow lifecycle
Pattern applicable to MasawaOS orchestration

Scenario 4: Self-Healing Under Cascading Failure

Domain: System resilience (applies to any domain) Purpose: Prove the organism can survive and recover from multi-layer failure

Flow

1. NORMAL OPERATION
   - Multiple workflows running concurrently
   - All subsystems healthy
   - Heartbeats normal

2. EXTERNAL FAILURE
   - Primary LLM provider goes down
   - Multiple agents report failures simultaneously
   - Health: stress.error_rate (intensity: 0.9) across multiple runs
   - Health: stress.resource_exhaustion (LLM capacity)
   - Stigmergy: danger.error_prone markers flood affected paths

3. CASCADE DETECTION
   - Immune: immune.anomaly_detected — correlated failures across agents
   - Immune recognizes: systemic provider failure, not agent-level issue
   - Signal cascade: stress (sustained) → immune anomaly → governance escalation

4. SYSTEM RESPONSE (automated)
   - Hypha: throttles all runs using affected provider
   - Hypha: reads stigmergic markers, reroutes to paths with resource.available
   - Seed: emergency checkpoints on all active runs
   - Health: system-level state → "stressed"
   - Loom: global health indicator shows stressed state
   - Quorum: auto-gates any new workflow starts until health recovers

5. RECOVERY
   - Provider comes back online
   - Agents report successful heartbeats
   - Health: stress signals decay
   - Stigmergy: danger markers decay, resource.available markers reappear
   - Health: system state → "degraded" → "healthy"
   - Quorum: lifts workflow start gate
   - Hypha: resumes throttled runs from seed checkpoints
   - Signal: recovery.restoration_complete × N

6. POST-INCIDENT
   - Immune: stores provider failure pattern
   - Composting: provider reliability scores updated system-wide
   - Templates: fallback provider configuration strengthened
   - System is now more resilient to this failure mode

What This Scenario Validates

Multi-run coordinated stress response
System-level (not just run-level) health management
Automated cascade response without operator intervention
Seed checkpoints under emergency conditions
Stigmergic markers driving rerouting decisions
Post-incident learning (anti-fragility)
The system gets stronger after failure

Integration Validation Matrix

Each scenario should demonstrate these layer interactions:

Interaction	Scenario 1	Scenario 2	Scenario 3	Scenario 4
Genesis → Agent	Yes	Yes	Yes	—
Agent → Stigmergy	Yes	Yes	Yes	Yes
Stigmergy → Hypha routing	Yes	—	Yes	Yes
Health → Stress signal	Yes	—	—	Yes
Stress → Immune cascade	Yes	Yes	—	Yes
Immune → Quorum escalation	—	Yes	—	Yes
Quorum → Hypha gate	Yes	Yes	Yes	Yes
Seed → Checkpoint	Yes	Yes	Yes	Yes
Seed → Recovery	Yes	Yes	—	Yes
Loom visibility	Yes	Yes	Yes	Yes
Composting → Learning	Yes	Yes	Yes	Yes
Heartbeat monitoring	Yes	Yes	Yes	Yes
Agent hibernation	—	—	Yes	—
Multi-run coordination	—	—	—	Yes

All critical paths are covered across the four scenarios.