@uipath/maestro-builder-sdk 6.11.5 → 6.12.0

package/dist/bpmn/graph.d.ts

@@ -0,0 +1,69 @@
+/**
+ * bpmn/graph — the resolved wiring of a built process, printed for review.
+ *
+ * `bpmn check --graph` exists because two things now write flows the author never
+ * typed: the nesting constructs (an arm's chain, a handler's path, a synthesized
+ * join) and `flowMode('sequence')` (consecutive siblings). Both are deterministic,
+ * but a reviewer reading the source cannot see the edge that inserting a line
+ * added or moved. This prints every element in placement order with the flows
+ * leaving it, an implied edge marked `~>` and an explicit one `->`, so the diff of
+ * the printed graph is the diff of what the builder actually inferred.
+ *
+ * Read-only over the built IR; nothing here changes what `serialize` emits.
+ */
+import { type BuiltBpmn } from './bpmn-sdk.js';
+/** One element of the printed graph, with the flows leaving it. */
+export interface GraphNode {
+    /** The element's id. */
+    id: string;
+    /** The builder's node kind, e.g. `scriptTask` or `exclusiveGateway`. */
+    kind: string;
+    /** The element's display name, when it has one. */
+    name?: string;
+    /** Flows leaving this element, in flow order. */
+    outgoing: GraphEdge[];
+    /** How many flows arrive. */
+    incoming: number;
+    /** Set when the element is an event sub-process, a boundary event, or a start: nothing is expected to lead into it. */
+    entersOnItsOwn?: boolean;
+    /** A nested scope's own graph. */
+    children?: GraphScope;
+}
+/** One flow leaving an element, as the graph prints it. */
+export interface GraphEdge {
+    /** The element the flow arrives at. */
+    to: string;
+    /** The flow's id. */
+    flow: string;
+    /** Whether the builder wrote the flow by inference rather than from an explicit `.sequenceFlow()`. */
+    implied: boolean;
+    /** The flow's condition expression, when it has one. */
+    condition?: string;
+    /** Whether this flow is its gateway's default. */
+    default?: boolean;
+}
+/** A scope's graph: the process root or one sub-process body. */
+export interface GraphScope {
+    /** The scope, e.g. `process "orders"` or `subProcess "batch"`. */
+    scope: string;
+    /** The scope's elements, in placement order. */
+    nodes: GraphNode[];
+    /** Ids of elements nothing leads into, that are not entry points of their own. */
+    unreachable: string[];
+    /** Ids of elements nothing leaves, that are not end events. */
+    dangling: string[];
+}
+/**
+ * The wiring of a built process as data — what `--json` carries.
+ *
+ * @param built - The process, as `.build()` returned it.
+ * @returns The root scope's graph, sub-processes nested inside their element.
+ */
+export declare function graphModel(built: BuiltBpmn): GraphScope;
+/**
+ * The wiring of a built process as text, one element per line, indented by scope.
+ *
+ * @param built - The process, as `.build()` returned it.
+ * @returns The printed graph, ending in a newline.
+ */
+export declare function renderGraph(built: BuiltBpmn): string;

package/dist/bpmn/graph.js

