@uipath/maestro-builder-sdk 6.62.0 → 6.64.0

package/dist/check.d.ts

@@ -3,12 +3,34 @@ import type { BuiltFlow } from './flow-sdk.js';
 import { type EventCheckOpts } from './core/event-checks.js';
 export type { EventParamFields } from './core/event-checks.js';
 import { type ConnectorCheckOpts } from './core/connector-checks.js';
+import { type RefusalClass } from './core/refusals.js';
 export interface Diagnostic {
     level: 'error' | 'warning';
     code: string;
     message: string;
     step?: string;
     suggestion?: string;
+    /**
+     * The id of the node the finding is on, in the flow `compile` would write:
+     * the step's node, or for a step inside a subflow the node inside it.
+     * Absent for a finding that names no node (a flow-level rule, a refusal
+     * about the whole scope such as two steps with one name).
+     */
+    nodeId?: string;
+    /**
+     * The code's class (`core/refusals.ts`): `lint`, the flow is probably wrong
+     * but `compile` would still write it; `lowering`, `compile` cannot write a
+     * correct `.flow`; `draft`, an unfinished canvas node. Set on every finding
+     * whose code the table lists.
+     */
+    class?: RefusalClass;
+    /**
+     * Only when `check` is given a baseline (`flow check --baseline`, {@link scopeToEdit}):
+     * `pre-existing` when the finding's node is unchanged from the baseline and
+     * the baseline reports the same code on it, so the edit did not cause it
+     * (such a finding is a warning); `edited` for every other finding.
+     */
+    origin?: 'edited' | 'pre-existing';
 }
 export interface ListEnvelopeFields {
     envelope: string | null;
@@ -47,6 +69,64 @@ export interface CheckOpts extends ConnectorCheckOpts, EventCheckOpts {
     serializer?: false;
 }
 export declare function check(built: BuiltFlow, opts?: CheckOpts): Diagnostic[];
+/**
+ * What {@link checkCompiled} found, with the flow its serializer pass compiled,
+ * which {@link scopeToEdit} compares against a baseline.
+ */
+export interface CheckedFlow {
+    diagnostics: Diagnostic[];
+    /**
+     * The collect-mode compile, stand-ins and all (`SerializeOpts.collect`);
+     * nothing writes it. `undefined` when collection stopped or the serializer
+     * pass was skipped.
+     */
+    flow: any;
+    /**
+     * The refusal that stopped collection (a scope-level one, such as two Ends
+     * with one name), or the internal error that did: no serializer finding past
+     * it is reported. Absent when collection ran to the end or was skipped.
+     */
+    stoppedAt?: {
+        code?: string;
+        message: string;
+    };
+}
+/**
+ * `check`, keeping the flow its serializer pass compiled. Each finding is
+ * placed on its node (`nodeId`: a refusal on the node collect mode claimed for
+ * its step, any other finding on the node its step emitted) and given its
+ * code's `class`.
+ */
+export declare function checkCompiled(built: BuiltFlow, opts?: CheckOpts): CheckedFlow;
+/**
+ * Scope `edited`'s findings to the edit, against `baseline`: the original
+ * `.flow` decompiled and checked the same way (`flow check --baseline`,
+ * docs/CHECK_COMPILE_CONTRACT_DESIGN.md §3.3). Every finding gets an `origin`:
+ *
+ *   - `pre-existing` when its node is unchanged from the baseline (by id and
+ *     content, as merge judges it: `classifyDrafts`; a node inside a subflow
+ *     by its subflow) AND the baseline reports the same code on that node,
+ *     once per occurrence. A finding that names no node is `pre-existing` when
+ *     the baseline reports the same code and message (`splitUnplaced`).
+ *   - `edited` otherwise, including a finding on an untouched node that the
+ *     baseline does not have: an edit elsewhere caused it (a deleted variable
+ *     the node updates, a deleted step it reads).
+ *
+ * A pre-existing error becomes a warning, so it does not fail the check. A
+ * pre-existing `lowering` one also says it is probably an SDK defect, since the
+ * designer's node is one the SDK cannot write back: `compile` still refuses it,
+ * and `merge --baseline-from` keeps it as saved.
+ *
+ * When the edited flow's collection stopped at a scope-level refusal, the rest
+ * of the flow was never judged, so one more error, CHECK_INCOMPLETE (class
+ * `lowering`: `compile` stops at the refusal it names), says so:
+ * passing never means "not checked".
+ *
+ * For instance, an `EMPTY_ARM` on a branch the edit did not touch, which the
+ * baseline reports too, comes back as a `pre-existing` warning; the same
+ * finding after the edit changed that branch's condition is an `edited` error.
+ */
+export declare function scopeToEdit(edited: CheckedFlow, baseline: CheckedFlow): Diagnostic[];
 /**
  * The ISO-8601 repeating-interval pattern, copied VERBATIM from the
  * `core.trigger.scheduled@1.1` definition (`inputDefinition.then.properties.

package/dist/check.js

@@ -30,7 +30,18 @@ import { stepDeclaredVariables } from './flow-step-variables.js';
 import { plainHttpOnErrorMessage } from './nodes/http/flow/family.js';
 import { resolveVersion, resolveVersionCarried } from './core/nodes/versioned.js';
 import { loopParallelWarning, resolveLoopDefinition, loopVersion } from './loop-version.js';
+import { refusalClass } from './core/refusals.js';
+import { classifyDrafts, findingCounts, placeDiagnostics, splitUnplaced } from './edit-scope.js';
 export function check(built, opts = {}) {
+    return checkCompiled(built, opts).diagnostics;
+}
+/**
+ * `check`, keeping the flow its serializer pass compiled. Each finding is
+ * placed on its node (`nodeId`: a refusal on the node collect mode claimed for
+ * its step, any other finding on the node its step emitted) and given its
+ * code's `class`.
+ */
+export function checkCompiled(built, opts = {}) {
     // A connection two connectors use, and an agent resource's `nodeId` another
     // node of the file has, are the serializer's CONNECTION_CONNECTOR_CONFLICT /
     // INLINE_AGENT_RESOURCE_NODE_ID: it claims ids and resolves connections file-wide.
@@ -44,10 +55,109 @@ export function check(built, opts = {}) {
             ...(d.suggestion ? { suggestion: d.suggestion } : {}),
         });
     }
