Version Compare & Three-Way Diff: How Rule Changes Get Reviewed in DecisionManager

## The review problem

A reviewer approving a ruleset promotion needs to answer one question: what changed between the current production version and the one being promoted? In IBM ODM, this was the Change Report — a generated document listing every modified action rule and decision table row. In DecisionManager, it's the Compare page (`/compare`), with three views and a permanent URL for every comparison.

Three comparison views

The Compare page exposes three views for the same pair of versions:

Changes view

The changes view shows only what's different: added rules (green), removed rules (red), and modified rules (yellow). For decision tables, it shows row-level diffs with condition values side by side. For action rules, it shows the BAL diff at the statement level.

This is the reviewer's primary view — it surfaces what requires attention without requiring a full read of the unchanged ruleset.

Structured view

The structured view renders both versions side by side as their fully resolved logical structure: all condition dimensions, all conclusion fields, all action statements. Unchanged content appears at reduced opacity. This is useful for understanding the full context of a change, not just the delta.

Raw view

The raw view shows the underlying JSON representation of both versions, diffed at the field level. This is the escape hatch for debugging serialisation issues, verifying that a metadata-only edit didn't accidentally touch rule logic, and for consuming the diff in an external tool via copy-paste.

Deep-linkable comparison URLs

Every comparison writes its state to the URL:

/compare?ruleset=<id>&base=<versionId>&target=<versionId>&view=changes

The URL is the complete state of the comparison. A reviewer can drop it into a Jira comment, a Slack message, or an email, and the recipient opens the exact same comparison — same ruleset, same base, same target, same view. No "send me the link" follow-up.

When a reviewer changes the view from `changes` to `structured`, the URL updates. When they select a different target version from the dropdown, the URL updates. The browser back button navigates the comparison history.

Branch Center comparison

The Compare page is for version-ID comparison — a specific `base` and `target` version pair. For branch-level merge comparison (comparing main with a feature branch before merging), the entry point is the Branch Center:

`/branches?tab=compare&ruleset=<id>&source=main&target=<branchId>`

Branch comparison shows the three-way merge: base (common ancestor), source (main), and target (branch), with conflict highlighting where both sides have modified the same rule.

ODM Change Report parity

The ODM Change Report covered: - Added / removed action rules - Added / removed decision table rows - Modified rule conditions and actions

The Compare page covers all three, with additions: - **Semantic merge context** (branch compare): shows common ancestor to explain why a conflict occurred - **Live, interactive**: no document generation step; the comparison runs in the browser against the API - **Permanent link**: share a specific comparison without attaching a PDF

Governance integration

The governance workflow surface shows the most recent comparison link alongside the suite run result. When a reviewer opens an approval request, the "View changes" button opens the comparison between the current production version and the proposed version — pre-populated, one click.