PRD — Cambium Core + Hypha

Document Status

Draft V1

Purpose

This PRD defines the first product and engineering requirements for Cambium Core and Hypha, the foundational platform and orchestration runtime.

This is the heart of Cambium V1. If this layer is weak, everything above it becomes a fragile demo. If this layer is solid, Loom, Quorum, health, immune, and seed systems can all grow on top of it without needing a rewrite every few weeks.

Product Summary

Cambium Core provides the platform substrate: - identity and workspace boundaries - shared contracts and domain model - persistence model - event backbone - integration boundaries - permissions model

Hypha provides the execution runtime: - graph-based workflow execution - stateful orchestration - task routing - retries and fallback behavior - pause/resume behavior - event emission for all major transitions

Together, they form the engine room of Cambium.

Problem

Most agent workflow systems fail in one or more of these ways: - workflows are linear and brittle - execution state is poorly modeled - failures are opaque - retry and fallback behavior is ad hoc - orchestration logic is tightly coupled to the UI - systems are hard to inspect and impossible to recover cleanly

That makes them fine for demos and annoying for real work.

Cambium needs a runtime that is built for: - adaptive execution - durable state - inspectable runs - policy-aware routing - recovery hooks - future governance and health systems

Goals

Product goals

1. Allow operators to define and run graph-based workflows.
2. Persist workflow runs with durable, inspectable state.
3. Support branching, retries, waits, failures, and fallback paths.
4. Emit structured events for every meaningful transition.
5. Provide clean interfaces for Loom, Quorum, health, immune, and seed layers.

Engineering goals

1. Build as a modular monolith with clear internal domain boundaries.
2. Make workflow execution stateful and event-driven.
3. Define stable core data contracts early.
4. Keep the runtime extensible enough for later policy and recovery features.
5. Avoid premature complexity from distributed services.

Non-Goals

This PRD does not require V1 to ship: - full marketplace-style agent ecosystems - advanced credit routing or internal economies - elaborate multi-tenant billing - autonomous self-modifying workflow generation - full no-code workflow authoring sophistication - high-scale distributed orchestration across many physical clusters on day one

We are building a serious platform core, not trying to cosplay the final form immediately.

Primary Users

1. Operator

A human who wants to: - create or configure workflows - inspect runs - understand failures - intervene when needed

2. Platform builder

An internal developer building new capabilities on top of Cambium who needs: - stable contracts - reusable execution primitives - clean extension points

3. Governed execution consumer

A downstream system such as Quorum, health, or seed that needs: - event streams - durable state - hooks for pause, gate, checkpoint, and replay flows

V1 User Stories

Workflow definition

• As an operator, I can create a workflow definition with nodes and edges.
• As an operator, I can version a workflow definition.
• As an operator, I can attach policies or metadata to specific nodes or actions.

Workflow execution

• As an operator, I can start a workflow run from a definition.
• As the system, I can execute workflows as graphs rather than only as linear steps.
• As the system, I can branch execution based on conditions or outcomes.
• As the system, I can retry failed nodes based on configured policies.
• As the system, I can route execution to fallback paths after failure.
• As the system, I can pause and later resume a run.

Observability

• As an operator, I can inspect the current state of a run.
• As an operator, I can see the history of events for a run.
• As an operator, I can see which node is active, failed, blocked, or completed.

Extensibility

• As a downstream subsystem, I can subscribe to workflow and task events.
• As a downstream subsystem, I can request a pause, gate, or intervention on a run.

Core Requirements

1. Workflow Definition Model

The platform must support a durable workflow definition model.

Functional requirements

• A workflow definition has a unique ID.
• A workflow definition has versions.
• A workflow definition stores a graph structure.
• A workflow definition supports node metadata.
• A workflow definition supports edge metadata.
• A workflow definition supports references to policies and checkpoint rules.
• A workflow definition can be activated or retired.

V1 node types

At minimum, support: - task node - condition node - wait node - approval/gate node - terminal success node - terminal failure node

V1 edge behavior

At minimum, support: - default next edge - conditional edge - fallback edge - retry edge

2. Workflow Run Model

Every workflow execution must create a durable run record.

Functional requirements

• A workflow run has a unique ID.
• A workflow run references a specific workflow definition version.
• A workflow run stores current status.
• A workflow run stores active node state.
• A workflow run stores execution history.
• A workflow run stores timestamps for all major transitions.
• A workflow run stores intervention records.
• A workflow run stores references to checkpoints and decision records.

V1 run states

At minimum: - created - queued - running - waiting - blocked - failed - completed - cancelled - paused

3. Task Execution Model

Each runnable node should produce a durable task execution record.

Functional requirements

• Task execution records reference a workflow run and node.
• Task execution records store inputs and outputs.
• Task execution records store retry count.
• Task execution records store current status.
• Task execution records store error information.
• Task execution records store actor/tool metadata.

V1 task execution states

At minimum: - pending - dispatched - running - succeeded - failed - retrying - blocked - cancelled