-    if (opts.serializer !== false)
-        diags.push(...serializerRefusals(built, { library: opts.library, bindings: opts.bindings }, diags));
-    return diags;
+    const serialized = opts.serializer !== false
+        ? serializerRefusals(built, { library: opts.library, bindings: opts.bindings }, diags)
+        : { diagnostics: [], flow: undefined };
+    diags.push(...serialized.diagnostics);
+    const placed = serialized.flow !== undefined ? placeDiagnostics(diags, serialized.flow) : undefined;
+    const diagnostics = diags.map((d, i) => {
+        const nodeId = d.nodeId ?? (placed?.[i].nodeId || undefined);
+        const cls = refusalClass(d.code);
+        return { ...d, ...(nodeId !== undefined ? { nodeId } : {}), ...(cls !== undefined ? { class: cls } : {}) };
+    });
+    return { diagnostics, flow: serialized.flow, ...(serialized.stoppedAt ? { stoppedAt: serialized.stoppedAt } : {}) };
+}
+/**
+ * Scope `edited`'s findings to the edit, against `baseline`: the original
+ * `.flow` decompiled and checked the same way (`flow check --baseline`,
+ * docs/CHECK_COMPILE_CONTRACT_DESIGN.md §3.3). Every finding gets an `origin`:
+ *
+ *   - `pre-existing` when its node is unchanged from the baseline (by id and
+ *     content, as merge judges it: `classifyDrafts`; a node inside a subflow
+ *     by its subflow) AND the baseline reports the same code on that node,
+ *     once per occurrence. A finding that names no node is `pre-existing` when
+ *     the baseline reports the same code and message (`splitUnplaced`).
+ *   - `edited` otherwise, including a finding on an untouched node that the
+ *     baseline does not have: an edit elsewhere caused it (a deleted variable
+ *     the node updates, a deleted step it reads).
+ *
+ * A pre-existing error becomes a warning, so it does not fail the check. A
+ * pre-existing `lowering` one also says it is probably an SDK defect, since the
+ * designer's node is one the SDK cannot write back: `compile` still refuses it,
+ * and `merge --baseline-from` keeps it as saved.
+ *
+ * When the edited flow's collection stopped at a scope-level refusal, the rest
+ * of the flow was never judged, so one more error, CHECK_INCOMPLETE (class
+ * `lowering`: `compile` stops at the refusal it names), says so:
+ * passing never means "not checked".
+ *
+ * For instance, an `EMPTY_ARM` on a branch the edit did not touch, which the
+ * baseline reports too, comes back as a `pre-existing` warning; the same
+ * finding after the edit changed that branch's condition is an `edited` error.
+ */
+export function scopeToEdit(edited, baseline) {
+    const locate = (c) => placeDiagnostics(c.diagnostics, c.flow)
+        .map((d, i) => ({ ...d, nodeId: c.diagnostics[i].nodeId ?? d.nodeId, index: i }));
+    const sorted = classifyDrafts(baseline.flow ?? {}, edited.flow ?? {}, baseline.flow, locate(edited));
+    // The baseline's findings on each node, by code; each one vouches for one edited finding.
+    const onNode = (f) => `${f.nodeId}\n${f.code}`;
+    const pool = new Map();
+    for (const b of locate(baseline)) {
+        if (b.nodeId === '')
+            continue;
+        pool.set(onNode(b), [...(pool.get(onNode(b)) ?? []), b.message]);
+    }
+    const preExisting = new Set();
+    // Exact messages are matched first: of two findings of one code on a node,
+    // the one the baseline has word for word is the pre-existing one. The second
+    // pass forgives wording the edit can shift without touching the finding (a
+    // "Known steps: ..." list), but only between messages that name the same
+    // quoted subjects: `UNKNOWN_REF "lookup" in "audit"` is a different finding
+    // from the baseline's `UNKNOWN_REF "ghost" in "audit"`, so it stays edited.
+    for (const exact of [true, false]) {
+        for (const f of sorted.kept) {
+            if (preExisting.has(f.index))
+                continue;
+            const messages = pool.get(onNode(f)) ?? [];
+            const j = exact ? messages.indexOf(f.message) : messages.findIndex((m) => quotedSubjects(m) === quotedSubjects(f.message));
+            if (j < 0)
+                continue;
+            messages.splice(j, 1);
+            preExisting.add(f.index);
+        }
+    }
+    for (const f of splitUnplaced(sorted.unplaced, findingCounts(baseline.diagnostics)).known)
+        preExisting.add(f.index);
+    const out = edited.diagnostics.map((d, i) => {
+        if (!preExisting.has(i))
+            return { ...d, origin: 'edited' };
+        const defect = d.level === 'error' && d.class === 'lowering';
+        return {
+            ...d,
+            level: 'warning',
+            message: defect ? `${d.message}\n  ${PRE_EXISTING_LOWERING_NOTE}` : d.message,
+            origin: 'pre-existing',
+        };
+    });
+    if (edited.stoppedAt) {
+        const at = edited.stoppedAt.code !== undefined ? `[${edited.stoppedAt.code}] ` : '';
+        out.push({
+            level: 'error', code: 'CHECK_INCOMPLETE',
+            message: `check stopped at ${at}${edited.stoppedAt.message} Nothing after that refusal was checked, so the edit is not judged. `
+                + 'Fix it, even if the original has it too, and run check again.',
+            class: refusalClass('CHECK_INCOMPLETE'), origin: 'edited',
+        });
+    }
+    return out;
+}
+/** The `"quoted"` names in a finding's message, in order: what it is about, apart from its wording. */
+function quotedSubjects(message) {
+    return JSON.stringify(message.match(/"[^"]*"/g) ?? []);
 }
+/** What a pre-existing lowering finding adds to its message ({@link scopeToEdit}). */
+const PRE_EXISTING_LOWERING_NOTE = 'This node is unchanged from the baseline, so this is probably an SDK defect: '
+    + 'the SDK cannot read what the designer wrote. `compile` refuses this node; `merge --baseline-from` keeps it as saved. '
+    + 'Report it: https://github.com/UiPath/builder-sdk/issues';
 /** The error-level diagnostics a custom node's own `diagnostics()` reported (see `serializerRefusals`). */
 const OWN_NODE_ERRORS = new WeakSet();
 /**
@@ -67,13 +177,20 @@ const OWN_NODE_ERRORS = new WeakSet();
  */
 function serializerRefusals(built, compile, found) {
     const collected = [];
+    let flow;
+    let stoppedAt;
     try {
-        serialize(built, { ...compile, collect: (r) => collected.push(r) });
+        flow = serialize(built, { ...compile, collect: (r) => collected.push(r) });
+        // Collection stopped: the refusal that stopped it is the last one reported.
+        const stop = collected[collected.length - 1];
+        if (flow === undefined && stop)
+            stoppedAt = { code: stop.code, message: stop.message };
     }
     catch (error) {
         // LIBRARY_REQUIRED is dropped below, so it does not count as something reported.
         if (!found.some((d) => d.level === 'error') && !collected.some((r) => r.code !== 'LIBRARY_REQUIRED'))
             throw error;
+        stoppedAt = { message: error instanceof Error ? error.message : String(error) };
     }
     const out = [];
     const seen = new Set();
@@ -100,9 +217,10 @@ function serializerRefusals(built, compile, found) {
             level: 'error', code: r.code, message,
             ...(step !== undefined ? { step } : {}),
             ...(r.suggestion !== undefined ? { suggestion: r.suggestion } : {}),
+            ...(r.nodeId !== undefined ? { nodeId: r.nodeId } : {}),
         });
     }
