feat(workflows): compare deployment versions across UI and API (#8455)

* feat(workflows): describe container changes and build a canvas diff overlay

The comparison engine now reports which loop and parallel fields changed and
which blocks entered or left a container, and exposes the field lists and a
shared hasChanges helper. A new overlay module merges two workflow states into
one canvas: removed blocks, containers and edges ride along as ghosts at their
old positions (nudged clear of live cards), deleted condition and router
branches stay on the surviving card so their ghost edge keeps a handle, and
every edge is classified by canonical port key. The renderer edge view gains a
quiet ghost style for those removed connections.

* feat(preview): paint comparison status on the read-only canvas

The preview canvas accepts per-block and per-edge diff status: added and
modified cards get a ring and a shared status label, removed cards and
containers fade to a ghost, changed sub-block rows and sentence chips tint,
and ghost edges sit under live ones so a rewired port shows the new line on top.

* feat(workflows): version diff view with a field-level change list

Side-by-side view of two workflow states: the overlaid canvas on the left and a
change list on the right, sharing selection. Each touched block is a collapsible
card with the app's block tile; modified blocks show field rows as folded line
diffs with word marks, item-by-item list diffs for tools, conditions, routes and
input fields, old to new pairs for scalars, and only the fact for secrets. Added
and removed blocks show every field diffed against nothing, with long one-sided
bodies capped behind one expander. Fork comparisons group credentials, picked
resources and trigger paths into a muted environment bindings section.

* feat(deploy): compare deployment versions and the draft

The deploy modal offers "View changes" (live against the draft) when a redeploy
is pending and a "Compare" action on every version row, opening a full-width
comparison whose two sides are pickable from the header. The draft state hook is
shared with change detection and only subscribes while something to compare
against exists.

* feat(forks): preview one workflow's block-level changes before a sync

The synced deployed workflows list gets a "View changes" action per row. A new
internal route and fork use case return the target as its editor holds it and
the source deployment re-keyed into the target's block ids through the fork block
map (or the derived id the sync would assign), with condition and route ids and
variable ids aligned, so the two sides diff block for block like two versions of
one workflow.

* fix(workflows): harden the version diff after review

Comparison: keep basic/advanced mode changes visible, include a tool's
permission, server and implementation fields in list diffs, include input field
defaults, read checkbox records as records, show whitespace-only edits, cap word
and line diffing so a pathological prompt cannot stall the pane, slot deleted
branches back at their old position, never reuse a ghost edge id, and mask
secret-looking keys at any depth (including key/value table rows) with a
name-based fallback when a block definition is unknown.

Change list: memoized cards that only re-render when their own selection
changes, nested cards for blocks inside an added or removed container, a
shared sign map, muted tokens that exist, hover and focus treatment, scroll
edge fades, and a shared skeleton for both hosts.

Fork preview: the before side is the target draft the sync overwrites, read
in one snapshot and scoped to the target workspace; variables and their
assignments are re-keyed by unique name; a create reports no target id; the
change rows are a discriminated union; the query key sits under the fork diff
keys so a sync invalidates it; a direction switch closes the preview.

* fix(workflows): scope the fork preview to one workflow and close review gaps

- Fork "View changes" now loads only the previewed workflow: its deployed
  state, its identity mapping, its target row and its block pairs, instead of
  every deployed state in the source workspace plus the full promote plan.
  The plan item comes from the same buildForkPromotePlanItems decision the
  promote uses. The route gets a per-user rate limit.
- Word marks give up past 64 edits per line pair, so many long rewritten
  lines cannot stall the tab.
- Agent tool params that their block marks as password fields are masked
  whatever their name.
- A list item whose label changed but whose body did not is no longer
  flagged as a masked value change.
- Hoist double casts under their annotations, make sourceWorkflowId
  optional on the wire for rollout, lazy-load both diff modals, and
  re-record the settings module baseline: the block registry the diff canvas
  needs is reached only through the lazy chunk opened on click.

* test(forks): use a neutral workflow name in preview fixtures

* fix(forks): offer "View changes" only on workflows the sync changes

- Sync details load each replaced target's draft and diff it against the
  projected source, using the same projection and "has changes" rule as the
  per-workflow preview, so a row and its preview never disagree. Rows the sync
  would not change read "No changes" and offer no comparison.
- Preview buttons wait until the list matches the selected direction.
- Mask JSON-encoded secrets in text and scalar fields, and say "A masked
  value changed" when masking hides the only difference.
- Show role changes on agent messages, highlight a router's changed Context
  on the canvas, and keep ghost edges under live ones into containers.
- Added or removed loops and parallels list their iteration settings.
- Size ghost containers the way the preview draws them.
- "Order changed" only when items moved; CRLF and CR read as line breaks;
  collapsing unchanged lines closes every fold; selecting a nested block
  opens its container card; the version pickers have distinct names.
- Drop redundant mock resets flagged by check:test-patterns.

* fix(workflows): bound the sync change check and tighten diff rendering

- The sync list's per-workflow change check measures the target drafts in one
  query first and skips itself past the fork state limit, then reads drafts a
  few at a time and drops each after comparing, instead of holding them all.
- Mask keys with a secret word anywhere in them (secretAccessKey,
  aws_secret_access_key) while credential references stay readable.
- Inline diffs show whitespace-only changes.
- Opened folds reset when the compared bodies change.
- Ghost collision boxes use the canvas's own block measurement.

* fix(workflows): mask message text, count all block columns, reset selection per comparison

- Agent message bodies go through the same masking as other text fields.
- The sync change check's size guard counts block outputs and data, not only sub-blocks.
- Picking another version clears the block selection.

* fix(workflows): scope selection reset to picked versions and test outcomes, not mock calls

- Key the comparison view by the picked version pair instead of resetting on state identity, so live draft updates no longer clear the selection.
- Agent message changes hidden by masking say so, like other fields.
- Fork preview tests assert results, with mocks that answer only the right arguments, instead of asserting mock calls.

* fix(workflows): only call a message change masked when the message exists on both sides

* test(workflows): use absolute imports in new tests

* fix(workflows): unify version comparison and simplify diff UI

* fix(workflows): compare against previous saved version by default

* fix(workflows): preserve comparison semantics and preview ports

* feat(workflows): render structured version changes by subblock type

* fix(api): remove stale OpenAPI operation count assertions

* fix(workflows): preserve scoped fields and snapshot ports

* fix(workflows): preserve version-specific container labels

* fix(workflows): retain tool context when masking encoded params

---------

Co-authored-by: Vikhyath Mondreti <vikhyath@simstudio.ai>

Author: mzxchandra

.github/workflows/test-build.yml

@@ -195,7 +195,7 @@ jobs:
       # immediately, and either way the server log tail lands in the job log. No
       # step timeout: the job's bound covers a hang without cutting a slow but
       # healthy suite short of writing its report.
-      - name: Verify SCIM and administration over real HTTP
+      - name: Verify SCIM, administration and workflow comparisons over real HTTP
         working-directory: apps/sim
         env:
           NEXT_PUBLIC_APP_URL: http://127.0.0.1:3017
@@ -247,6 +247,11 @@ jobs:
           SCIM_E2E_AUTH_SECRET="$BETTER_AUTH_SECRET" \
           SCIM_E2E_REPORT_PATH="$report_dir/scim-e2e-report.json" \
             bun run test:scim:e2e
+          VERSION_COMPARE_E2E_BASE_URL="$NEXT_PUBLIC_APP_URL" \
+          VERSION_COMPARE_E2E_DATABASE_URL="$DATABASE_URL" \
+          VERSION_COMPARE_E2E_AUTH_SECRET="$BETTER_AUTH_SECRET" \
+          VERSION_COMPARE_E2E_REPORT_PATH="$report_dir/version-compare-http-report.json" \
+            bun run test:workflow-version-compare:e2e
 
       - name: Upload end-to-end reports and server logs
         if: failure()

apps/docs/content/docs/api-reference/(generated)/workflows/meta.json

@@ -14,6 +14,7 @@
     "applyWorkflowVariables",
     "listWorkflowVersionsV2",
     "getWorkflowVersionV2",
+    "compareWorkflowVersionsV2",
     "updateWorkflowVersionV2",
     "activateWorkflowVersion",
     "revertWorkflowVersion",

apps/docs/content/docs/cli/reference.mdx

@@ -6277,6 +6277,113 @@ sim workflows runs wait <runId> [options]
 
 </CommandTable>
 
+### sim workflows versions compare
+
+Compare Workflow Versions
+
+```bash
+sim workflows versions compare <workflowId> [options]
+```
+
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `workflowId` | Yes | Unique workflow identifier. |
+
+</CommandTable>
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--base <value>` | Yes | Deployment version to compare from. |
+| `--target <value>` | Yes | Deployment version to compare to, in the same workflow. |
+
+</CommandTable>
+
+### sim workflows versions get
+
+Get Workflow Version
+
+```bash
+sim workflows versions get <workflowId> <version>
+```
+
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `workflowId` | Yes | Unique workflow identifier. |
+| `version` | Yes | Numeric deployment version. |
+
+</CommandTable>
+
+### sim workflows versions list
+
+List Workflow Versions
+
+```bash
+sim workflows versions list <workflowId> [options]
+```
+
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `workflowId` | Yes | Unique workflow identifier. |
+
+</CommandTable>
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+
+</CommandTable>
+
+### sim workflows versions update
+
+Update Workflow Version
+
+```bash
+sim workflows versions update <workflowId> <version> [options]
+```
+
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `workflowId` | Yes | Unique workflow identifier. |
+| `version` | Yes | Numeric deployment version. |
+
+</CommandTable>
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--name <value>` | No | New label for the deployment version. |
+| `--description <value>` | No | New release note for the deployment version, or null to clear it. (--description null sends the word, not JSON null). |
+
+</CommandTable>
+
 ### sim workflows create
 
 Create Workflow
@@ -6750,84 +6857,6 @@ sim workflows state replace <workflowId> [options]
 
 </CommandTable>
 
-### sim workflows versions get
-
-Get Workflow Version
-
-```bash
-sim workflows versions get <workflowId> <version>
-```
-
-**Arguments**
-
-<CommandTable>
-
-| Argument | Required | Description |
-| --- | --- | --- |
-| `workflowId` | Yes | Unique workflow identifier. |
-| `version` | Yes | Numeric deployment version. |
-
-</CommandTable>
-
-### sim workflows versions list
-
-List Workflow Versions
-
-```bash
-sim workflows versions list <workflowId> [options]
-```
-
-**Arguments**
-
-<CommandTable>
-
-| Argument | Required | Description |
-| --- | --- | --- |
-| `workflowId` | Yes | Unique workflow identifier. |
-
-</CommandTable>
-
-**Options**
-
-<CommandTable>
-
-| Option | Required | Description |
-| --- | --- | --- |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
-| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-
-</CommandTable>
-
-### sim workflows versions update
-
-Update Workflow Version
-
-```bash
-sim workflows versions update <workflowId> <version> [options]
-```
-
-**Arguments**
-
-<CommandTable>
-
-| Argument | Required | Description |
-| --- | --- | --- |
-| `workflowId` | Yes | Unique workflow identifier. |
-| `version` | Yes | Numeric deployment version. |
-
-</CommandTable>
-
-**Options**
-
-<CommandTable>
-
-| Option | Required | Description |
-| --- | --- | --- |
-| `--name <value>` | No | New label for the deployment version. |
-| `--description <value>` | No | New release note for the deployment version, or null to clear it. (--description null sends the word, not JSON null). |
-
-</CommandTable>
-
 ### sim workflows import
 
 Import Workflow