@@ -0,0 +1,98 @@
+/**
+ * bpmn/graph — the resolved wiring of a built process, printed for review.
+ *
+ * `bpmn check --graph` exists because two things now write flows the author never
+ * typed: the nesting constructs (an arm's chain, a handler's path, a synthesized
+ * join) and `flowMode('sequence')` (consecutive siblings). Both are deterministic,
+ * but a reviewer reading the source cannot see the edge that inserting a line
+ * added or moved. This prints every element in placement order with the flows
+ * leaving it, an implied edge marked `~>` and an explicit one `->`, so the diff of
+ * the printed graph is the diff of what the builder actually inferred.
+ *
+ * Read-only over the built IR; nothing here changes what `serialize` emits.
+ */
+import { isStartLike } from './bpmn-sdk.js';
+const GATEWAYS = new Set(['exclusiveGateway', 'parallelGateway', 'inclusiveGateway', 'eventBasedGateway']);
+function entersOnItsOwn(n) {
+    return isStartLike(n) || n.kind === 'boundaryEvent' || (n.kind === 'subProcess' && n.triggeredByEvent === true);
+}
+function scopeGraph(scope, nodes, flows) {
+    const defaults = new Map();
+    for (const n of nodes)
+        if ((n.kind === 'exclusiveGateway' || n.kind === 'inclusiveGateway') && n.default)
+            defaults.set(n.default, n.id);
+    const incoming = new Map();
+    for (const f of flows)
+        incoming.set(f.target, (incoming.get(f.target) ?? 0) + 1);
+    const out = [];
+    const unreachable = [];
+    const dangling = [];
+    for (const n of nodes) {
+        const outgoing = flows
+            .filter((f) => f.source === n.id)
+            .map((f) => ({
+            to: f.target,
+            flow: f.id,
+            implied: f.implied === true,
+            ...(f.condition !== undefined ? { condition: f.condition } : {}),
+            ...(defaults.get(f.id) === n.id ? { default: true } : {}),
+        }));
+        const ins = incoming.get(n.id) ?? 0;
+        const own = entersOnItsOwn(n);
+        if (!own && ins === 0)
+            unreachable.push(n.id);
+        if (n.kind !== 'endEvent' && !(n.kind === 'subProcess' && n.triggeredByEvent) && outgoing.length === 0)
+            dangling.push(n.id);
+        out.push({
+            id: n.id,
+            kind: n.kind,
+            ...(n.name !== undefined ? { name: n.name } : {}),
+            outgoing,
+            incoming: ins,
+            ...(own ? { entersOnItsOwn: true } : {}),
+            ...(n.kind === 'subProcess' ? { children: scopeGraph(`subProcess "${n.id}"`, n.nodes, n.flows) } : {}),
+        });
+    }
+    return { scope, nodes: out, unreachable, dangling };
+}
+/**
+ * The wiring of a built process as data — what `--json` carries.
+ *
+ * @param built - The process, as `.build()` returned it.
+ * @returns The root scope's graph, sub-processes nested inside their element.
+ */
+export function graphModel(built) {
+    return scopeGraph(`process "${built.id}"`, built.nodes, built.flows);
+}
+/**
+ * The wiring of a built process as text, one element per line, indented by scope.
+ *
+ * @param built - The process, as `.build()` returned it.
+ * @returns The printed graph, ending in a newline.
+ */
+export function renderGraph(built) {
+    const lines = ['# ->  explicit .sequenceFlow()      ~>  implied by nesting or flowMode(\'sequence\')'];
+    const walk = (g, depth) => {
+        const pad = '  '.repeat(depth);
+        lines.push(`${pad}${g.scope}`);
+        for (const n of g.nodes) {
+            const label = `${pad}  ${n.kind.padEnd(22)} ${n.id}${n.name !== undefined ? `  "${n.name}"` : ''}`;
+            const notes = [];
+            if (g.unreachable.includes(n.id))
+                notes.push('NO INCOMING');
+            if (g.dangling.includes(n.id))
+                notes.push('NO OUTGOING');
+            if (n.incoming > 1 && !GATEWAYS.has(n.kind))
+                notes.push(`${n.incoming} incoming`);
+            lines.push(notes.length ? `${label}    [${notes.join(', ')}]` : label);
+            for (const o of n.outgoing) {
+                const tags = [o.default ? 'default' : '', o.condition !== undefined ? `when ${o.condition}` : ''].filter(Boolean);
+                lines.push(`${pad}    ${o.implied ? '~>' : '->'} ${o.to}  (${o.flow})${tags.length ? `  ${tags.join(', ')}` : ''}`);
+            }
+            if (n.children)
+                walk(n.children, depth + 2);
+        }
+    };
+    walk(graphModel(built), 0);
+    return lines.join('\n') + '\n';
+}

package/dist/bpmn/intsvc.js

@@ -76,7 +76,7 @@ export function createConnectorEvent(ctx, n) {
             `${type === 'Intsvc.EventTrigger' ? '.eventTrigger()' : '.waitForEvent()'} instead.`);
     }
     const conn = connectorBindingRef(ctx, n.connection, 'Connection', 'ConnectionId', `${rc.connectorKey} connection`);
-    const folder = connectorBindingRef(ctx, n.folder, 'Connection', 'folderKey', 'FolderKey');
+    const folder = connectorBindingRef(ctx, n.folder, 'Connection', 'folderKey', 'FolderKey', conn?.resourceKey);
     if (!conn || !folder) {
         throw new Error(`connector event "${n.id}" needs both a connection and a folder binding name — ` +
             `the type declares connectionId, folderId, folderPath and folderKey all required.`);
@@ -129,7 +129,7 @@ export function createExternalTask(ctx, n) {
             `The shipped library has very few of these — ${wanted === 'AgentExecution' ? '2' : '1'} operation(s).`);
     }
     const conn = connectorBindingRef(ctx, n.connection, 'Connection', 'ConnectionId', `${rc.connectorKey} connection`);