-    return out;
+    return { diagnostics: out, flow, ...(stoppedAt ? { stoppedAt } : {}) };
 }
 /**
  * `ancestors` is the chain of child flows currently being checked, innermost

package/dist/cli/commands/flow.js

@@ -23,14 +23,16 @@ export function registerFlowCommands(program) {
         .option('--library <dir>', 'connector library directory')
         .option('--bindings <file>', 'bindings.json path')
         .option('--connectors-local <dir>', 'connection-resolved connector overlay')
-        .option('--no-check', 'skip the source-level check')
+        .option('--no-check', 'deprecated, does nothing: compile no longer runs check')
         .action(async (source, options) => {
         const argv = [source];
         addValue(argv, '-o', options.output);
         addValue(argv, '--library', options.library);
         addValue(argv, '--bindings', options.bindings);
         addValue(argv, '--connectors-local', options.connectorsLocal);
-        if (options.check === false || emitOnlyEnabled())
+        // Passed on only when given, so compile prints its deprecation warning.
+        // Emit-only mode needs nothing here: compile does not run check.
+        if (options.check === false)
             argv.push('--no-check');
         await invoke('flow compile', () => import('../../compile-cli.js'), argv);
     });
@@ -40,7 +42,10 @@ export function registerFlowCommands(program) {
         .option('--source', 'check authored TypeScript')
         .addOption(retiredCompiledOption())
         .option('--library <dir>', 'connector library directory')
-        .option('--connectors-local <dir>', 'connection-resolved connector overlay');
+        .option('--connectors-local <dir>', 'connection-resolved connector overlay')
+        .option('--bindings <file>', 'bindings.json path')
+        .option('--baseline <file>', 'the original .flow the source was decompiled from (what merge --baseline-from takes, not the compiled baseline merge --baseline takes): findings on nodes the edit did not touch, which the original has too, become warnings')
+        .option('--package <name...>', 'trust and load this node-type package for --baseline (repeatable)');
     // Hidden, not removed: scripts that pass these keep parsing.
     for (const [flags, , description] of RETIRED_COMPILED_CHECK_FLAGS) {
         check.addOption(new Option(flags, description).hideHelp());
@@ -69,6 +74,10 @@ export function registerFlowCommands(program) {
             const argv = [input];
             addValue(argv, '--library', options.library);
             addValue(argv, '--connectors-local', options.connectorsLocal);
+            addValue(argv, '--bindings', options.bindings);
+            addValue(argv, '--baseline', options.baseline);
+            for (const name of options.package ?? [])
+                argv.push('--package', name);
             await invoke('flow check', () => import('../../check-cli.js'), argv);
             return;
         }

package/dist/cli-result.d.ts

@@ -24,30 +24,34 @@ export declare function reportResult(fields: Record<string, unknown>): void;
  * @param text - the result as text; a trailing newline is added.
  */
 export declare function printResult(text: string): void;
