> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture migration history

> A migration guide for anyone who knew the old architecture — what was retired, what replaced it, and where to find things now.

If you're returning to Forge after the architecture shift, this page maps the old concepts to the new ones. The platform underwent a major simplification: the execution model is now unified around Convex-native agents, the workflow engine was rebuilt on `@convex-dev/workflow`, and several layers (Bridge dispatch, adapter packages, .lobsterX YAML) were retired.

For weekly cadence, see the [Changelog landing](https://docs.gloo.com/forge/changelog.md).

## Architecture: Four Layers → Three

The substrate recast

Four execution layers collapsed to three; the Bridge and adapter tier was deleted.

## Concept-by-Concept Migration

| Old Concept | Status | New Equivalent | Where to Read |
| - | - | - | - |
| **Bridge** (async execution router) | **Retired and deleted.** The bridge packages were removed — no bridge layer exists in the platform. | Convex-native dispatch. Every agent runs via `@convex-dev/agent` as a Convex action. | [Execution Model](https://docs.gloo.com/forge/architecture/system-overview.md#agent-dispatch) |
| **Gateway Adapters** (OpenClaw, Claude Agent SDK, Vercel AI, Gloo AI, Hermes Agent) | **Retired and deleted.** The gateway adapter packages were removed. | No equivalent needed. Agents run directly in Convex. For code execution, agents use the `runInSandbox` tool. | [Vercel Sandbox](https://docs.gloo.com/forge/build/configure-sandbox.md#vercel-sandbox-provider) |
| **`.lobsterX` YAML DSL** | **Retired**. The old interpreter and step dispatcher throw legacy errors. | Workflow graphs. Authored via Forge Console graph editor or Dashboard API. Stored in the entity-model tables (`workflows` / `workflowVersions` / `workflowDrafts`) plus polymorphic `workflowGraphNodes` / `workflowGraphEdges`. | [Workflow Graph Model](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#the-workflow-graph) |
| **`workflowGraphDefinitions` single table** | **Retired** (April 2026). Holding pen for migration data only. | Split into three entity tables: `workflows` (identity), `workflowVersions` (immutable published snapshots), `workflowDrafts` (editable workspace). Runs pin a `versionId` (production) or `draftId` (test) with a required `kind` discriminator. | [Workflow Entity Model Split](#workflow-entity-model-split) below |
| **The interpreter** (2200-line DAG walker) | **Retired**. | The workflow orchestrator — durable state machine on `@convex-dev/workflow`. | [Convex Platform](https://docs.gloo.com/forge/architecture/system-overview.md#why-a-transactional-reactive-backend) |
| **Step dispatch** (with Bridge) | **Retired**. | Per-node agent dispatch via `composeAgentConfig`. | [Data Flow End-to-End](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#data-flow-end-to-end) |
| **"Dual execution model"** (Convex-native vs Bridge-dispatched) | **Retired**. | One model: all agents are Convex-native. `composeAgentConfig` is the universal resolver. | [Agent Composition](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#2-composition) |
| **`ExecutionAdapter` interface** | **Retired and deleted** along with the Bridge. | Not needed. Agents compose via `composeAgentConfig` and execute via `@convex-dev/agent`. | [Convex-Native Agents](https://docs.gloo.com/forge/architecture/system-overview.md#agent-dispatch) |
| **`exe.dev` cloud VMs** | **Replaced**. | Vercel Sandbox via `@vercel/sandbox`. Agents call `runInSandbox` tool. | [Vercel Sandbox](https://docs.gloo.com/forge/build/configure-sandbox.md#vercel-sandbox-provider) |
| **`agentDeployments` table** (gateway bindings) | **Deprecated**. | `agentDefinitions` is the single table. No deployment step — `composeAgentConfig` resolves at dispatch time. | [Agents Overview](https://docs.gloo.com/forge/build/define-an-agent.md) |
| **`skillRegistry` table** | **Deleted**. | `skillDefinitions` — single source of truth for all skills. Three source types: builtin, workspace, imported. | [Skills Overview](https://docs.gloo.com/forge/build/author-a-skill.md) |
| **`agentRegistry` table** | **Consolidated**. | `agentDefinitions` — canonical agent definitions with lifecycle, trust, autonomy. | [Agents Overview](https://docs.gloo.com/forge/build/define-an-agent.md) |
| **Workflow "steps"** | **Renamed to "nodes"**. | Workflow graph nodes: `produce`, `router`, `join`, `publish`. The legacy `agent` and `human` literals were unified into `produce`. | [Workflow Graph Model](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#the-workflow-graph) |
| **Governance engine and gates** | **Moved**. | The Trust Fabric engine and its numbered gates. Same numbered pipeline, better organized. | [Trust Fabric Internals](https://docs.gloo.com/forge/run/trust-fabric.md) |

## Key New Concepts

| Concept | What It Is | Where to Read |
| - | - | - |
| **`composeAgentConfig`** | Universal agent resolver. Every dispatch site calls it. Loads definition, resolves prompt + promptRef, intersects skills, merges tools, builds model. Returns `ComposedAgentConfig`. Does NOT invoke Trust Fabric. | [Agent Composition](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#2-composition) |
| **`@convex-dev/workflow`** | Durable workflow component. The orchestrator runs as a durable workflow — survives restarts, commits checkpoints. | [Workflow Graph Model](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#the-workflow-graph) |
| **`@convex-dev/agent`** | Durable agent framework. Every agent is instantiated per-dispatch from a `ComposedAgentConfig`. Thread history is durable. | [Convex-Native Agents](https://docs.gloo.com/forge/architecture/system-overview.md#agent-dispatch) |
| **`runInSandbox` tool** | Isolated code execution via `@vercel/sandbox`. Agents call it to spawn a VM, run commands, collect results. | [Vercel Sandbox](https://docs.gloo.com/forge/build/configure-sandbox.md#vercel-sandbox-provider) |
| **Skills (first-class)** | Packaged instruction sets with activation modes (`always` / `on_demand`), `allowedTools` governance, quality review pipeline. Three authoring paths: builtin (platform), workspace (UI), imported (marketplace/ClawHub). | [Skills](https://docs.gloo.com/forge/build/author-a-skill.md) |
| **Workflow graph nodes** | 4 types: `produce`, `router`, `join`, `publish`. Replace `.lobsterX` steps. The `produce` type covers both agent and human workers — the resolved worker kind decides the dispatch path. | [Workflow Graph Model](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#the-workflow-graph) |
| **`executionModel: "native"`** | The only value that works. `"managed"` (legacy) throws. `"cloud"` (reserved) throws. The `create()` mutation defaults to `"managed"` — always set `"native"` explicitly. | [Execution Model](https://docs.gloo.com/forge/architecture/system-overview.md#agent-dispatch) |

## Workflow Entity Model Split

> [!NOTE]
>
> **Shipped April 2026.** This was the largest data-model change since the Bridge retirement.

The workflow data model had historically commingled four semantically distinct concepts in a single `workflowGraphDefinitions` table, discriminated only by a `status` enum (`draft` / `active` / `superseded`): logical identity, the draft workspace, the currently-published active version, and historical superseded versions. That conflation produced a recurring class of UX bugs (the post-publish catalog card landing on the still-editable draft; Publish button reappearing on a just-shipped workflow) and had no stable `workflowId` to hang workflow-level features from — ownership, tags, cross-version analytics, test runs.

The shipped model splits workflows across three entity tables with clear invariants:

| Table | What it holds |
| - | - |
| `workflows` | Logical workflow identity. One row per `(factoryId, name)`. Carries `ownerId`, `tags`, `retired`, `description`. Unique on `by_factoryId_name`. |
| `workflowVersions` | Immutable published snapshots. Monotonic `version: number` per workflow. `status: "active" \| "superseded"` — at most one active per workflow. |
| `workflowDrafts` | Editable workspace. One per workflow for MVP. Optional `baseVersionId` points at the version the draft was forked from; publish rebases this link. |

`workflowGraphNodes` and `workflowGraphEdges` gained a polymorphic parent: exactly one of `versionId` or `draftId` is set per row (the `graphOwner` invariant). `workflowRuns` gained `versionId?`, `draftId?`, and a required `kind: "production" | "test"` discriminator — production runs pin a `versionId`; **test runs** (a new first-class affordance) pin a `draftId` so operators can exercise a draft before publishing.

The launcher contract changed accordingly: `api.workflowV2.launcher.launch` now accepts `{ workflowId }`, `{ versionId }`, or `{ name, factoryId? }` (all three resolve to a production run), and a new `launchTest({ draftId })` mutation launches against the draft graph and tags the run `kind: "test"`. The Forge Console URL contract moved to `/production/workflows/[workflowId]` (overview page with Graph / Versions / Runs tabs), and the builder accepts `?draftId=` or `?versionId=`. Bookmarks using the retired `?definitionId=` form redirect to the catalog rather than silently resolving.

**What this means if you had bookmarks or code against the old shape:**

* External SDK / MCP consumers that referenced `definitionId` must migrate to the entity-model fields. The packages were bumped in the same rollout.
* Analytics queries over `workflowRuns` default-exclude `kind: "test"` runs. Opt back in with an explicit `includeTest: true` flag on the query.
* `workflowGraphDefinitions` remains in the schema only during the migration window; the split migration is idempotent and paginated, and the table is scheduled for removal after all environments converge.
* The Workflow Architect AI pipeline now writes directly into `workflows` + `workflowDrafts`. The dispatch mutation returns `{ workflowId, draftId }` and the builder URL uses `?draftId=<X>`. The `api.graphAuthoring.*` public surface has been removed.

***

*See also: [Changelog](https://docs.gloo.com/forge/changelog.md) | [Welcome](https://docs.gloo.com/forge.md#how-forge-fits-together) | [Architecture](https://docs.gloo.com/forge/architecture/system-overview.md) | [Convex-Native Agents](https://docs.gloo.com/forge/architecture/system-overview.md#agent-dispatch)*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.