-    const folder = connectorBindingRef(ctx, n.folder, 'Connection', 'folderKey', 'FolderKey');
+    const folder = connectorBindingRef(ctx, n.folder, 'Connection', 'folderKey', 'FolderKey', conn?.resourceKey);
     if (!conn || !folder) {
         throw new Error(`external ${n.family} "${n.id}" needs both a connection and a folder binding name.`);
     }

package/dist/bpmn/known-methods.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Method names the platform expects to be CALLED, not merely named.
+ *
+ * Generated — do not edit by hand. Run `node scripts/gen-bpmn-known-methods.mjs`
+ * to refresh from the installed `@uipath/maestro-sdk`.
+ *
+ * The canvas validator's `METHOD_MISSING_PARENTHESES` rule reads this list: an
+ * expression containing `.<name>` not followed by `(` is an ERROR when `<name>` is
+ * one of these. It is the platform's own vocabulary of .NET/Jint methods reachable
+ * from an expression, copied verbatim so the SDK can report the same thing a rung
+ * earlier. `tests/bpmn-check-platform-rules.test.ts` fails if the copy drifts.
+ */
+export declare const KNOWN_METHODS: readonly string[];
+/** The same list as a set, for the check's inner loop. */
+export declare const KNOWN_METHOD_SET: ReadonlySet<string>;

package/dist/bpmn/known-methods.js