-/**
- * Report a check's diagnostics as `{ errors, warnings, diagnostics }`, the one
- * shape every family's check (and compile's check pass) uses.
- */
-export declare function reportDiagnostics(diags: ReadonlyArray<{
+/** A diagnostic as `reportDiagnostics` and `diagnosticLine` read it: any family's, with the fields it has. */
+interface ReportedDiagnostic {
     level: string;
     code: string;
     message: string;
     step?: string;
     suggestion?: string;
-}>): void;
+    nodeId?: string;
+    class?: string;
+    origin?: string;
+}
+/**
+ * Report a check's diagnostics as `{ errors, warnings, diagnostics }`, the one
+ * shape every family's check (and compile's check pass) uses. Each diagnostic
+ * keeps the optional fields it has: `step`, `suggestion`, and Flow's `nodeId`,
+ * `class` and (with `check --baseline`) `origin`.
+ */
+export declare function reportDiagnostics(diags: ReadonlyArray<ReportedDiagnostic>): void;
 /**
  * One diagnostic as `check` and `compile` print it: its mark and code, the
- * message, the step it is on (unless the message already names it), and the
- * suggestion. For instance
- * `✗ [STEP_SWITCH_EXIT_UNKNOWN] no exit named "maybe". … (step "route")`.
+ * message, the step it is on (unless the message already names it), the
+ * suggestion, and, with `check --baseline`, its origin. For instance
+ * `✗ [STEP_SWITCH_EXIT_UNKNOWN] no exit named "maybe". … (step "route")`, or
+ * `⚠ [EMPTY_ARM] … (pre-existing, not counted)`. With an origin, a message's
+ * later lines (the note on a pre-existing lowering finding) follow the line
+ * the origin ends.
  */
