docs(automation): state the stored-flow impact, and pin the shape Studio emits

Two gaps found while verifying #4439.

The #4414 changeset described the mechanism but not who it moves. `objectui`'s
FlowEdgeInspector has always written `isDefault: true` when an out-edge is
bound to a decision's default/else branch — into a key with zero readers, so
that edge ran unconditionally alongside whichever branch matched. Enforcement
therefore changes STORED flows, and mostly Studio's own: they now take exactly
one branch. That is the fix, but it lands on existing data, which a reader of
the release notes needs to know before upgrading.

The same inspector also copies each branch's expression and label onto the
edge it wires, so Studio emits the very double declaration the authoring guide
told hand-writers to avoid. It routes correctly — the designer keeps the two
sides in sync by construction — so the guide now says that plainly instead of
forbidding a shape our own tool produces: redundant, not wrong, and dangerous
only when the two disagree, which is the whole of #4414.

Pins that exact emitted shape as a regression test, both directions.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q8as8yR67v41xEdomiTba9

Author: claude

.changeset/decision-branch-routing-enforced.md

@@ -74,6 +74,21 @@ sibling — the actual hole), `flow-default-edge-with-condition` and
 Both of the first two fire on the pre-fix `convert-lead.flow.ts` and are silent
 after it.
 
+## Effect on flows that already exist
+
+Enforcing `isDefault` changes how a **stored** flow behaves, and the flows it
+changes are mostly Studio's own. `objectui`'s flow edge inspector has always
+written `isDefault: true` when you bind an out-edge to a decision's default/else
+branch — into a key with zero readers, so that edge ran unconditionally, in
+parallel with whichever branch actually matched. Those flows now take exactly
+one branch. That is the fix, but it is a behaviour change on existing data
+rather than only on newly authored metadata, so it is worth knowing before
+upgrading: a flow that quietly ran two paths will now run one.
+
+Nothing changes for an edge that never carried the marker — `isDefault` defaults
+to `false`, and an ordinary unconditional out-edge still fans out in parallel
+exactly as before.
+
 ## The example app
 
 `crm_convert_lead_wizard`'s guard is now a plain exclusive gateway: the

content/docs/automation/flows.mdx

@@ -783,9 +783,16 @@ sibling), `flow-default-edge-with-condition` and `flow-multiple-default-edges`.
 
 <Callout type="warn">
 A decision node that declares **no** `conditions` reports no branch at all — it
-is a plain gateway and its out-edges do the routing. Do not declare both:
-`config.conditions` *and* per-edge `condition`s on the same node means the node
-picks a branch, and then that branch's edge re-decides.
+is a plain gateway and its out-edges do the routing.
+
+Declaring **both** — `config.conditions` *and* per-edge `condition`s — is
+redundant but not wrong: the node picks a branch, and then that branch's edge
+re-decides with the same predicate. The Studio flow designer emits exactly this
+(it copies each branch's expression and label onto the edge it wires), and it
+routes correctly because the two are kept in sync by construction. Hand-written
+metadata has no such guarantee, which is the whole of #4414: when the two
+disagree, the node's branch wins the narrowing and the edge's predicate decides
+what actually runs. If you are writing the flow by hand, pick one.
 </Callout>
 
 ### Fault edges — handling a failed node

packages/services/service-automation/src/builtin/decision-branch-routing.test.ts

@@ -296,3 +296,74 @@ describe('decision branch predicate is validated at registration (#4439)', () =>
         expect(() => engine.registerFlow('guard', flowWith("lead.status == 'converted'"))).not.toThrow();
     });
 });
+
+/**
+ * The shape objectui's flow designer actually emits, pinned.
+ *
+ * `FlowEdgeInspector.applyBranch()` copies a decision branch onto the edge it
+ * wires: a guarded branch becomes `{ condition, label }`, and the `true`/empty
+ * branch becomes `{ isDefault: true, label }`. So Studio has been writing
+ * `isDefault` since long before anything read it (#4414) — every Studio
+ * "default/else" edge ran unconditionally, in parallel with whichever branch
+ * matched. These flows are the ones enforcement changes, and they must now take
+ * exactly one path.
+ *
+ * It is also the double declaration the authoring guide tells hand-writers to
+ * avoid — node `conditions[]` AND per-edge `condition`s. It is correct here
+ * only because the designer keeps the two in sync by construction, which is
+ * exactly why it is worth pinning rather than assuming.
+ */
+describe('objectui-authored decision shape (FlowEdgeInspector.applyBranch)', () => {
+    let engine: AutomationEngine;
+    let visited: string[];
+
+    beforeEach(() => {
+        warnings.length = 0;
+        visited = [];
+        engine = new AutomationEngine(createTestLogger());
+        registerLogicNodes(engine, createCtx());
+        engine.registerNodeExecutor({
+            type: 'mark',
+            async execute(node) { visited.push(node.id); return { success: true }; },
+        });
+        engine.registerFlow('studio', {
+            name: 'studio',
+            label: 'Studio-authored',
+            type: 'autolaunched',
+            variables: [{ name: 'order_amount', type: 'number', isInput: true }],
+            nodes: [
+                { id: 'start', type: 'start', label: 'Start' },
+                {
+                    id: 'check', type: 'decision', label: 'Check Amount',
+                    config: {
+                        conditions: [
+                            { label: 'High Value', expression: 'order_amount > 10000' },
+                            { label: 'Standard', expression: 'true' },
+                        ],
+                    },
+                },
+                { id: 'escalate', type: 'mark', label: 'Escalate' },
+                { id: 'auto', type: 'mark', label: 'Auto approve' },
+            ],
+            edges: [
+                { id: 'e1', source: 'start', target: 'check' },
+                // The guarded branch: expression + label copied onto the edge.
+                { id: 'e2', source: 'check', target: 'escalate', label: 'High Value', condition: 'order_amount > 10000', isDefault: false },
+                // The `true` branch: written as the BPMN default edge, no condition.
+                { id: 'e3', source: 'check', target: 'auto', label: 'Standard', isDefault: true },
+            ],
+        });
+    });
+
+    it('takes only the guarded branch when it matches', async () => {
+        await engine.execute('studio', { params: { order_amount: 20000 } } as any);
+        expect(visited).toEqual(['escalate']);
+        expect(warnings).toHaveLength(0);
+    });
+
+    it('takes only the default branch when it does not', async () => {
+        await engine.execute('studio', { params: { order_amount: 5000 } } as any);
+        expect(visited).toEqual(['auto']);
+        expect(warnings).toHaveLength(0);
+    });
+});