@@ -0,0 +1,271 @@
+/**
+ * Method names the platform expects to be CALLED, not merely named.
+ *
+ * Generated — do not edit by hand. Run `node scripts/gen-bpmn-known-methods.mjs`
+ * to refresh from the installed `@uipath/maestro-sdk`.
+ *
+ * The canvas validator's `METHOD_MISSING_PARENTHESES` rule reads this list: an
+ * expression containing `.<name>` not followed by `(` is an ERROR when `<name>` is
+ * one of these. It is the platform's own vocabulary of .NET/Jint methods reachable
+ * from an expression, copied verbatim so the SDK can report the same thing a rung
+ * earlier. `tests/bpmn-check-platform-rules.test.ts` fails if the copy drifts.
+ */
+export const KNOWN_METHODS = [
+    'Abs',
+    'Acos',
+    'AcosPi',
+    'Acosh',
+    'Add',
+    'AddDays',
+    'AddHours',
+    'AddMicroseconds',
+    'AddMilliseconds',
+    'AddMinutes',
+    'AddMonths',
+    'AddSeconds',
+    'AddTicks',
+    'AddYears',
+    'Asin',
+    'AsinPi',
+    'Asinh',
+    'Atan',
+    'Atan2',
+    'Atan2Pi',
+    'AtanPi',
+    'Atanh',
+    'BigMul',
+    'BitDecrement',
+    'BitIncrement',
+    'Cbrt',
+    'Ceiling',
+    'ChangeType',
+    'Clamp',
+    'Clone',
+    'Compare',
+    'CompareOrdinal',
+    'CompareTo',
+    'Concat',
+    'Contains',
+    'ConvertFromUtf32',
+    'ConvertToInteger',
+    'ConvertToIntegerNative',
+    'Copy',
+    'CopySign',
+    'CopyTo',
+    'Cos',
+    'CosPi',
+    'Cosh',
+    'Create',
+    'CreateChecked',
+    'CreateSaturating',
+    'CreateTruncating',
+    'CreateVersion7',
+    'DaysInMonth',
+    'Deconstruct',
+    'DegreesToRadians',
+    'DivRem',
+    'Divide',
+    'Duration',
+    'EndsWith',
+    'Equals',
+    'Exp',
+    'Exp10',
+    'Exp10M1',
+    'Exp2',
+    'Exp2M1',
+    'ExpM1',
+    'Finalize',
+    'Floor',
+    'Format',
+    'FromBase64CharArray',
+    'FromBase64String',
+    'FromBinary',
+    'FromDays',
+    'FromFileTime',
+    'FromFileTimeUtc',
+    'FromHexString',
+    'FromHours',
+    'FromMicroseconds',
+    'FromMilliseconds',
+    'FromMinutes',
+    'FromOACurrency',
+    'FromOADate',
+    'FromSeconds',
+    'FromTicks',
+    'FusedMultiplyAdd',
+    'GetBits',
+    'GetDateTimeFormats',
+    'GetEnumerator',
+    'GetHashCode',
+    'GetNumericValue',
+    'GetPinnableReference',
+    'GetType',
+    'GetTypeCode',
+    'GetUnicodeCategory',
+    'Hypot',
+    'IEEERemainder',
+    'ILogB',
+    'Ieee754Remainder',
+    'IndexOf',
+    'IndexOfAny',
+    'Insert',
+    'Intern',
+    'IsAscii',
+    'IsAsciiDigit',
+    'IsAsciiHexDigit',
+    'IsAsciiHexDigitLower',
+    'IsAsciiHexDigitUpper',
+    'IsAsciiLetter',
+    'IsAsciiLetterLower',
+    'IsAsciiLetterOrDigit',
+    'IsAsciiLetterUpper',
+    'IsBetween',
+    'IsCanonical',
+    'IsControl',
+    'IsDBNull',
+    'IsDaylightSavingTime',
+    'IsDigit',
+    'IsEvenInteger',
+    'IsFinite',
+    'IsHighSurrogate',
+    'IsInfinity',
+    'IsInteger',
+    'IsInterned',
+    'IsLeapYear',
+    'IsLetter',
+    'IsLetterOrDigit',
+    'IsLowSurrogate',
+    'IsLower',
+    'IsNaN',
+    'IsNegative',
+    'IsNegativeInfinity',
+    'IsNormal',
+    'IsNormalized',
+    'IsNullOrEmpty',
+    'IsNullOrWhiteSpace',
+    'IsNumber',
+    'IsOddInteger',
+    'IsPositive',
+    'IsPositiveInfinity',
+    'IsPow2',
+    'IsPunctuation',
+    'IsRealNumber',
+    'IsSeparator',
+    'IsSubnormal',
+    'IsSurrogate',
+    'IsSurrogatePair',
+    'IsSymbol',
+    'IsUpper',
+    'IsWhiteSpace',
+    'Join',
+    'LastIndexOf',
+    'LastIndexOfAny',
+    'LeadingZeroCount',
+    'Lerp',
+    'Log',
+    'Log10',
+    'Log10P1',
+    'Log2',
+    'Log2P1',
+    'LogP1',
+    'Max',
+    'MaxMagnitude',
+    'MaxMagnitudeNumber',
+    'MaxNumber',
+    'MemberwiseClone',
+    'Min',
+    'MinMagnitude',
+    'MinMagnitudeNumber',
+    'MinNumber',
+    'Multiply',
+    'MultiplyAddEstimate',
+    'Negate',
+    'NewGuid',
+    'Normalize',
+    'PadLeft',
+    'PadRight',
+    'Parse',
+    'ParseExact',
+    'PopCount',
+    'Pow',
+    'RadiansToDegrees',
+    'ReciprocalEstimate',
+    'ReciprocalSqrtEstimate',
+    'ReferenceEquals',
+    'Remainder',
+    'Remove',
+    'Replace',
+    'ReplaceLineEndings',
+    'RootN',
+    'RotateLeft',
+    'RotateRight',
+    'Round',
+    'Scale',
+    'ScaleB',
+    'Sign',
+    'Sin',
+    'SinCos',
+    'SinCosPi',
+    'SinPi',
+    'Sinh',
+    'SpecifyKind',
+    'Split',
+    'Sqrt',
+    'StartsWith',
+    'Substring',
+    'Subtract',
+    'Tan',
+    'TanPi',
+    'Tanh',
+    'ToBase64CharArray',
+    'ToBase64String',
+    'ToBinary',
+    'ToBoolean',
+    'ToByte',
+    'ToByteArray',
+    'ToChar',
+    'ToCharArray',
+    'ToDateTime',
+    'ToDecimal',
+    'ToDouble',
+    'ToFileTime',
+    'ToFileTimeUtc',
+    'ToInt16',
+    'ToInt32',
+    'ToInt64',
+    'ToLocalTime',
+    'ToLongDateString',
+    'ToLongTimeString',
+    'ToLower',
+    'ToLowerInvariant',
+    'ToOACurrency',
+    'ToOADate',
+    'ToSByte',
+    'ToShortDateString',
+    'ToShortTimeString',
+    'ToSingle',
+    'ToString',
+    'ToUInt16',
+    'ToUInt32',
+    'ToUInt64',
+    'ToUniversalTime',
+    'ToUpper',
+    'ToUpperInvariant',
+    'TrailingZeroCount',
+    'Trim',
+    'TrimEnd',
+    'TrimStart',
+    'Truncate',
+    'TryFormat',
+    'TryFromBase64Chars',
+    'TryFromBase64String',
+    'TryGetBits',
+    'TryParse',
+    'TryParseExact',
+    'TryToBase64Chars',
+    'TryToHexString',
+    'TryToHexStringLower',
+    'TryWriteBytes',
+];
+/** The same list as a set, for the check's inner loop. */
+export const KNOWN_METHOD_SET = new Set(KNOWN_METHODS);