-export declare function diagnosticLine(d: {
-    level: string;
-    code: string;
-    message: string;
-    step?: string;
-    suggestion?: string;
-}): string;
+export declare function diagnosticLine(d: ReportedDiagnostic): string;
 /**
  * The error diagnostic for a throw that ends a compile: the error's own string
  * `code` when it carries one, else `COMPILE_FAILED`.
@@ -57,3 +61,4 @@ export declare function thrownDiagnostic(error: unknown): {
     code: string;
     message: string;
 };
+export {};

package/dist/cli-result.js

@@ -38,7 +38,9 @@ export function printResult(text) {
 }
 /**
  * Report a check's diagnostics as `{ errors, warnings, diagnostics }`, the one
- * shape every family's check (and compile's check pass) uses.
+ * shape every family's check (and compile's check pass) uses. Each diagnostic
+ * keeps the optional fields it has: `step`, `suggestion`, and Flow's `nodeId`,
+ * `class` and (with `check --baseline`) `origin`.
  */
 export function reportDiagnostics(diags) {
     reportResult({
@@ -48,21 +50,34 @@ export function reportDiagnostics(diags) {
             level: d.level, code: d.code, message: d.message,
             ...(d.step !== undefined ? { step: d.step } : {}),
             ...(d.suggestion ? { suggestion: d.suggestion } : {}),
+            ...(d.nodeId !== undefined ? { nodeId: d.nodeId } : {}),
+            ...(d.class !== undefined ? { class: d.class } : {}),
+            ...(d.origin !== undefined ? { origin: d.origin } : {}),
         })),
     });
 }
 /**
  * One diagnostic as `check` and `compile` print it: its mark and code, the
- * message, the step it is on (unless the message already names it), and the
- * suggestion. For instance
- * `✗ [STEP_SWITCH_EXIT_UNKNOWN] no exit named "maybe". … (step "route")`.
+ * message, the step it is on (unless the message already names it), the
+ * suggestion, and, with `check --baseline`, its origin. For instance
+ * `✗ [STEP_SWITCH_EXIT_UNKNOWN] no exit named "maybe". … (step "route")`, or
+ * `⚠ [EMPTY_ARM] … (pre-existing, not counted)`. With an origin, a message's
+ * later lines (the note on a pre-existing lowering finding) follow the line
+ * the origin ends.
  */
 export function diagnosticLine(d) {
     // A step inside a subflow is `<caller> › <step>`; the message names the innermost one.
     const named = d.step !== undefined && d.message.includes(`"${d.step.split(' › ').pop()}"`);
-    return `${d.level === 'error' ? '✗' : '⚠'} [${d.code}] ${d.message}`
-        + (d.step !== undefined && !named ? ` (step "${d.step}")` : '')
+    const suffix = (d.step !== undefined && !named ? ` (step "${d.step}")` : '')
         + (d.suggestion ? ` (did you mean "${d.suggestion}"?)` : '');
+    const mark = `${d.level === 'error' ? '✗' : '⚠'} [${d.code}]`;
+    if (d.origin === undefined)
+        return `${mark} ${d.message}${suffix}`;
+    // With a baseline the origin ends the finding's first line, where it is seen.
+    const origin = d.origin === 'edited' ? ' (edited)'
+        : d.class === 'lowering' ? ' (pre-existing)' : ' (pre-existing, not counted)';
+    const [first, ...rest] = d.message.split('\n');
+    return [`${mark} ${first}${suffix}${origin}`, ...rest].join('\n');
 }
 /**
  * The error diagnostic for a throw that ends a compile: the error's own string

package/dist/compile-cli.js

@@ -10,12 +10,17 @@
  * --library defaults to $FLOW_SDK_LIBRARY_JSON; --bindings defaults to
  * .flow-sdk/bindings.json (or a legacy ./bindings.json) when present. Connector actions require a library.
  *
- * `--no-check` skips the SDK's static `check()` pass and emits whatever
- * `.build()` produced. It exists for loops whose verification is somewhere else
- * entirely — e.g. authoring against the product CLI (`uip maestro flow
- * validate` / `debug`), where a pre-emit static pass would answer questions the
- * product's own gates are supposed to answer. `.build()` still throws on
- * structural problems; only the diagnostic pass is skipped.
+ * `compile` only serializes (docs/CHECK_COMPILE_CONTRACT_DESIGN.md D1, D2). It
+ * does not run `check()`'s lint rules: run `flow check` first for those. It
+ * stops only when it cannot write a correct `.flow`, a refusal the serializer
+ * throws. A draft node (a connector with no connection, an empty required
+ * input) the canvas saved is written, with a warning: decompile marks its step
+ * `{ draft: true }` and carries its definition in `.definitions([...])`. Any
+ * other draft, such as one an agent just wrote (even of an operation the canvas
+ * has a draft of), is refused.
+ *
+ * `--no-check` is a deprecated no-op: it is accepted for one minor version, with
+ * a warning, and then removed.
  */
 import { diagnosticLine, reportDiagnostics, reportResult, thrownDiagnostic } from './cli-result.js';
 import { writeJsonFile } from './core/json-file.js';
