@waron97/prbot 3.2.0 → 3.2.1

package/agrippa-pb.md

@@ -156,6 +156,7 @@ Node types: `startEvent`, `endEvent`, `boundaryEvent`, `exclusiveGateway`,
 ```
 agrippa pb ls            # discover node/edge ids
 agrippa pb add / rm / connect / disconnect / set-default   # change the graph
+agrippa pb lint          # check for structural issues before handing off
 # STOP. Do NOT format. Do NOT push. Report back to the human (see Formatting below).
 ```
 
@@ -229,20 +230,27 @@ manifest entries. No dangling references left behind.
 # plain sequence
 agrippa pb connect --from ScriptTask_a --to ScriptTask_b --pb <document_id>
 
-# gateway branch with a condition
+# named branch (required when the source has 2+ outgoing flows and this is non-default)
 agrippa pb connect --from ExclusiveGateway_g --to ScriptTask_b \
-  --condition '${isAlive}' --pb <document_id>
+  --name "alive" --condition '${isAlive}' --pb <document_id>
 
-# the gateway's fallback branch
+# the gateway's fallback branch (default needs no name)
 agrippa pb connect --from ExclusiveGateway_g --to EndEvent_err \
   --default --pb <document_id>
 ```
 
 A flow's id is printed. Conditions default to `xsi:type="tFormalExpression"`
-(override with `--condition-type`). **Gateway rule** (enforced by Activiti, warned by
-this command): an `exclusiveGateway` with more than one outgoing flow must have
-**exactly one** `--default` flow, and **every other** outgoing flow must carry a
-`--condition`. Heed the `!` warnings `connect` prints.
+(override with `--condition-type`). **Rules** (warned by this command and by `pb lint`):
+
+- An `exclusiveGateway` with more than one outgoing flow must have **exactly one**
+  `--default` flow, and **every other** outgoing flow must carry a `--condition`.
+- Any node with more than one outgoing flow: every **non-default** flow must have a
+  `--name` (operators need labels to distinguish branches at runtime).
+- Only `exclusiveGateway` may have more than one **incoming** flow.
+- An `exclusiveGateway` may not have both multiple incoming **and** multiple outgoing
+  flows — pick one direction (merging or splitting), not both.
+
+Heed the `!` warnings `connect` prints.
 
 #### `pb disconnect` — remove a flow
 
@@ -251,6 +259,22 @@ agrippa pb disconnect --id SequenceFlow_1lso8x0 --pb <document_id>
 agrippa pb disconnect --from ScriptTask_a --to ScriptTask_b --pb <document_id>
 ```
 
+#### `pb lint` — check for structural issues
+
+```bash
+agrippa pb lint --pb <document_id>
+```
+
+Runs all diagram rules and prints any violations. Exits 1 if issues found. Run after
+every batch of structural edits before handing off to a human. Rules checked:
+
+- `exclusiveGateway` default/condition rule (2+ outgoing → one default, rest conditioned)
+- Non-default outgoing flows must have a name when the source has 2+ outgoing flows
+- Only `exclusiveGateway` may have multiple incoming flows
+- `exclusiveGateway` may not have both multiple incoming and multiple outgoing flows
+
+`pb format` and `pb connect` also surface the same warnings inline.
+
 #### `pb set-default` — change a gateway's default flow
 
 ```bash
@@ -324,7 +348,8 @@ graph (`pb ls`) first if so.
 
 ```bash
 agrippa pb add --type exclusiveGateway --name "alive?" --pb W   # → ExclusiveGateway_g