package/dist/bpmn/lift-verify.d.ts

@@ -0,0 +1,40 @@
+import type { BuiltBpmn } from './bpmn-sdk.js';
+/** The result of building two sources and comparing what they built. */
+export interface GraphComparison {
+    /** Whether the two sources build the same graph. */
+    same: boolean;
+    /** When they do not: which source failed to build, or what differed. */
+    reason?: string;
+}
+/**
+ * The part of a built process that is the process: ordered by id, `implied`
+ * provenance dropped, and `undefined` fields gone the way JSON drops them.
+ *
+ * @param built - A built process.
+ * @returns A string two builds can be compared by.
+ */
+export declare function canonicalGraph(built: BuiltBpmn, renamedFlows?: ReadonlyMap<string, string>): string;
+/**
+ * Build a decompiled source and return its graph.
+ *
+ * The source's `import { bpmn } from "<specifier>"` line is rewritten to `sdkEntry`
+ * so the module resolves from a temp directory, whatever specifier the caller asked
+ * the emitted file to carry.
+ *
+ * @param source - A `.bpmn.ts` source.
+ * @param sdkEntry - Absolute path of the `bpmn-sdk.js` to build against.
+ * @returns The built process.
+ */
+export declare function buildSource(source: string, sdkEntry: string): Promise<BuiltBpmn>;
+/**
+ * Whether two sources build the same graph.
+ *
+ * @param flat - The flat source.
+ * @param nested - The lifted source.
+ * @param sdkEntry - Absolute path of the `bpmn-sdk.js` to build both against.
+ * @param renamedFlows - Flow ids the lift renamed, applied to the flat build before comparing.
+ * @returns `same: true`, or the reason they differ.
+ */
+export declare function sameGraph(flat: string, nested: string, sdkEntry: string, 
+/** Flow ids the lift renamed (`from` → `to`), applied to the FLAT build before comparing — see `LiftSummary.renamedFlows`. */
+renamedFlows?: ReadonlyMap<string, string>): Promise<GraphComparison>;

package/dist/bpmn/lift-verify.js