@@ -24,8 +29,7 @@ import { basename, dirname, join, relative, resolve } from 'node:path';
 import { resolveFlowFile, loadBuiltFlow } from './load.js';
 import { serializeWithSidecars } from './serialize.js';
 import { compileOwnsResource } from './core/agent-tool-resources.js';
-import { check } from './check.js';
-import { flowCheckOpts, openCliLibrary } from './cli-library.js';
+import { openCliLibrary } from './cli-library.js';
 import { Bindings } from './bindings.js';
 import { flagValue, runWhenInvokedDirectly } from './cli-run.js';
 import { connectionResources, inlineAgentResources, mergeBindingsV2, refreshInlineAgentRows } from './bindings-v2.js';
@@ -35,8 +39,8 @@ import { defaultBindingsFile } from './workdir.js';
 import { isWithin } from './path-within.js';
 import { flowSources, resourceSourcesOfOtherFlows } from './project-resource-users.js';
 import { fnv1aX4Uuid } from './core/stable-id.js';
-import { BindingRefusal } from './core/binding-messages.js';
-import { ByoaRefusal } from './core/byoa.js';
+import { CompileRefusal } from './core/compile-refusal.js';
+import { cliSpelling } from './core/cli-spelling.js';
 /** An agent folder name: a uuid, any case. */
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export async function run(argv) {
@@ -45,7 +49,9 @@ export async function run(argv) {
         return 2;
     }
     const flags = new Set(['-o', '--library', '--bindings', '--connectors-local']);
-    const noCheck = argv.includes('--no-check');
+    if (argv.includes('--no-check')) {
+        console.error(`compile: --no-check is deprecated and does nothing: compile no longer runs check. Run \`${cliSpelling()} flow check\` before \`compile\`; the flag will be removed.`);
+    }
     const pos = argv.find((a, i) => !flags.has(a) && !flags.has(argv[i - 1]));
     if (!pos) {
         console.error('compile: missing <flow.ts | BaseName>');
@@ -66,37 +72,20 @@ export async function run(argv) {
     // (e.g. HTTP-only) then compile fine even if the connector cache isn't built.
     // A connector action with no library resolves to a clear error in serialize().
     //
-    // Loaded BEFORE check() on purpose: one of check's rules (whether a connector
-    // event operation declares any event parameters) can only be answered from the
-    // library, and answering it from an assumption instead is what made
-    // EVENT_NO_SCOPE an error for HTTP Webhook, whose only correct `where` is empty.
     const library = openCliLibrary(argv);
     const bindFile = flagValue(argv, '--bindings') ?? defaultBindingsFile();
     const bindings = new Bindings(bindFile);
     // One list per run; every exit path reports it (reportResult overwrites keys).
     const diagnostics = [];
-    if (!noCheck) {
-        // Same options as `flow check`, so the two cannot disagree.
-        const diags = check(built, flowCheckOpts(library, bindings));
-        const errors = diags.filter((d) => d.level === 'error');
-        for (const d of diags)
-            console.error(`  ${diagnosticLine(d)}`);
-        diagnostics.push(...diags);
-        if (errors.length) {
-            reportDiagnostics(diagnostics);
-            console.error(`compile: ${errors.length} error(s); not emitting.`);
-            return 1;
-        }
-    }
     // The serializer's own observations — a connection or folder value that can
-    // never be a tenant resource key — printed in the same `⚠ [CODE]` shape as
-    // check()'s. Warnings are never fatal: the .flow is still written, exit stays 0.
-    // A binding LABEL the serializer refuses (its own name as the resourceKey, or a
-    // label a populated bindings.json does not declare) is an error, not a
-    // warning, and so is a BYOA-only event on a connection `prepare` never checked
-    // (EVENT_BYOA_UNVERIFIED): the check pass above reports each first, and this is
-    // the same refusal in the same `✗ [CODE]` shape when that pass was skipped
-    // (`--no-check`, or an emit-only project). Nothing is written.
+    // never be a tenant resource key, a draft node written from its carried
+    // definition — printed in the same `⚠ [CODE]` shape as check()'s. Warnings are
+    // never fatal: the .flow is still written, exit stays 0. A binding LABEL the
+    // serializer refuses (its own name as the resourceKey, or a label a populated
+    // bindings.json does not declare) is an error, not a warning, and so is a
+    // BYOA-only event on a connection `prepare` never checked
+    // (EVENT_BYOA_UNVERIFIED): printed in the same `✗ [CODE]` shape `check` uses
+    // for it. Nothing is written.
     const out = flagValue(argv, '-o') ?? `${built.name || basename(file).replace(/\.flow\.ts$|\.ts$/, '')}.flow`;
     const outDir = dirname(resolve(out));
     // ONE FOLDER, ONE FLOW (#1184). An agent's `source` is the name of the folder
@@ -147,28 +136,37 @@ export async function run(argv) {
     const warnings = [];
     let emitted;
     try {
-        emitted = serializeWithSidecars(built, { library, bindings, warn: (w) => warnings.push(w), agentSource });
+        emitted = serializeWithSidecars(built, {
+            library, bindings, warn: (w) => warnings.push(w), agentSource,
+            carriedDrafts: (d) => warnings.push(draftWarning(d)),
+        });
     }
     catch (error) {
         for (const w of warnings)
-            console.error(`  ⚠ [${w.code}] ${w.message}`);
+            console.error(`  ${diagnosticLine(serializeWarningDiagnostic(w))}`);
         diagnostics.push(...warnings.map(serializeWarningDiagnostic));
-        if (!(error instanceof BindingRefusal || error instanceof ByoaRefusal)) {
-            // Any other throw still ends the run through the caller (exit 1, `--json`
-            // `error`); the list is reported first.
+        if (!(error instanceof CompileRefusal)) {
+            // Any other throw (an internal SDK error) still ends the run through the
+            // caller (exit 1, `--json` `error`); the list is reported first.
             diagnostics.push(thrownDiagnostic(error));
             reportDiagnostics(diagnostics);
             throw error;
         }
-        console.error(`  ✗ [${error.code}] ${error.message}`);
-        diagnostics.push({ level: 'error', code: error.code, message: error.message });
+        // A coded refusal: the serializer cannot write a correct `.flow`. Printed in
+        // `check`'s `✗ [CODE]` shape, which `check` reports for it too.
+        const refused = {
+            level: 'error', code: error.code, message: error.message,
+            ...(error.suggestion !== undefined ? { suggestion: error.suggestion } : {}),
+        };
+        console.error(`  ${diagnosticLine(refused)}`);
+        diagnostics.push(refused);
         reportDiagnostics(diagnostics);
         console.error('compile: 1 error(s); not emitting.');
         return 1;
     }
     const { flow: flowJson, sidecars } = emitted;
     for (const w of warnings)
-        console.error(`  ⚠ [${w.code}] ${w.message}`);
+        console.error(`  ${diagnosticLine(serializeWarningDiagnostic(w))}`);
     diagnostics.push(...warnings.map(serializeWarningDiagnostic));
     // An inline agent is TWO artifacts: the node, and the agent's own configuration
     // at `<source>/agent.json` — which is where flow-v1's serializer points the
@@ -325,7 +323,19 @@ export async function run(argv) {
     return 0;
 }
 function serializeWarningDiagnostic(w) {
-    return { level: 'warning', code: w.code, message: w.message };
+    return { level: 'warning', code: w.code, message: w.message, ...(w.step !== undefined ? { step: w.step } : {}) };
+}
+/**
+ * A draft node written from its carried definition, as a warning: the node is
+ * in the `.flow` as the canvas saved it, unfinished. For instance
+ * `⚠ [BINDING_MISSING] … written as a draft from its carried definition`.
+ */
+function draftWarning(d) {
+    return {
+        code: String(d.code),
+        message: `${d.message} Written as a draft, with the definition the source carries; finish the node before the flow runs.`,
+        ...(d.step !== undefined ? { step: d.step } : {}),
+    };
 }
 runWhenInvokedDirectly(import.meta.url, 'compile', run);
 /** A JSON file's contents, or `undefined` when it is missing or unreadable. */

package/dist/core/refusals.d.ts

@@ -55,6 +55,7 @@ export declare const REFUSALS: {
     readonly CARRIED_DEFINITION_CONFLICT: "lowering";
     readonly CARRIED_DEFINITION_INVALID: "lowering";
     readonly CEQL_UNPARSEABLE: "lowering";
+    readonly CHECK_INCOMPLETE: "lowering";
     readonly COMPILE_FAILED: "lowering";
     readonly CONNECTION_CONNECTOR_CONFLICT: "draft";
     readonly CONNECTION_STUB: "lint";

package/dist/core/refusals.js

@@ -93,6 +93,9 @@ export const REFUSALS = {
     CARRIED_DEFINITION_CONFLICT: 'lowering',
     CARRIED_DEFINITION_INVALID: 'lowering',
     CEQL_UNPARSEABLE: 'lowering',
+    // Only `check --baseline` reports it: collection stopped at a scope-level
+    // refusal, and `compile` (and `merge --baseline-from`) stops at that refusal.
+    CHECK_INCOMPLETE: 'lowering',
     // A throw that is no refusal, which `compile` cannot get past: check reports it on its step.
     COMPILE_FAILED: 'lowering',
     CONNECTION_CONNECTOR_CONFLICT: 'draft',

package/dist/decompile-cli.js

@@ -159,7 +159,7 @@ if (!existsSync(BASELINE)) {
   // ── Step 1: capture the baseline = compile of the PRISTINE decompiled code,
   //    BEFORE any edit. Run this once right after decompiling, then edit. ──
   mkdirSync(dirname(BASELINE), { recursive: true });
-  run('compile', [TS, '-o', BASELINE, '--no-check']);
+  run('compile', [TS, '-o', BASELINE]);
   console.log('\\n>>> Baseline captured. Now EDIT ' + ${JSON.stringify(basename(tsPath))} + ', then re-run this script to compile + merge.');
 } else {
   // ── Step 2: compile your edits, then merge them back into the original. ──
@@ -182,7 +182,7 @@ if (!existsSync(BASELINE)) {
     process.exit(2);
   }
   mkdirSync(dirname(EDITED), { recursive: true });
-  run('compile', [TS, '-o', EDITED, '--no-check']);
+  run('compile', [TS, '-o', EDITED]);
 
   // ── DIFF GATE (seam) ──────────────────────────────────────────────────────
   // A future step can diff ORIGINAL vs the about-to-be-written MERGED here and