4. Graph-Based Runtime

Hypha must execute workflows as graphs.

Functional requirements

• The runtime evaluates the current active node set.
• The runtime determines eligible next transitions.
• The runtime supports branching.
• The runtime supports joins where applicable.
• The runtime supports retries based on policy.
• The runtime supports fallback paths.
• The runtime supports explicit wait/pause behavior.
• The runtime supports external intervention.

Design requirement

The runtime must not assume exactly one active next step at all times.

5. Event Backbone

Cambium Core must provide a structured event backbone.

Functional requirements

The system emits events for at least: - workflow definition created - workflow version activated - workflow run created - workflow run started - node entered - node completed - node failed - retry scheduled - workflow paused - workflow resumed - workflow blocked - workflow failed - workflow completed - intervention requested - intervention applied

Event requirements

• Each event has a unique ID.
• Each event has a type.
• Each event has a timestamp.
• Each event references related workflow/run/task IDs when relevant.
• Each event includes payload metadata.
• Events are queryable for inspection in Loom.

6. Pause / Resume / Intervention Hooks

The platform must support controlled intervention.

Functional requirements

• An operator or subsystem can request a pause.
• A paused run can be resumed.
• A blocked run can await external input.
• Interventions are recorded durably.
• The runtime responds safely to intervention without corrupting run state.

7. Integration Boundary

Cambium Core and Hypha must expose clear internal interfaces for future modules.

Integration consumers in V1 or near-V1

• Loom
• Quorum
• health layer
• seed layer
• immune signals layer
• external tool/model integrations

Requirements

• Workflow and task events are consumable by other modules.
• Run status can be queried without scraping logs.
• Policy references can be attached at workflow and node levels.
• External modules can annotate runs with metadata or signals.

8. Permissions and Identity Model

V1 needs a sane internal identity model.

Functional requirements

• Workflows and runs belong to a workspace or tenant boundary.
• Actions are attributable to a user, system process, or service identity.
• Sensitive interventions are attributable in audit records.
• Permissions exist for creating, running, viewing, pausing, and intervening in workflows.

We do not need enterprise IAM theater in V1, but we do need clean attribution and boundaries.

Data Model

WorkflowDefinition

• id
• workspace_id
• name
• description
• version
• graph_spec
• policy_bindings
• checkpoint_policy
• status
• created_at
• updated_at

WorkflowRun

• id
• workspace_id
• workflow_definition_id
• workflow_version
• status
• current_nodes
• context_payload
• health_state
• started_at
• completed_at
• created_at
• updated_at

TaskExecution

• id
• workflow_run_id
• node_id
• actor_type
• actor_ref
• status
• input_payload
• output_payload
• error_payload
• retry_count
• started_at
• completed_at
• created_at
• updated_at

EventRecord

• id
• workspace_id
• event_type
• workflow_run_id
• task_execution_id
• payload
• emitted_at

InterventionRecord

• id
• workflow_run_id
• requested_by
• intervention_type
• reason
• payload
• created_at

Operator Experience Requirements

Even before Loom gets fancy, operators should be able to: - create and version workflows - start runs - inspect run status - inspect event history - see current active nodes - pause and resume runs - identify failure points

If the engine works but nobody can tell what the hell it is doing, that still counts as failure.

Reliability Requirements

Required for V1

• No workflow run exists only in transient memory.
• Workflow transitions are persisted before or with their event trail.
• Failed tasks do not silently disappear.
• Retry behavior is deterministic relative to policy.
• Pause/resume behavior is consistent.
• Event history is sufficient for debugging a failed run.

Nice to have if feasible

• idempotency safeguards for task dispatch
• replay support for select workflow segments
• dead-letter handling for failed event processing

Success Metrics

Product success

• Operators can define and run graph-based workflows without code changes.
• Operators can inspect why a run failed or blocked.
• Downstream modules can consume events without runtime hacks.

Engineering success

• The runtime supports branching, retries, waits, and interventions cleanly.
• The codebase preserves modular boundaries between core, runtime, and UI.
• New modules can attach without rewriting the execution engine.

Open Questions

1. What is the canonical workflow definition format for V1?
2. Should nodes compile into an internal intermediate representation before execution?
3. How much of task execution is local vs provider/integration driven?
4. What persistence model best balances speed and replayability?
5. Which events must be guaranteed durable before state transitions are acknowledged?

Build Recommendation

The implementation should likely start with: 1. Workflow definition schema 2. Run state model 3. Graph executor 4. Event emission layer 5. Operator inspection endpoints 6. Pause/resume/intervention controls

That gets us to a credible Hypha core quickly while keeping room for Quorum, Loom, and resilience systems to plug in cleanly.

Final Requirement Statement

Cambium Core + Hypha must provide a modular, stateful, event-driven orchestration foundation that supports graph-based workflows, durable run state, structured events, controlled intervention, and clean extension points for the rest of the Cambium platform.