Skip to main content
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.

Architecture: Four Layers → Three

Concept-by-Concept Migration

Key New Concepts

Workflow Entity Model Split

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: 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 | Welcome | Architecture | Convex-Native Agents