Data Flow End-to-End

This page traces the complete lifecycle of a single workflow step through every layer of Forge. Follow the request as it moves from an operator’s click in the Forge Console, through Convex

Convex’s interpreter, the

Trust Fabric governance pipeline, the

Bridge execution router, a gateway adapter, and back again.

This traces the Bridge-dispatched async path — the most common execution model. For Convex-native agents (Factory Manager, Task Manager, Copilot), see Convex-Native Agents. Those agents run inside Convex and never touch Bridge.

1. Operator Action

The flow begins when an operator clicks Run in the Forge Console.

Forge Consoleapps/burgundy

The dashboard calls the interpreter.startWorkflow Convex mutation. This is a public mutation protected by requirePermission(ctx, “workflow:execute”).

Detail	Value
File	`convex/interpreter.ts`
Function	`startWorkflow` (public mutation, line ~2060)
Auth	`requirePermission(ctx, "workflow:execute")`
Delegates to	`startWorkflowImpl()` (private, line ~1977)

startWorkflowImpl does three things:

Loads the workflow definition — fetches the workflows and workflowVersions documents, pinning the YAML definition at run start (immutable for the run’s lifetime).
Resolves the gateway — checks for a pinned gatewayId from the active deployment, or falls back to the org’s default gateway.
Creates the workflowRuns record — inserts a new row with status "running", a fresh traceId and rootSpanId, then starts the durable workflow:

// convex/interpreter.ts — startWorkflowImpl (simplified)
const runId = await ctx.db.insert("workflowRuns", {
  workflowId: args.workflowId,
  workflowVersion: workflowDef.currentVersion,
  definition: version.definition,  // pinned YAML string
  gatewayId,
  executionAuthorityPosture,
  status: "running",
  startedAt: Date.now(),
  traceId,
  rootSpanId,
});

const workflowId = await workflow.start(
  ctx,
  internal.interpreter.lobsterXInterpreter,
  { runId, definition: version.definition, workflowName, ... }
);

The workflow.start() call uses @convex-dev/workflow’s WorkflowManager to launch a durable workflow. The workflow survives Convex function restarts and resumes from the last committed step.

Cross-links: Workflow Execution Flow | .lobsterX Format

2. DAG Resolution

Inside the durable workflow handler (lobsterXInterpreter), the interpreter parses the YAML and computes the execution graph.

Convex Interpreterconvex/interpreter.ts

Deterministic graph resolution — no LLM tokens burned. Convex walks the DAG, the LLM executes steps.

Detail	Value
File	`convex/interpreter.ts`
Key function	`resolveExecutionLayers()` (from `convex/lib/interpreter_utils.ts`)
Input	Array of `LobsterXStep` objects parsed from YAML
Output	Ordered execution layers — steps within a layer can run in parallel

The interpreter’s event loop then iterates:

Find ready steps — steps whose depends_on dependencies are all completed or skipped, and which have not been dispatched, failed, or cancelled.
Evaluate conditions — if a step has a condition field, evaluate it against accumulated outputs and variables. Steps where the condition is not met are marked skipped.
Dispatch — each ready step is dispatched based on its type: agent step, approval gate, or sub-workflow.
Await completion — step.awaitEvent({ name: "completion" }) blocks until a completion event arrives.
Process and loop — the completed step’s outputs are accumulated, variables updated, and the loop returns to step 1.

// convex/interpreter.ts — event loop (simplified)
while (true) {
  const readySteps = findReadySteps(def.steps, completedSteps, skippedSteps, ...);

  for (const step of readySteps) {
    await dispatchAgentStep(step, lobsterXStep, ctx, 0);
    dispatchedSteps.add(step.id);
  }

  // Wait for any one step to complete
  const event = await step.awaitEvent({ name: "completion" });
  // Process completion, update state, loop back...
}

Cross-links: Interpreter Deep Dive | Checkpoints

3. Governance Evaluation

Before any step reaches the network, the

Trust Fabric evaluates it.

Trust Fabric — The Covenantconvex/trust_fabric/

A fail-fast gate pipeline. The first rejection terminates evaluation and returns a structured GovernanceDecision.

The dispatchStep action (in convex/dispatch.ts) calls the governance engine before doing anything else:

// convex/dispatch.ts — dispatchStep (line ~90)
let decision = await ctx.runAction(
  internal.trust_fabric.bindings.runGovernanceGates,
  { agentId, gatewayId, stepId, runId, dispatchType: "step" }
);

This invokes evaluateGovernance() in convex/trust_fabric/engine.ts, which runs the dispatch pipeline — 10 sequential gates:

#	Gate	Error Code	Purpose
1	`gatewayHealth`	`gateway_unreachable`	Is the target gateway reachable?
2	`agentStatus`	`agent_disabled`	Is the agent enabled and active?
3	`concurrency`	`agent_busy`	Is the agent under its max concurrent step limit?
4	`rateLimit`	`rate_limited`	Has the agent exceeded its dispatch rate?
5	`budgetAgent`	`budget_exceeded`	Has the agent’s monthly spend exceeded its ceiling?
6	`budgetEnvelopes`	`budget_exceeded`	Has any scoped budget envelope been breached?
7	`trustLevel`	`trust_level_insufficient`	Does the agent meet the gateway’s minimum trust level?
8	`contextTrust`	`context_untrusted`	Is the execution context trusted for this agent’s role?
9	`policyRules`	`policy_blocked`	Do dispatch policies permit this action?
10	`approvalRequired`	—	Does this step require human approval before proceeding?

Gates 5—8 use POC reduced enforcement for agents in the poc lifecycle phase. These gates log warnings but do not block dispatch, allowing teams to iterate quickly during prototyping.

Decision Outcomes

The engine returns a GovernanceDecision with one of three dispositions:

Disposition	What happens	Code path
`allow`	Step proceeds to dispatch	Normal flow continues
`block`	Step is marked failed, `SafetyGateError` thrown	`stepResults.markFailed` + audit event
`hold`	Approval request created, step waits	`trust_fabric.approvals.mutations.create`

The dispatchStep action retries retryable blocks up to 3 times with exponential backoff (1s, 2s, 4s) before giving up.

// convex/dispatch.ts — governance retry loop (simplified)
for (let attempt = 0; attempt < 3; attempt++) {
  if (decision.disposition !== "block") break;
  if (!decision.blockedBy?.retryable) break;
  await sleep(backoffDelays[attempt]);
  decision = await runGovernanceGates(...);
}

Every decision is persisted to the audit trail via persistGovernanceDecision(). Cross-links: Governance Pipeline | Safety Gates | Trust Fabric Overview | Approvals | Agent Trust

4. Dispatch

If the Trust Fabric allows the step, dispatchStep performs three operations atomically before hitting the network.

Dispatch Actionconvex/dispatch.ts

Atomic concurrency check, mark step running, then fire-and-forget HTTP dispatch to Bridge.

Detail	Value
File	`convex/dispatch.ts`
Function	`dispatchStep` (internalAction, line ~69)
Key mutation	`stepResults.atomicCheckConcurrencyAndMarkRunning`

Step-by-step:

a) Atomic concurrency check + mark running A single mutation combines the concurrency gate and markRunning to eliminate the TOCTOU race between separate query + mutation calls:

// convex/dispatch.ts (line ~278)
const concurrencyResult = await ctx.runMutation(
  internal.stepResults.atomicCheckConcurrencyAndMarkRunning,
  { runId, stepId, agent, maxConcurrentSteps, attempt, runtimeProvider, executionPath: "bridge" }
);

If the agent is at its concurrency limit, the step is marked failed with agent_busy and a SafetyGateError is thrown. b) Build callback URL The callback URL is derived from CONVEX_SITE_URL (or transformed from CONVEX_URL):

${convexSiteUrl}/api/workflow/step-complete

c) Dispatch to Bridge via adapter The adapter’s dispatchStep() method sends the request to Bridge with 3-attempt retry and exponential backoff (1s, 4s, 16s):

// convex/dispatch.ts (line ~448)
const response = await adapter.dispatchStep(gateway, {
  runId, stepId, workflowName, agent, command, stdin,
  callbackUrl,
  governanceConstraints,  // scope constraints from Trust Fabric
  conversationThreadId,   // for real-time streaming
  traceId,                // distributed trace context
  ...
});