-agrippa pb connect --from ExclusiveGateway_g --to ScriptTask_ok  --condition '${isAlive}' --pb W
+agrippa pb connect --from ExclusiveGateway_g --to ScriptTask_ok \
+  --name "alive" --condition '${isAlive}' --pb W
 agrippa pb connect --from ExclusiveGateway_g --to EndEvent_err --default --pb W
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@waron97/prbot",
-    "version": "3.2.0",
+    "version": "3.2.1",
     "description": "",
     "main": "index.js",
     "scripts": {

package/src/agrippa/commands/diff.js

@@ -47,19 +47,30 @@ async function diff(targetArg) {
     const token = await getToken();
 
     let diffCount = 0;
+    const chunks = [];
 
     if (codeEntries.length) {
         const remoteCodeMap = await fetchRemoteCode(token, process.env.RIP_URL, codeEntries);
-        diffCount += diffCodeEntries(codeEntries, remoteCodeMap);
+        const { diffCount: c, chunks: cs } = diffCodeEntries(codeEntries, remoteCodeMap);
+        diffCount += c;
+        chunks.push(...cs);
     }
 
     for (const entry of pbEntries) {
-        if (await diffPbEntry(token, entry)) diffCount++;
+        const { hasDiff, chunk } = await diffPbEntry(token, entry);
+        if (hasDiff) {
+            diffCount++;
+            chunks.push(chunk);
+        }
     }
 
     if (diffCount === 0) {
         console.log('No differences found — all tracked files match the remote.');
     } else {
+        const combined = Buffer.concat(chunks);
+        const pager = process.env.PAGER || 'less';
+        const pagerArgs = pager === 'less' ? ['-R', '-F'] : [];
+        spawnSync(pager, pagerArgs, { input: combined, stdio: ['pipe', 'inherit', 'inherit'] });
         console.log(`\n${diffCount} file(s) differ from remote.`);
     }
 }
@@ -68,6 +79,7 @@ async function diff(targetArg) {
 // hand both sides to `git diff --no-index`.
 function diffCodeEntries(entries, remoteCodeMap) {
     let diffCount = 0;
+    const chunks = [];
     const tmpFiles = [];
     try {
         for (const entry of entries) {
@@ -86,17 +98,17 @@ function diffCodeEntries(entries, remoteCodeMap) {
             writeFileSync(tmpPath, (remoteCode ?? '').trim() + '\n', 'utf-8');
             tmpFiles.push(tmpPath);
 
-            console.log(`\n=== ${entry.path}  [${entry.name}] ===`);
-
             const result = spawnSync(
                 'git',
                 ['diff', '--no-index', '--color=always', tmpPath, entry.path],
-                { stdio: ['ignore', 'inherit', 'inherit'] }
+                { stdio: ['ignore', 'pipe', 'pipe'] }
             );
             // exit code 1 means differences found (normal), 0 means identical, >1 means error
             if (result.status !== null && result.status > 1) {
                 console.error(`git diff failed for ${entry.path}`);
             }
+            const header = Buffer.from(`\n=== ${entry.path}  [${entry.name}] ===\n`);
+            chunks.push(Buffer.concat([header, result.stdout ?? Buffer.alloc(0)]));
             diffCount++;
         }
     } finally {
@@ -108,7 +120,7 @@ function diffCodeEntries(entries, remoteCodeMap) {
             }
         }
     }
-    return diffCount;
+    return { diffCount, chunks };
 }
 
 // Process-builder wizard: decompose the upstream payload into a throwaway
@@ -136,18 +148,19 @@ async function diffPbEntry(token, entry) {
         // and never matches the raw upstream xml byte-for-byte even when nothing
         // structural changed, so it'd otherwise look like a permanent false diff.
         if (localChecksum(projectReader(upstreamDir)) === localChecksum(projectReader(localDir)))
-            return false;
+            return { hasDiff: false };
 
-        console.log(`\n=== ${entry.path}  [${entry.name}] (process-builder) ===`);
         const result = spawnSync(
             'git',
             ['diff', '--no-index', '--color=always', 'upstream', 'local'],
-            { cwd: tmpRoot, stdio: ['ignore', 'inherit', 'inherit'] }
+            { cwd: tmpRoot, stdio: ['ignore', 'pipe', 'pipe'] }
         );
         if (result.status !== null && result.status > 1) {
             console.error(`git diff failed for ${entry.path}`);
         }
-        return true;
+        const header = Buffer.from(`\n=== ${entry.path}  [${entry.name}] (process-builder) ===\n`);
+        const chunk = Buffer.concat([header, result.stdout ?? Buffer.alloc(0)]);
+        return { hasDiff: true, chunk };
     } finally {
         rmSync(tmpRoot, { recursive: true, force: true });
     }

package/src/agrippa/commands/pb.js

@@ -25,7 +25,7 @@ import {
     connect,
     disconnect,
     eachNode,
-    lintGateways,
+    lintAll,
     listGraph,
     removeNode,
     setDefault,
@@ -125,9 +125,9 @@ async function pbFormat(opts) {
     console.log(
         `Formatted ${dir} (${nodes} node(s) laid out${missing ? `, ${missing} without layout` : ''}).`
     );
-    const issues = lintGateways(structure);
+    const issues = lintAll(structure);
     if (issues.length) {
-        console.warn('Gateway issues (exclusiveGateway default/condition rule):');
+        console.warn('Diagram issues:');
         for (const w of issues) console.warn(`  ! ${w}`);
     }
 }
@@ -276,4 +276,16 @@ async function pbPreview(opts) {
     console.log(`Wrote ${out} (${svg.length} bytes).`);
 }
 
-export { pbFormat, pbAdd, pbRemove, pbConnect, pbDisconnect, pbSetDefault, pbList, pbPreview };
+async function pbLint(opts) {
+    const dir = await resolveProjectPath(opts);
+    const { structure } = loadProject(dir);
+    const issues = lintAll(structure);
+    if (!issues.length) {
+        console.log('No issues.');
+    } else {
+        for (const w of issues) console.warn(`  ! ${w}`);
+        process.exitCode = 1;
+    }
+}
+
+export { pbFormat, pbAdd, pbRemove, pbConnect, pbDisconnect, pbSetDefault, pbList, pbPreview, pbLint };

package/src/agrippa/commands/pull.js

@@ -5,7 +5,7 @@ import { describeWorkflow, getPhasesByIds, getPhasesByWorkflow, listMfas } from
 import { computeChecksum } from '../lib/checksum.js';
 import { loadEffectiveEnv, readConfig, writeConfig } from '../lib/config.js';
 import { getProcess } from '../lib/pbApi.js';
-import { localChecksum } from '../lib/pbProject.js';
+import { localChecksum, remoteChecksumPb } from '../lib/pbProject.js';
 import { projectReader } from '../lib/pbWorkspace.js';
 import {
     fileExists,
@@ -63,13 +63,13 @@ async function pull() {
             const localCode = readCodeFile(entry.path);
 
             const remoteChecksum = computeChecksum(remoteCode ?? '');
-            const localChecksum = computeChecksum(localCode ?? '');
+            const localChecksumVal = computeChecksum(localCode ?? '');
             const pullChecksum = entry.checksum_at_pull;
 
             let status;
-            if (pullChecksum === localChecksum && pullChecksum === remoteChecksum) {
+            if (localChecksumVal === remoteChecksum) {
                 status = 'unchanged';
-            } else if (pullChecksum === localChecksum) {
+            } else if (pullChecksum === localChecksumVal) {
                 status = 'fast-forward';
             } else {
                 status = 'conflict';
@@ -116,11 +116,10 @@ async function pull() {
 }
 
 // Refresh tracked wizards from upstream. Pull concern (inverted from push):
-// overwriting *local* edits. Status per entry from three states —
-// checksum_at_pull, current local (recomposed), upstream updated_date:
-//   unchanged    remote not advanced → nothing to bring down
-//   fast-forward remote advanced, local untouched since pull → safe overwrite
-//   conflict     remote advanced AND local diverged → overwrite loses local work
+// overwriting *local* edits. Status per entry:
+//   unchanged    local === remote semantically → nothing to do
+//   fast-forward remote changed, local untouched since pull → safe overwrite
+//   conflict     local diverged from checksum_at_pull → overwrite loses local work
 async function pullPbEntries(token, config) {
     const entries = config.workspace.filter((e) => e.object_type === 'process_builder');
     if (!entries.length) return;
@@ -140,12 +139,13 @@ async function pullPbEntries(token, config) {
             console.warn(`  ${entry.name}: could not fetch upstream, skipping`);
             continue;
         }
-        const local = localChecksum(projectReader(entry.path));
-        const localChanged = entry.checksum_at_pull !== local;
-        const remoteChanged = upstream.updated_date !== entry.updated_date;
+        const localSemantic = localChecksum(projectReader(entry.path));
+        const remoteSemantic = remoteChecksumPb(upstream);
+        const pullChecksum = entry.checksum_at_pull;
         let status;
-        if (!remoteChanged) status = 'unchanged';
-        else status = localChanged ? 'conflict' : 'fast-forward';
+        if (localSemantic === remoteSemantic) status = 'unchanged';
+        else if (pullChecksum === localSemantic) status = 'fast-forward';
+        else status = 'conflict';
         classified.push({ ...entry, upstream, status });
     }
 

package/src/agrippa/commands/push.js

@@ -6,7 +6,7 @@ import { updateMfa, updatePhase } from '../lib/api.js';
 import { computeChecksum } from '../lib/checksum.js';
 import { loadEffectiveEnv, readConfig, writeConfig } from '../lib/config.js';
 import { getProcess } from '../lib/pbApi.js';
-import { localChecksum } from '../lib/pbProject.js';
+import { localChecksum, remoteChecksumPb } from '../lib/pbProject.js';
 import { projectReader } from '../lib/pbWorkspace.js';
 import { fileExists, readCodeFile } from '../lib/workspace.js';
 import { fetchRemoteCode, selectEntries } from './pull.js';
@@ -71,12 +71,12 @@ async function push(opts = {}) {
     const classified = config.workspace.map((entry) => {
         if (entry.object_type === 'process_builder') {
             const upstream = upstreamMap.get(entry.guid) ?? null;
-            const local = localChecksum(projectReader(entry.path));
-            const localChanged = entry.checksum_at_pull !== local;
-            const remoteChanged = !upstream || upstream.updated_date !== entry.updated_date;
+            const localSemantic = localChecksum(projectReader(entry.path));
+            const remoteSemantic = upstream ? remoteChecksumPb(upstream) : null;
+            const pullChecksum = entry.checksum_at_pull;
             let status;
-            if (!localChanged && !remoteChanged) status = 'unchanged';
-            else if (!remoteChanged) status = 'fast-forward';
+            if (localSemantic === remoteSemantic) status = 'unchanged';
+            else if (pullChecksum === remoteSemantic) status = 'fast-forward';
             else status = 'conflict';
             return { ...entry, upstream, status };
         }
@@ -88,8 +88,7 @@ async function push(opts = {}) {
         const localChecksumVal = computeChecksum(localCode ?? '');
         const pullChecksum = entry.checksum_at_pull;
         let status;
-        if (pullChecksum === localChecksumVal && pullChecksum === remoteChecksum)
-            status = 'unchanged';
+        if (localChecksumVal === remoteChecksum) status = 'unchanged';
         else if (pullChecksum === remoteChecksum) status = 'fast-forward';
         else status = 'conflict';
         return { ...entry, remoteCode, localCode, status };

package/src/agrippa/index.js

@@ -10,6 +10,7 @@ import {
     pbConnect,
     pbDisconnect,
     pbFormat,
+    pbLint,
     pbList,
     pbPreview,
     pbRemove,
@@ -171,6 +172,11 @@ pb.command('set-default')
     .option('--pb <document_id>', 'Target wizard')
     .action((opts) => pbSetDefault(opts).catch(die));
 
+pb.command('lint')
+    .description('Check diagram for structural issues (edge names, incoming-edge rules, gateway rules)')
+    .option('--pb <document_id>', 'Target wizard')
+    .action((opts) => pbLint(opts).catch(die));
+
 pb.command('ls')
     .description('List nodes and edges (discover ids without reading the YAML)')
     .option('--pb <document_id>', 'Target wizard')

package/src/agrippa/lib/pbEdit.js

@@ -44,6 +44,20 @@ const PREFIX = {
 
 const CONTAINER = new Set(['subProcess', 'transaction']);
 
+// Default attrs injected at node creation so the editor accepts them without manual edits.
+const DEFAULT_ATTRS = {
+    scriptTask: {
+        scriptFormat: 'javascript',
+        'activiti:async': 'false',
+        'activiti:exclusive': 'false',
+        'activiti:autoStoreVariables': 'false',
+    },
+    serviceTask: {
+        'activiti:async': 'false',
+        'activiti:exclusive': 'false',
+    },
+};
+
 // Depth-first visit of every node in the nested graph, with its parent node.
 function eachNode(nodes, parent, fn) {
     for (const n of nodes || []) {
@@ -161,6 +175,8 @@ function addNode(structure, manifest, opts, ctx = {}) {
         node.nodes = [];
     }
 
+    if (DEFAULT_ATTRS[type]) node.attrs = { ...DEFAULT_ATTRS[type] };
+
     if (parentId) {
         const f = findNode(structure, parentId);
         if (!f) throw new Error(`parent not found: ${parentId}`);
@@ -334,10 +350,9 @@ function connect(structure, { from, to, name, condition, conditionType, makeDefa
                 warnings.push(`replaced previous default flow ${prev} on ${from}.`);
         }
     }
-    // Re-check the gateway's invariant after the edit.
-    if (sf.node.type === 'exclusiveGateway') {
-        warnings.push(...lintGateways(structure).filter((w) => w.startsWith(from)));
-    }
+    // Re-check all structural invariants after the edit, scoped to affected nodes.
+    const allIssues = lintAll(structure);
+    warnings.push(...allIssues.filter((w) => w.startsWith(from) || w.startsWith(to)));
 
     return { writes: {}, deletes: [], result: { id, from, to, warnings } };
 }
@@ -407,6 +422,64 @@ function lintGateways(structure) {
     return issues;
 }
 
+// Flag non-default outgoing edges that are missing a name when a node has 2+
+// outgoing flows. In Activiti diagrams these labels are mandatory so operators
+// can distinguish branches at runtime.
+function lintEdgeNames(structure) {
+    const issues = [];
+    eachNode(structure.nodes, null, (n) => {
+        const outs = n.edges || [];
+        if (outs.length < 2) return;
+        const def = n.attrs?.default;
+        for (const e of outs) {
+            if (e.id === def) continue;
+            if (!e.name) {
+                issues.push(
+                    `${n.id} → ${e.target} (${e.id}): non-default flow has no name.`
+                );
+            }
+        }
+    });
+    return issues;
+}
+
+// Flag incoming-edge violations:
+// - Only exclusiveGateway may have >1 incoming flows.
+// - An exclusiveGateway may not have both >1 incoming AND >1 outgoing (pick one
+//   direction for merging or splitting, not both at once).
+function lintIncomingEdges(structure) {
+    const inCount = {};
+    const outCount = {};
+    eachNode(structure.nodes, null, (n) => {
+        for (const e of n.edges || []) {
+            inCount[e.target] = (inCount[e.target] || 0) + 1;
+            outCount[n.id] = (outCount[n.id] || 0) + 1;
+        }
+    });
+
+    const issues = [];
+    eachNode(structure.nodes, null, (n) => {
+        const inc = inCount[n.id] || 0;
+        const out = outCount[n.id] || 0;
+        if (inc > 1 && n.type !== 'exclusiveGateway') {
+            issues.push(
+                `${n.id} (${n.name || n.type}): only exclusiveGateway may have multiple incoming flows (has ${inc}).`
+            );
+        }
+        if (n.type === 'exclusiveGateway' && inc > 1 && out > 1) {
+            issues.push(
+                `${n.id} (${n.name || 'gateway'}): exclusiveGateway may not have both multiple incoming (${inc}) and multiple outgoing (${out}) flows.`
+            );
+        }
+    });
+    return issues;
+}
+
+// Run all lint rules and return combined issues.
+function lintAll(structure) {
+    return [...lintGateways(structure), ...lintEdgeNames(structure), ...lintIncomingEdges(structure)];
+}
+
 // Remove an edge by id, or by --from/--to pair.
 function disconnect(structure, { id, from, to }) {
     let removed = 0;
@@ -464,4 +537,7 @@ export {
     setDefault,
     listGraph,
     lintGateways,
+    lintEdgeNames,
+    lintIncomingEdges,
+    lintAll,
 };

package/src/agrippa/lib/pbLayout.js

@@ -37,7 +37,13 @@ const ROOT_OPTS = {
     'elk.layered.spacing.edgeEdgeBetweenLayers': '20',
     'elk.layered.spacing.edgeNodeBetweenLayers': '20',
 };
-const CONTAINER_OPTS = { 'elk.padding': '[top=40.0,left=20.0,bottom=20.0,right=20.0]' };
+const CONTAINER_OPTS = {
+    'elk.padding': '[top=50.0,left=30.0,bottom=50.0,right=30.0]',
+    'elk.layered.spacing.nodeNodeBetweenLayers': '60',
+    'elk.spacing.nodeNode': '80',
+    'elk.spacing.edgeNode': '20',
+    'elk.layered.spacing.edgeNodeBetweenLayers': '20',
+};
 
 function sizeOf(n) {
     if (SIZE[n.type]) return SIZE[n.type];
@@ -147,6 +153,9 @@ async function autoLayout(structure) {
                 sources: [source],
                 targets: [e.target],
                 sourcePort,
+                labels: e.name
+                    ? [{ id: `${e.id}__lbl`, text: e.name, width: Math.min(e.name.length * 6, 140), height: 14 }]
+                    : [],
                 layoutOptions: {
                     'elk.layered.priority.straightness': isHappy ? '10' : 1,
                     'elk.layered.priority.shortness': isHappy ? '10' : 1,
@@ -237,8 +246,20 @@ async function autoLayout(structure) {
                 height: round(p.height),
             };
         for (const e of n.edges || []) {
-            const wp = waypointsFor(e.id, lcaOffset(n.id, e.target));
+            const off = lcaOffset(n.id, e.target);
+            const wp = waypointsFor(e.id, off);
             if (wp) e.waypoints = wp;
+            if (e.name) {
+                const lbl = elkEdges[e.id]?.labels?.[0];
+                if (lbl) {
+                    e.labelPos = {
+                        x: round(lbl.x + off.x),
+                        y: round(lbl.y + off.y),
+                        width: round(lbl.width),
+                        height: round(lbl.height),
+                    };
+                }
+            }
         }
     });
 

package/src/agrippa/lib/pbModel.js

@@ -353,8 +353,9 @@ function boundsAttrs(b) {
 }
 
 // Rebuild <bpmndi> purely from structure.yaml geometry (model graph + geo maps).
-// DI element ids are derived (`<id>_di`); the manifest is never consulted. Labels
-// are omitted (renderers auto-place them); only positions, sizes, waypoints and
+// DI element ids are derived (`<id>_di`); the manifest is never consulted. Node
+// labels are omitted (renderers auto-place them); edge labels use ELK-computed
+// bounds from geo.labelPos when present — only positions, sizes, waypoints and
 // subprocess expand-state are authoritative — see compareDiagram.
 function buildDiagram(model, geo) {
     if (!geo) return null;
@@ -373,10 +374,12 @@ function buildDiagram(model, geo) {
     const pushEdge = (id) => {
         const wps = geo.waypoints[id];
         if (!wps) return;
-        const pts = wps.map(([x, y]) =>
-            el('omgdi:waypoint', { '@_x': String(x), '@_y': String(y) }, [])
-        );
-        edgeEls.push(el('bpmndi:BPMNEdge', { '@_id': `${id}_di`, '@_bpmnElement': id }, pts));
+        const children = [];
+        const lp = geo.labelPos?.[id];
+        for (const [x, y] of wps)
+            children.push(el('omgdi:waypoint', { '@_x': String(x), '@_y': String(y) }, []));
+        if (lp) children.push(el('bpmndi:BPMNLabel', {}, [el('omgdc:Bounds', boundsAttrs(lp), [])]));
+        edgeEls.push(el('bpmndi:BPMNEdge', { '@_id': `${id}_di`, '@_bpmnElement': id }, children));
     };
     for (const e of model.edges) pushEdge(e.id);
     for (const a of model.associations || []) pushEdge(a.id);

package/src/agrippa/lib/pbPreview.js

@@ -91,9 +91,11 @@ function toSvg(structure) {
             `<polyline points="${pts}" fill="none" stroke="#444" stroke-width="1.5" marker-end="url(#arrow)"/>`
         );
         if (e.name) {
-            const m = e.waypoints[Math.floor(e.waypoints.length / 2)];
+            const lp = e.labelPos;
+            const lx = lp ? lp.x + lp.width / 2 : e.waypoints[Math.floor(e.waypoints.length / 2)][0];
+            const ly = lp ? lp.y + lp.height / 2 : e.waypoints[Math.floor(e.waypoints.length / 2)][1] - 4;
             out.push(
-                `<text x="${m[0] + ox}" y="${m[1] + oy - 4}" text-anchor="middle" fill="#666" font-size="9">${esc(e.name)}</text>`
+                `<text x="${lx + ox}" y="${ly + oy}" text-anchor="middle" fill="#666" font-size="9">${esc(e.name)}</text>`
             );
         }
     }

package/src/agrippa/lib/pbProject.js

@@ -169,6 +169,7 @@ function flattenNodes(structNodes, parentId, model, read, geo) {
             if (se.documentation !== undefined) e.documentation = se.documentation;
             if (parentId) e.parent = parentId;
             if (se.waypoints) geo.waypoints[se.id] = se.waypoints;
+            if (se.labelPos) geo.labelPos[se.id] = se.labelPos;
             model.edges.push(e);
         }
         if (sn.nodes) flattenNodes(sn.nodes, sn.id, model, read, geo);
@@ -264,7 +265,7 @@ function recompose(read) {
         annotations: structure.annotations || [],
         associations: structure.associations || [],
     };
-    const geo = { bounds: {}, waypoints: {}, expanded: {} };
+    const geo = { bounds: {}, waypoints: {}, expanded: {}, labelPos: {} };
     flattenNodes(structure.nodes, null, model, read, geo);
     // annotation/association geometry (top-level lists carry it inline)
     for (const a of model.annotations) if (a.layout) geo.bounds[a.id] = a.layout;
@@ -342,6 +343,15 @@ function localChecksum(read) {
     return computeChecksum(stableStringify(recompose(read)));
 }
 
+// Semantic checksum of a remote payload. Decompose → recompose normalises field
+// order and non-semantic server-side differences, same pipeline as localChecksum
+// so the two are directly comparable.
+function remoteChecksumPb(payload) {
+    const { files } = decompose(payload);
+    const read = (p) => files[p] ?? '';
+    return computeChecksum(stableStringify(recompose(read)));
+}
+
 // Enumerate the wizard's pages from the pages/*.yml files (the authoritative
 // local set). Each page links to its userTask via `page._id.stepkey`; the
 // manifest supplies the upstream page guid (absent => a locally-added page that
@@ -379,6 +389,7 @@ export {
     verifyRoundTrip,
     stableStringify,
     localChecksum,
+    remoteChecksumPb,
     enumeratePages,
     stringifyStructure,
     pad,