@@ -0,0 +1,133 @@
+/**
+ * lift-verify — the check that makes `decompile --style nested` safe to write.
+ *
+ * The nested style is a lift of flat regions into the builder's constructs, and
+ * every construct lowers back to plain nodes and flows. So the two sources are
+ * interchangeable exactly when they BUILD THE SAME GRAPH: same elements, same
+ * flows, same variables, ids and payloads included. This builds both and compares
+ * them, and the CLI writes the nested source only when they agree — otherwise the
+ * flat one, with the reason. The lift's own rules are conservative, but a rule is
+ * an argument and this is the measurement.
+ */
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+function sortById(xs) {
+    return [...xs].sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * JSON with every object's keys sorted, so two builds that set the same fields in a
+ * different order — a start event's `payload` before or after its `event` — read as
+ * the same. `Map` values are not expected here; `canonicalGraph` flattens the one it has.
+ */
+function stableJson(value) {
+    return JSON.stringify(value, (_key, v) => v && typeof v === 'object' && !Array.isArray(v)
+        ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, v[k]]))
+        : v);
+}
+/**
+ * The part of a built process that is the process: ordered by id, `implied`
+ * provenance dropped, and `undefined` fields gone the way JSON drops them.
+ *
+ * @param built - A built process.
+ * @returns A string two builds can be compared by.
+ */
+export function canonicalGraph(built, renamedFlows = new Map()) {
+    // A flow the lift renamed is compared under its new id — on the flow itself and on
+    // the gateway `default` that names it. Everything else about it must still agree.
+    const flowId = (id) => renamedFlows.get(id) ?? id;
+    const nodes = (ns) => sortById(ns).map((n) => n.kind === 'subProcess'
+        ? { ...n, nodes: nodes(n.nodes), flows: flows(n.flows), variables: sortById(n.variables) }
+        : 'default' in n && typeof n.default === 'string'
+            ? { ...n, default: flowId(n.default) }
+            : n);
+    // A relabelled edge also sheds an EMPTY label: `name=""` is designer residue an
+    // implied edge has nowhere to carry, and the lift refuses a real one.
+    const flows = (fs) => sortById(fs.map((f) => (renamedFlows.has(f.id) && f.name === '' ? { ...f, id: flowId(f.id), name: undefined } : { ...f, id: flowId(f.id) }))).map(({ implied: _implied, ...f }) => f);
+    return stableJson({
+        id: built.id,
+        name: built.name,
+        metadata: built.metadata,
+        variables: sortById(built.variables),
+        messages: sortById(built.messages),
+        errors: sortById(built.errors),
+        bindings: sortById(built.bindings),
+        schemas: [...built.schemas.entries()].sort(([a], [b]) => a.localeCompare(b)),
+        nodes: nodes(built.nodes),
+        flows: flows(built.flows),
+    });
+}
+/**
+ * Build a decompiled source and return its graph.
+ *
+ * The source's `import { bpmn } from "<specifier>"` line is rewritten to `sdkEntry`
+ * so the module resolves from a temp directory, whatever specifier the caller asked
+ * the emitted file to carry.
+ *
+ * @param source - A `.bpmn.ts` source.
+ * @param sdkEntry - Absolute path of the `bpmn-sdk.js` to build against.
+ * @returns The built process.
+ */
+export async function buildSource(source, sdkEntry) {
+    const dir = mkdtempSync(join(tmpdir(), 'bpmn-lift-'));
+    // `finally`, not a call after the await: the throw below and any error inside the
+    // imported module both escape, and `sameGraph` catches them — which is the path the
+    // tests take most. Cleaning up only on success leaked a directory per failed lift,
+    // two per verify and up to four per `decompile --style nested`.
+    //
+    // Safe to delete once the import has resolved: the module is fully evaluated, the SDK
+    // specifier was rewritten to an absolute path OUTSIDE this directory, and the file
+    // name is `mkdtemp` plus a random suffix, so nothing re-resolves it.
+    try {
+        writeFileSync(join(dir, 'package.json'), '{"type":"module"}\n');
+        const file = join(dir, `Lift-${Math.random().toString(36).slice(2)}.bpmn.ts`);
+        const rewritten = source.replace(/^(import\s*\{[^}]*\}\s*from\s*)["'][^"']+["'];/m, `$1${JSON.stringify(sdkEntry)};`);
+        writeFileSync(file, rewritten);
+        const mod = await import(pathToFileURL(file).href);
+        if (!mod.default || !Array.isArray(mod.default.nodes))
+            throw new Error('the source has no built default export');
+        return mod.default;
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/**
+ * Whether two sources build the same graph.
+ *
+ * @param flat - The flat source.
+ * @param nested - The lifted source.
+ * @param sdkEntry - Absolute path of the `bpmn-sdk.js` to build both against.
+ * @param renamedFlows - Flow ids the lift renamed, applied to the flat build before comparing.
+ * @returns `same: true`, or the reason they differ.
+ */
+export async function sameGraph(flat, nested, sdkEntry, 
+/** Flow ids the lift renamed (`from` → `to`), applied to the FLAT build before comparing — see `LiftSummary.renamedFlows`. */
+renamedFlows = new Map()) {
+    let a;
+    let b;
+    try {
+        a = canonicalGraph(await buildSource(flat, sdkEntry), renamedFlows);
+    }
+    catch (e) {
+        return { same: false, reason: `the flat source did not build: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    try {
+        b = canonicalGraph(await buildSource(nested, sdkEntry));
+    }
+    catch (e) {
+        return { same: false, reason: `the nested source did not build: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    if (a === b)
+        return { same: true };
+    return { same: false, reason: firstDifference(a, b) };
+}
+/** A short pointer at where two canonical graphs part ways. */
+function firstDifference(a, b) {
+    let i = 0;
+    while (i < a.length && i < b.length && a[i] === b[i])
+        i++;
+    const from = Math.max(0, i - 60);
+    return `the graphs differ near …${a.slice(from, i + 80)}… (flat) vs …${b.slice(from, i + 80)}… (nested)`;
+}