The payload includes governance scope constraints (environment eligibility, tool allow/deny lists, data access restrictions) propagated from the Trust Fabric decision. Cross-links: Bridge Architecture | Gateways | Traceability

5. Adapter Execution

Bridge receives the dispatch, ACKs immediately, and delegates to the adapter.

Bridgepackages/bridge/src/

Async execution router. Receives dispatch, returns 202 immediately, executes via adapter in the background.

Bridge endpoint

Detail	Value
File	`packages/bridge/src/server.ts`
Route	`POST /api/workflow/dispatch` (line ~503)
Auth	`authenticateToken` middleware (bearer token)

The endpoint validates the request, returns 202 Accepted immediately, then delegates execution asynchronously:

// packages/bridge/src/server.ts (line ~530)
res.status(202).json({ status: "dispatched", run_id, step_id, dispatched_at });

setImmediate(async () => {
  await dispatchStepV2(adapters, dispatchBody);
});

Dispatch orchestrator

Detail	Value
File	`packages/bridge/src/dispatch-orchestrator.ts`
Function	`dispatchStepV2()` (line ~319)

The orchestrator:

Resolves the adapter based on the provider field in the request. In multi-adapter mode, Bridge loads multiple adapters from BRIDGE_ADAPTERS env var.
Assembles the ExecutionRequest — builds the full request with output strategy, model, timeout, and tools.
Calls adapter.execute(request) — this is where the actual LLM call happens, with timeout enforcement via AbortController.
Normalizes the output via OutputNormalizer — parses structured output, extracts file content, resolves output strategies.
Builds the callback payload with status, outputs, telemetry (tokens, cost, model), and conversation messages.

Adapter example: Vercel AI

Detail	Value
File	`packages/adapter-vercel-ai/src/provider.ts`
Class	`VercelAIProvider implements ExecutionAdapter`

The adapter dynamically loads AI SDK providers (Anthropic, OpenAI, Google), resolves the model, and calls generateText():

// packages/adapter-vercel-ai/src/provider.ts (simplified)
async execute(request: ExecutionRequest): Promise<ExecutionResult> {
  const { generateText } = await import("ai");
  const model = this.resolveModel(request.model);
  const result = await generateText({ model, prompt: request.message, ... });
  return { status: "success", text: result.text, durationMs, usage };
}

Other adapters (Claude SDK, OpenClaw) follow the same ExecutionAdapter interface but use their native SDKs. Cross-links: Bridge Architecture | Writing Adapters | Gateways

6. Callback

When the adapter finishes (or fails), Bridge delivers the result back to Convex.

CallbackBridge —> Convex HTTP action

Bridge POSTs the result to Convex’s /api/workflow/step-complete endpoint with 3x retry.

Bridge side

Detail	Value
File	`packages/bridge/src/dispatch-orchestrator.ts`
Function	`callbackWithRetry()` (invoked at line ~502)

After execution completes, Bridge sends the callback payload:

// Callback payload shape
{
  run_id, step_id,
  status: "completed" | "failed" | "timed_out",
  outputs: { ... },
  started_at, completed_at,
  error: null | string,
  model, input_tokens, output_tokens, thinking_tokens,
  total_tokens, cost, session_id,
  conversation: [ ... ]  // if adapter captured messages
}

Convex side

Detail	Value
File	`convex/http.ts`
Route	`POST /api/workflow/step-complete` (line ~28)
Auth	`X-Gateway-Token` header verified against gateway registry

The HTTP action handler performs a 10-step sequence:

Verify gateway token — looks up gateway by token hash.
Parse and validate — validates against stepCompleteSchema, range-checks numeric fields (tokens, cost).
Idempotency check — insertIfNotDuplicate prevents duplicate processing of the same callback.
Check workflow status — if the run is cancelled, ACK but discard the result.
Update step result — markStepCompleted or markStepFailed depending on status.
Log audit event — records step_completed or step_failed with full detail.
Record telemetry — inserts a tokenEvents record for cost attribution.
Schedule post-execution governance — evaluates budget thresholds, triggers alerts if spend is approaching limits.
Persist logs and conversation — stores step logs as NDJSON blobs, persists conversation transcripts to agent threads.
Fire completion event — resumes the waiting interpreter:

// convex/http.ts (line ~476)
await ctx.runMutation(internal.workflowEvents.fireCompletion, {
  workflowId: workflowRun.convexWorkflowId,
  type: "step_complete",
  stepId: step_id,
  status,
  outputs,
  ...
});

This fireCompletion mutation sends an event to the durable workflow, which unblocks the interpreter’s awaitEvent("completion") call. Cross-links: Audit Trail | Traces | Analytics

7. DAG Advance

Back in the interpreter, the completion event is received and the DAG advances.

Interpreter Event Loopconvex/interpreter.ts

The event loop processes the completion, accumulates outputs, resolves new dependencies, and dispatches the next wave of steps.

Detail	Value
File	`convex/interpreter.ts`
Event	`awaitEvent({ name: "completion" })` (line ~677)
Completion handler	`processAgentCompletion()` from `convex/lib/interpreter/completion_handlers.ts`

When a step completes:

Parse the completion event — extracts stepId, type, status, outputs, error.
Validate outputs — if the step declares outputs in the .lobsterX definition, the interpreter validates and coerces them.
Accumulate state — outputs are merged into accumulatedOutputs[stepId] and declared variables are updated.
Save checkpoint — a workflow checkpoint is saved so a restart can resume from this point.
Resolve next steps — the loop returns to step 1, finding steps whose dependencies are now satisfied.
Termination check — when all steps are completed, skipped, failed, or cancelled, the loop exits.

// convex/interpreter.ts — completion processing (simplified)
const event = await step.awaitEvent({ name: "completion" });
const { result, error } = await processAgentCompletion(step, completedStep, ctx, event);

if (result === "completed") {
  completedSteps.add(completedStep.id);
  // Save checkpoint for restart resilience
  await saveCheckpoint(runId, completedSteps, skippedSteps, variables, accumulatedOutputs);
} else if (result === "retry") {
  retryDispatched.add(completedStep.id);
  await dispatchAgentStep(step, completedStep, ctx, 1);  // re-dispatch
}
// Loop back to find newly ready steps...

After the loop exits, the interpreter marks the workflow run as "completed" and logs the final audit event. Cross-links: Workflow Execution Flow | Checkpoints | Execution Overview

Failure Paths

Things go wrong. Here is what happens at each layer.

Governance blocks the step

Trigger	Behavior
Any gate returns `block`	`dispatchStep` retries retryable blocks up to 3x, then marks the step failed via `stepResults.markFailed`, logs `safety_gate_rejected` audit event, throws `SafetyGateError`.
Gate returns `hold`	An approval request is created. The step stays in `running` status, waiting for human approval via the Approval Lifecycle.

The interpreter receives the SafetyGateError and applies the step’s on_failure policy:

halt (default) — the workflow stops, recording a failure snapshot for restart.
skip — the step is marked skipped, downstream steps cascade-skip if all their dependencies were skipped.
retry_once — the step is re-dispatched once. If it fails again, it halts.
retry_once_then_escalate — an escalation approval is created. A human can approve retry or abort.

Adapter execution fails

Trigger	Behavior
Adapter throws	Bridge catches the error, builds a `failed` callback payload with `error_code` classification, delivers callback to Convex.
Timeout	`AbortController` cancels the adapter after `timeoutMs`. Bridge sends a `timed_out` callback. A best-effort cancel is sent to the adapter.

Callback delivery fails

Trigger	Behavior
Callback HTTP error	Bridge retries up to 3x with backoff. If all attempts fail, the error is logged but the step remains in `running` status on the Convex side.
Convex timeout enforcer	Convex’s cron-based timeout enforcer independently detects steps that have been running beyond their timeout. It marks them failed and fires a completion event, even if Bridge’s callback never arrived.

Duplicate callbacks

The HTTP handler uses insertIfNotDuplicate for atomic idempotency. If Bridge retries a callback that Convex already processed, the duplicate is ACKed ({ received: true, deduplicated: true }) without side effects. If the timeout enforcer already handled a timed-out step, any late gateway callback only reconciles cost — it does not replay audit events or fire a second completion.

DAG stall detection

If the interpreter finds no ready steps and no in-flight steps, but not all steps are resolved, it throws a stall error:

Workflow stalled: N step(s) have unmet dependencies: step_a, step_b

This typically indicates a circular dependency or a missing step definition. Cross-links: Safety Gates | Approval Lifecycle | Budgets

Data Shape Reference

Key types that flow through this pipeline:

Type	Location	Used at
`LobsterXDocument`	`@tangogroup/shared`	Interpreter YAML parsing
`LobsterXStep`	`@tangogroup/shared`	Step definitions within the DAG
`GovernanceDecision`	`convex/trust_fabric/types.ts`	Trust Fabric evaluation result
`GovernanceEvaluationContext`	`convex/trust_fabric/engine.ts`	Pre-fetched context for gate evaluation
`ExecutionRequest`	`@tangogroup/bridge`	Bridge adapter input
`ExecutionResult`	`@tangogroup/bridge`	Bridge adapter output
`CallbackPayload`	`packages/bridge/src/dispatch-orchestrator.ts`	Bridge-to-Convex callback body
`StepCompleteEvent`	`convex/lib/interpreter/helpers.ts`	Parsed completion event in interpreter

Summary Diagram

The complete flow, layer by layer:

END-TO-END DATA FLOW

Forge Console calls interpreter.startWorkflow

Interpreter parses YAML, resolveExecutionLayers() builds the DAG

Trust Fabric evaluates 10 gates: evaluateGovernance() returns allow / block / hold

Atomic concurrency check + mark running, then HTTP dispatch to Bridge

Bridge ACKs 202, adapter calls execute() on the gateway (LLM call happens here)

Bridge POSTs callback to /api/workflow/step-complete with 3x retry

Convex processes callback, fires fireCompletion, interpreter resumes and advances the DAG

Next Steps

Workflow Execution Flow

The 8-phase execution flow from the architecture perspective.

Governance Pipeline

The full 11-gate dispatch pipeline and 5-gate launch pipeline.

Approval Lifecycle

What happens when a step is held for human approval.

Bridge & Adapters

Bridge architecture, adapter loading, and the ExecutionAdapter interface.

Safety Gates

Detailed reference for each safety gate and its error codes.

Interpreter Deep Dive

The 2200-line workflow engine: DAG resolution, conditions, failure handling.

Writing Adapters

How to implement a new gateway adapter.

Audit Trail

Every governance decision and step event in the append-only log.

.lobsterX Format

The YAML workflow definition language.

Start Here

Agents

Workflows

Trust Fabric

Observability

Operations

Factories & Chat

Architecture

Execution Flows

Engineering

API Reference

SDK & MCP

Data Flow End-to-End

1. Operator Action

2. DAG Resolution

3. Governance Evaluation

Decision Outcomes

4. Dispatch

Step-by-step:

5. Adapter Execution

Bridge endpoint

Dispatch orchestrator

Adapter example: Vercel AI

6. Callback

Bridge side

Convex side

7. DAG Advance

Failure Paths

Governance blocks the step

Adapter execution fails

Callback delivery fails

Duplicate callbacks

DAG stall detection

Data Shape Reference

Summary Diagram

Next Steps

Start Here

Agents

Workflows

Trust Fabric

Observability

Operations

Factories & Chat

Architecture

Execution Flows

Engineering

API Reference

SDK & MCP

​1. Operator Action

​2. DAG Resolution

​3. Governance Evaluation

​Decision Outcomes

​4. Dispatch

​Step-by-step:

​5. Adapter Execution

​Bridge endpoint

​Dispatch orchestrator

​Adapter example: Vercel AI

​6. Callback

​Bridge side

​Convex side

​7. DAG Advance

​Failure Paths

​Governance blocks the step

​Adapter execution fails

​Callback delivery fails

​Duplicate callbacks

​DAG stall detection

​Data Shape Reference

​Summary Diagram

​Next Steps

1. Operator Action

2. DAG Resolution

3. Governance Evaluation

Decision Outcomes

4. Dispatch

Step-by-step:

5. Adapter Execution

Bridge endpoint

Dispatch orchestrator

Adapter example: Vercel AI

6. Callback

Bridge side

Convex side

7. DAG Advance

Failure Paths

Governance blocks the step

Adapter execution fails

Callback delivery fails

Duplicate callbacks

DAG stall detection

Data Shape Reference

Summary Diagram

Next Steps