deepline 0.2.56 → 0.2.57

package/dist/bundling-sources/sdk/src/release.ts

@@ -160,7 +160,7 @@ export const SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: '0.2.56',
+  version: '0.2.57',
   contracts: {
     api: {
       name: 'sdk-http-api',

package/dist/bundling-sources/shared_libs/plays/docflow.ts

@@ -38,6 +38,19 @@ export type PlayDocflowNode = {
   id: string;
   label: string;
   kind: PlayDocflowNodeKind;
+  /**
+   * No statement in this play runs this box — the author said so with
+   * `class <id> sketch`. See {@link SKETCH_CLASS}.
+   *
+   * Deliberately NOT a `kind`. What a box IS (an action, a decision, a dataset)
+   * and whether code binds it are two different questions, and folding the
+   * second into the first was wrong in a way the tests caught immediately: a
+   * sketched diamond stopped being a decision, so it lost its shape on the
+   * canvas and the branch-label lint stopped checking its arms. Absent rather
+   * than `false` when bound, so the JSON a bound diagram hashes to is byte for
+   * byte what it was before sketches existed.
+   */
+  sketch?: true;
 };
 
 /**
@@ -225,6 +238,23 @@ const ATTRIBUTE = /([A-Za-z][\w-]*)\s*:\s*"([^"\n]*)"/y;
 const MERMAID_NODE_ATTRIBUTES = ['label', 'type', 'in', 'out', 'arm'] as const;
 const LEGACY_DOCFLOW_ATTRIBUTES = ['id', ...MERMAID_NODE_ATTRIBUTES] as const;
 const MERMAID_NODE_ID = /^[A-Za-z][\w-]*/;
+/**
+ * `class a,b,c sketch` — the author declaring that no statement runs these boxes.
+ *
+ * Every other box in a diagram must point at a statement in this play's source,
+ * because that is what makes the diagram a claim about the code rather than a
+ * picture of it. Some boxes honestly cannot: a cascade whose legs live in a
+ * sibling module, a loop over a provider list, the outcome boxes hanging off a
+ * decision. Those boxes still belong on the canvas — they name the real route —
+ * and this is how the author says so out loud, so the reader is told "sketch"
+ * instead of being shown a box that looks misconfigured.
+ *
+ * It is mermaid's own `class` statement rather than a Deepline directive, so the
+ * block stays a diagram any mermaid renderer can draw. Class names other than
+ * `sketch` remain styling this dashboard does not apply, exactly as before.
+ */
+const SKETCH_CLASS =
+  /^\s*class\s+([A-Za-z][\w-]*(?:\s*,\s*[A-Za-z][\w-]*)*)\s+sketch\s*;?\s*$/;
 /**
  * Mermaid's node shapes, longest opener FIRST.
  *
@@ -601,7 +631,14 @@ function levenshtein(left: string, right: string): number {
 
 const MERMAID_BLOCK = /\/\*\*\s*@mermaid(?:\s|\r?\n)([\s\S]*?)\*\//g;
 const LEGACY_BLOCK = /\/\*\*\s*@docflow(?:\s|\r?\n)([\s\S]*?)\*\//;
-const BLOCK_EXPORT_HEADER = /^[A-Za-z_$][\w$]*$/;
+/**
+ * What a block header may name: an export name, or the play's own kebab-case
+ * name. Hyphens are in the set for the second — `@mermaid name-to-linkedin-url-
+ * waterfall` is the header worth writing, and while it was identifier-only the
+ * whole line silently became the diagram's first line, which surfaced as
+ * "Docflow must start with `flowchart`" and named nothing.
+ */
+const BLOCK_EXPORT_HEADER = /^[A-Za-z_$][\w$-]*$/;
 
 /** Strips the JSDoc `*` gutter and trims, leaving the authored block text. */
 function cleanBlockBody(raw: string): string {
@@ -613,7 +650,8 @@ function cleanBlockBody(raw: string): string {
 }
 
 /**
- * Splits `/** @mermaid batch` into the export it names and the diagram itself.
+ * Splits `/** @mermaid contact-to-phone-waterfall` into the play it names and
+ * the diagram itself.
  *
  * The name is the first token after the tag, the same place `// @mermaid-node
  * <id>` puts its target, so one rule covers both halves of the grammar. It is
@@ -649,6 +687,8 @@ type ParsedDocflowBlockGraph = {
   edges: PlayDocflowEdge[];
   subgraphs: Map<string, PlayDocflowSubgraph>;
   ignoredDirectives: string[];
+  /** Ids a `class … sketch` line declared to run no statement. */
+  sketchIds: Set<string>;
 };
 
 type ParsedDocflowBlock = ParsedDocflowBlockGraph & {
@@ -701,6 +741,9 @@ function parseDocflowBlockGraph(
   // an edge on an earlier line may reference a subgraph declared later.
   const subgraphs = new Map<string, PlayDocflowSubgraph>();
   const ignoredDirectives: string[] = [];
+  // Boxes the author declared to be a sketch, via mermaid's own
+  // `class a,b sketch`. See {@link SKETCH_CLASS}.
+  const sketchIds = new Set<string>();
   const subgraphStack: PlayDocflowSubgraph[] = [];
   const subgraphIds = new Set<string>();
   if (syntax === 'mermaid') {
@@ -796,7 +839,15 @@ function parseDocflowBlockGraph(
     const isDirective =
       /^\s*(?:direction|classDef|class|style|linkStyle|click)\b/i.test(line);
     if (syntax === 'mermaid' && isDirective) {
-      ignoredDirectives.push(line.trim());
+      const sketch = SKETCH_CLASS.exec(line);
+      if (sketch) {
+        for (const id of sketch[1]!.split(',')) {
+          const trimmed = id.trim();
+          if (trimmed) sketchIds.add(trimmed);
+        }
+      } else {
+        ignoredDirectives.push(line.trim());
+      }
     }
     if (syntax === 'mermaid' && !isDirective) {
       declaredOnThisLine = addNodes(line, line);
@@ -859,7 +910,20 @@ function parseDocflowBlockGraph(
     );
   }
 
-  return { direction, nodes, edges, subgraphs, ignoredDirectives };
+  for (const id of sketchIds) {
+    const node = nodes.get(id);
+    if (!node) {
+      errors.push(
+        subgraphs.has(id)
+          ? `Docflow \`class ${id} sketch\` names a subgraph. A subgraph is a region, not a box, and never binds code — drop it from the class line.`
+          : `Docflow \`class ${id} sketch\` names "${id}", which this diagram does not draw.`,
+      );
+      continue;
+    }
+    node.sketch = true;
+  }
+
+  return { direction, nodes, edges, subgraphs, ignoredDirectives, sketchIds };
 }
 
 function materializeDocflow(block: ParsedDocflowBlock): PlayDocflow {
@@ -889,7 +953,11 @@ export function parsePlayDocflowFile(
   sourceCode: string,
 ): PlayDocflowFileParseResult {
   const errors: string[] = [];
-  const bindings = parseDocflowBindings(sourceCode, errors);
+  // Ids whose annotation was written but refused. They are NOT unbound boxes:
+  // the author already has one actionable error about them, and telling them to
+  // "bind it" on the next line is telling them to do what they just did.
+  const rejectedNodeIds = new Set<string>();
+  const bindings = parseDocflowBindings(sourceCode, errors, rejectedNodeIds);
 
   const rawBlocks: Array<{
     syntax: NonNullable<PlayDocflow['syntax']>;
@@ -923,7 +991,13 @@ export function parsePlayDocflowFile(
   }
 
   resolveBlockExports(sourceCode, parsedBlocks, errors);
-  attachBindingsToBlocks(sourceCode, parsedBlocks, bindings, errors);
+  attachBindingsToBlocks(
+    sourceCode,
+    parsedBlocks,
+    bindings,
+    errors,
+    rejectedNodeIds,
+  );
 
   return {
     blocks: parsedBlocks
@@ -1163,7 +1237,7 @@ function projectRecordedArms(
     // One decision, one meaning per token. Two arms both claiming `run` is the
     // exact defect the recorded identity exists to make impossible, so it is
     // refused at the source rather than resolved by precedence downstream.
-    const key = `${edge.from}${binding.arm}`;
+    const key = `${edge.from}\u0000${binding.arm}`;
     const already = declaredBy.get(key);
     if (already !== undefined) {
       errors.push(
@@ -1181,6 +1255,7 @@ function attachBindingsToBlocks(
   blocks: ParsedDocflowBlock[],
   bindings: readonly PlayDocflowBinding[],
   errors: string[],
+  rejectedNodeIds: ReadonlySet<string>,
 ): void {
   const lineStarts = sourceLineStartsForDocflow(sourceCode);
   const exportRanges = playExportSourceRanges(sourceCode);
@@ -1227,17 +1302,33 @@ function attachBindingsToBlocks(
     for (const binding of block.bindings) {
       const node = block.nodes.get(binding.nodeId)!;
       if (binding.label) node.label = binding.label;
+      // A box cannot be both a sketch and a bound statement. Silently letting
+      // one win renders a real, traceable step as scenery — or the reverse — and
+      // the author who wrote both has no way to see which they got.
+      if (block.sketchIds.has(binding.nodeId)) {
+        errors.push(
+          `Docflow box "${binding.nodeId}" is declared \`class ${binding.nodeId} sketch\` and also bound by \`// @mermaid-node ${binding.nodeId}\` on line ${binding.line}. It is one or the other: drop it from the class line, or drop the annotation.`,
+        );
+        continue;
+      }
       if (binding.kind) node.kind = binding.kind;
     }
     projectRecordedArms(block, errors);
-    if (block.syntax !== 'docflow') continue;
     const bound = new Set(block.bindings.map((binding) => binding.nodeId));
     for (const node of block.nodes.values()) {
-      if (node.kind !== 'conceptual' && !bound.has(node.id)) {
-        errors.push(
-          `Docflow node "${node.id}" has no code binding; mark it type:"conceptual" or bind it.`,
-        );
-      }
+      if (
+        node.sketch ||
+        node.kind === 'conceptual' ||
+        bound.has(node.id) ||
+        rejectedNodeIds.has(node.id)
+      )
+        continue;
+      errors.push(
+        block.syntax === 'docflow'
+          ? `Docflow node "${node.id}" has no code binding; mark it type:"conceptual" or bind it.`
+          : `Docflow box "${node.id}" in \`${blockLabel(block)}\` points at nothing, so the canvas can only draw it and say nothing about it. ` +
+              `Either put \`// @mermaid-node ${node.id}\` above the statement it runs, or — if this play has no such statement, because the work happens in another module or inside a loop — add it to a \`class ${node.id} sketch\` line in the block to declare it a sketch.`,
+      );
     }
   }
 }
@@ -1292,6 +1383,7 @@ export function parsePlayDocflow(
 function parseDocflowBindings(
   sourceCode: string,
   errors: string[],
+  rejectedNodeIds: Set<string>,
 ): PlayDocflowBinding[] {
   const lines = sourceCode.split(/\r?\n/);
   const bindings: PlayDocflowBinding[] = [];
@@ -1302,6 +1394,11 @@ function parseDocflowBindings(
     const legacyMatch = PUT.exec(lines[index]!);
     const mermaidMatch = MERMAID_NODE.exec(lines[index]!);
     if (!legacyMatch && !mermaidMatch) continue;
+    // Whatever this annotation names, the author has now written it down. Every
+    // `continue` below is a rejection, and a rejected id must not come back as
+    // an unbound box — see `rejectedNodeIds` in `parsePlayDocflowFile`.
+    const annotatedId = mermaidMatch?.[1]?.trim();
+    if (annotatedId) rejectedNodeIds.add(annotatedId);
     const attributes = parseAttributes(
       mermaidMatch ? (mermaidMatch[2] ?? '') : legacyMatch![1]!,
       {
@@ -1311,11 +1408,12 @@ function parseDocflowBindings(
       },
     );
     if (!attributes) continue;
-    const id = (mermaidMatch ? mermaidMatch[1] : attributes.id)?.trim();
+    const id = (annotatedId ?? attributes.id)?.trim();
     if (!id) {
       errors.push(`Docflow annotation on line ${index + 1} requires id:"…".`);
       continue;
     }
+    rejectedNodeIds.add(id);
     const kind = nodeKind(attributes.type);
     if (attributes.type && !kind) {
       errors.push(
@@ -1370,6 +1468,7 @@ function parseDocflowBindings(
             ioConfidence: 'explicit' as const,
           }
         : inferBindingIo(lines[nextLine]!);
+    rejectedNodeIds.delete(id);
     bindings.push({
       nodeId: id,
       line: nextLine + 1,

package/dist/bundling-sources/shared_libs/plays/play-exports.ts

@@ -34,6 +34,16 @@ export type PlayFileExport = {
   name: string;
   /** Other export names that resolve to the same `definePlay` call. */
   aliases: string[];
+  /**
+   * The play's own name — `definePlay('<this>', …)` — when it is a literal.
+   *
+   * An export name is a module detail (`scalar`, `batch`); the play name is what
+   * the product, the registry and the customer call this thing. So it is a legal
+   * way to address the play, which is why an `@mermaid <name>` header may write
+   * either. Null when the first argument is not a string literal, which is only
+   * possible for a play the registry could not name either.
+   */
+  playName: string | null;
 };
 
 function getIdentifierName(node: unknown): string | null {
@@ -83,6 +93,16 @@ export function isDefinePlayCall(node: AstNode | null): boolean {
   return false;
 }
 
+/** The literal name a `definePlay('…', …)` call declares, when it is one. */
+function definePlayName(node: AstNode | null): string | null {
+  const expression = unwrapStaticExpression(node);
+  if (!expression || expression.type !== 'CallExpression') return null;
+  const first = astArray(expression.arguments)[0] ?? null;
+  return first?.type === 'Literal' && typeof first.value === 'string'
+    ? first.value
+    : null;
+}
+
 /**
  * The plays `sourceCode` exports, default first, then named exports in source
  * order. `null` means acorn could not parse the file — the caller abstains and
@@ -163,13 +183,26 @@ export function listPlayFileExports(
           .map(([exported]) => exported)
       : [];
     if (defaultLocalName) aliasedLocals.add(defaultLocalName);
-    exports.push({ name: PLAY_DEFAULT_EXPORT, aliases });
+    exports.push({
+      name: PLAY_DEFAULT_EXPORT,
+      aliases,
+      playName: definePlayName(
+        defaultLocalName
+          ? (declarations.get(defaultLocalName) ?? null)
+          : defaultExpression,
+      ),
+    });
   }
   for (const [exportedName, localName] of namedExports) {
     if (exportedName === PLAY_DEFAULT_EXPORT) continue;
     if (aliasedLocals.has(localName)) continue;
-    if (!isDefinePlayCall(declarations.get(localName) ?? null)) continue;
-    exports.push({ name: exportedName, aliases: [] });
+    const declaration = declarations.get(localName) ?? null;
+    if (!isDefinePlayCall(declaration)) continue;
+    exports.push({
+      name: exportedName,
+      aliases: [],
+      playName: definePlayName(declaration),
+    });
   }
 
   return exports;
@@ -180,6 +213,12 @@ export function listPlayFileExports(
  * canonical name. `scalar` in `export default scalar` resolves to `default`;
  * an unknown name resolves to `null` so the caller can fail loudly with the
  * available set rather than silently binding nothing.
+ *
+ * The play's own name resolves too, and is the better thing to write: a diagram
+ * headed `@mermaid scalar` names a module-local binding, while one headed
+ * `@mermaid name-and-domain-to-email-waterfall` names the play the reader came
+ * here for. Export names keep working because every diagram authored before this
+ * used one.
  */
 export function canonicalPlayExportName(
   exportName: string | null | undefined,
@@ -191,6 +230,12 @@ export function canonicalPlayExportName(
       return entry.name;
     }
   }
+  // Second pass, so an export literally named after another play's play name
+  // can never lose to it. Ambiguity between two plays' names is impossible:
+  // the registry rejects a duplicate play name before this ever runs.
+  for (const entry of exports) {
+    if (entry.playName === requested) return entry.name;
+  }
   return null;
 }
 
@@ -198,5 +243,9 @@ export function canonicalPlayExportName(
 export function playExportNamesForMessage(
   exports: readonly PlayFileExport[],
 ): string[] {
-  return exports.flatMap((entry) => [entry.name, ...entry.aliases]);
+  return exports.flatMap((entry) => [
+    ...(entry.playName ? [entry.playName] : []),
+    entry.name,
+    ...entry.aliases,
+  ]);
 }

package/dist/cli/index.js

@@ -1044,7 +1044,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.56",
+  version: "0.2.57",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -16645,6 +16645,12 @@ function isDefinePlayCall(node) {
   }
   return false;
 }
+function definePlayName(node) {
+  const expression = unwrapStaticExpression(node);
+  if (!expression || expression.type !== "CallExpression") return null;
+  const first = astArray(expression.arguments)[0] ?? null;
+  return first?.type === "Literal" && typeof first.value === "string" ? first.value : null;
+}
 function listPlayFileExports(sourceCode) {
   const ast = parsePlaySourceForAnalysis(sourceCode);
   if (!ast) return null;
@@ -16694,13 +16700,24 @@ function listPlayFileExports(sourceCode) {
   if (defaultIsPlay) {
     const aliases = defaultLocalName ? [...namedExports.entries()].filter(([, local]) => local === defaultLocalName).map(([exported]) => exported) : [];
     if (defaultLocalName) aliasedLocals.add(defaultLocalName);
-    exports2.push({ name: PLAY_DEFAULT_EXPORT, aliases });
+    exports2.push({
+      name: PLAY_DEFAULT_EXPORT,
+      aliases,
+      playName: definePlayName(
+        defaultLocalName ? declarations.get(defaultLocalName) ?? null : defaultExpression
+      )
+    });
   }
   for (const [exportedName, localName] of namedExports) {
     if (exportedName === PLAY_DEFAULT_EXPORT) continue;
     if (aliasedLocals.has(localName)) continue;
-    if (!isDefinePlayCall(declarations.get(localName) ?? null)) continue;
-    exports2.push({ name: exportedName, aliases: [] });
+    const declaration = declarations.get(localName) ?? null;
+    if (!isDefinePlayCall(declaration)) continue;
+    exports2.push({
+      name: exportedName,
+      aliases: [],
+      playName: definePlayName(declaration)
+    });
   }
   return exports2;
 }

package/dist/cli/index.mjs

@@ -1030,7 +1030,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.56",
+  version: "0.2.57",
   contracts: {
     api: {
       name: "sdk-http-api",
@@ -16690,6 +16690,12 @@ function isDefinePlayCall(node) {
   }
   return false;
 }
+function definePlayName(node) {
+  const expression = unwrapStaticExpression(node);
+  if (!expression || expression.type !== "CallExpression") return null;
+  const first = astArray(expression.arguments)[0] ?? null;
+  return first?.type === "Literal" && typeof first.value === "string" ? first.value : null;
+}
 function listPlayFileExports(sourceCode) {
   const ast = parsePlaySourceForAnalysis(sourceCode);
   if (!ast) return null;
@@ -16739,13 +16745,24 @@ function listPlayFileExports(sourceCode) {
   if (defaultIsPlay) {
     const aliases = defaultLocalName ? [...namedExports.entries()].filter(([, local]) => local === defaultLocalName).map(([exported]) => exported) : [];
     if (defaultLocalName) aliasedLocals.add(defaultLocalName);
-    exports.push({ name: PLAY_DEFAULT_EXPORT, aliases });
+    exports.push({
+      name: PLAY_DEFAULT_EXPORT,
+      aliases,
+      playName: definePlayName(
+        defaultLocalName ? declarations.get(defaultLocalName) ?? null : defaultExpression
+      )
+    });
   }
   for (const [exportedName, localName] of namedExports) {
     if (exportedName === PLAY_DEFAULT_EXPORT) continue;
     if (aliasedLocals.has(localName)) continue;
-    if (!isDefinePlayCall(declarations.get(localName) ?? null)) continue;
-    exports.push({ name: exportedName, aliases: [] });
+    const declaration = declarations.get(localName) ?? null;
+    if (!isDefinePlayCall(declaration)) continue;
+    exports.push({
+      name: exportedName,
+      aliases: [],
+      playName: definePlayName(declaration)
+    });
   }
   return exports;
 }

package/dist/{compiler-manifest-Bl8kmLx9.d.mts → compiler-manifest-TgaC4DeD.d.mts}

@@ -21,6 +21,19 @@ type PlayDocflowNode = {
     id: string;
     label: string;
     kind: PlayDocflowNodeKind;
+    /**
+     * No statement in this play runs this box — the author said so with
+     * `class <id> sketch`. See {@link SKETCH_CLASS}.
+     *
+     * Deliberately NOT a `kind`. What a box IS (an action, a decision, a dataset)
+     * and whether code binds it are two different questions, and folding the
+     * second into the first was wrong in a way the tests caught immediately: a
+     * sketched diamond stopped being a decision, so it lost its shape on the
+     * canvas and the branch-label lint stopped checking its arms. Absent rather
+     * than `false` when bound, so the JSON a bound diagram hashes to is byte for
+     * byte what it was before sketches existed.
+     */
+    sketch?: true;
 };
 /**
  * Which arm of a conditional a drawn decision edge IS.

package/dist/{compiler-manifest-Bl8kmLx9.d.ts → compiler-manifest-TgaC4DeD.d.ts}

@@ -21,6 +21,19 @@ type PlayDocflowNode = {
     id: string;
     label: string;
     kind: PlayDocflowNodeKind;
+    /**
+     * No statement in this play runs this box — the author said so with
+     * `class <id> sketch`. See {@link SKETCH_CLASS}.
+     *
+     * Deliberately NOT a `kind`. What a box IS (an action, a decision, a dataset)
+     * and whether code binds it are two different questions, and folding the
+     * second into the first was wrong in a way the tests caught immediately: a
+     * sketched diamond stopped being a decision, so it lost its shape on the
+     * canvas and the branch-label lint stopped checking its arms. Absent rather
+     * than `false` when bound, so the JSON a bound diagram hashes to is byte for
+     * byte what it was before sketches existed.
+     */
+    sketch?: true;
 };
 /**
  * Which arm of a conditional a drawn decision edge IS.

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { e as PlayRuntimeBackendId, c as PlayCompilerManifest, D as DeeplineError, f as ToolExecutionError, g as ToolExecutionErrorOptions, h as PlayAuthoringColumnMap, i as PlayAuthoringColumnResolver, j as PlayAuthoringRuntimeContext, k as PlayAuthoringConditionalStepResolver, l as PlayAuthoringCsvInput, m as PlayAuthoringCsvOptions, n as PlayAuthoringDatasetBuilder, o as PlayAuthoringDatasetColumnDefinition, p as PlayAuthoringDatasetColumnRunInput, q as ToolExecuteResult, r as PlayAuthoringReferenceLike, s as PlayReturnObject$1, t as PlayAuthoringDefineConfig, u as PlayAuthoringDefinedPlay, v as PlayAuthoringFetchOptions, w as PlayAuthoringFileInput, x as PlayAuthoringBindings, y as PlayAuthoringCallExecution, z as PlayAuthoringCallOptions, A as PlayAuthoringFetchResponse, B as PlayAuthoringInputContract, C as PlayAuthoringStepProgramStep, E as PlayAuthoringRuntimeStepOptions, F as PlaySqlListenerDeclaration, G as PlaySqlListenerEvent, H as PlaySqlListenerOperation, I as PlaySqlQuery, J as PlayAuthoringStepOptions, K as PlayAuthoringStepProgram, L as PlayAuthoringStepProgramResolver, M as PlayAuthoringStepResolver, N as PlayToolExecutionRequest } from './compiler-manifest-Bl8kmLx9.mjs';
-export { O as DEEPLINE_EXTRACTOR_TARGETS, Q as DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, R as DeeplineEmailStatusGetterValue, S as DeeplineExtractorTarget, U as DeeplineGetterValue, V as DeeplineGetterValueMap, W as JOB_CHANGE_STATUS_VALUES, X as JobChangeStatus, Y as PHONE_STATUS_VALUES, Z as PhoneStatus, _ as PlayDataset, $ as PlayDatasetInput, a0 as PreviousCell, a1 as ProviderTransientError, a2 as ProviderTransientErrorCategory, a3 as ToolExecutionErrorCategory, a4 as ToolExecutionErrorOrigin, a5 as ToolExecutionFailureV1, a6 as ToolExecutionNetworkKind, a7 as ToolExecutionNetworkScope, a8 as isDeeplineExtractorTarget } from './compiler-manifest-Bl8kmLx9.mjs';
+import { e as PlayRuntimeBackendId, c as PlayCompilerManifest, D as DeeplineError, f as ToolExecutionError, g as ToolExecutionErrorOptions, h as PlayAuthoringColumnMap, i as PlayAuthoringColumnResolver, j as PlayAuthoringRuntimeContext, k as PlayAuthoringConditionalStepResolver, l as PlayAuthoringCsvInput, m as PlayAuthoringCsvOptions, n as PlayAuthoringDatasetBuilder, o as PlayAuthoringDatasetColumnDefinition, p as PlayAuthoringDatasetColumnRunInput, q as ToolExecuteResult, r as PlayAuthoringReferenceLike, s as PlayReturnObject$1, t as PlayAuthoringDefineConfig, u as PlayAuthoringDefinedPlay, v as PlayAuthoringFetchOptions, w as PlayAuthoringFileInput, x as PlayAuthoringBindings, y as PlayAuthoringCallExecution, z as PlayAuthoringCallOptions, A as PlayAuthoringFetchResponse, B as PlayAuthoringInputContract, C as PlayAuthoringStepProgramStep, E as PlayAuthoringRuntimeStepOptions, F as PlaySqlListenerDeclaration, G as PlaySqlListenerEvent, H as PlaySqlListenerOperation, I as PlaySqlQuery, J as PlayAuthoringStepOptions, K as PlayAuthoringStepProgram, L as PlayAuthoringStepProgramResolver, M as PlayAuthoringStepResolver, N as PlayToolExecutionRequest } from './compiler-manifest-TgaC4DeD.mjs';
+export { O as DEEPLINE_EXTRACTOR_TARGETS, Q as DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, R as DeeplineEmailStatusGetterValue, S as DeeplineExtractorTarget, U as DeeplineGetterValue, V as DeeplineGetterValueMap, W as JOB_CHANGE_STATUS_VALUES, X as JobChangeStatus, Y as PHONE_STATUS_VALUES, Z as PhoneStatus, _ as PlayDataset, $ as PlayDatasetInput, a0 as PreviousCell, a1 as ProviderTransientError, a2 as ProviderTransientErrorCategory, a3 as ToolExecutionErrorCategory, a4 as ToolExecutionErrorOrigin, a5 as ToolExecutionFailureV1, a6 as ToolExecutionNetworkKind, a7 as ToolExecutionNetworkScope, a8 as isDeeplineExtractorTarget } from './compiler-manifest-TgaC4DeD.mjs';
 import '@sinclair/typebox';
 
 declare const FIXTURE_BEHAVIOR_VERSION: 1;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { e as PlayRuntimeBackendId, c as PlayCompilerManifest, D as DeeplineError, f as ToolExecutionError, g as ToolExecutionErrorOptions, h as PlayAuthoringColumnMap, i as PlayAuthoringColumnResolver, j as PlayAuthoringRuntimeContext, k as PlayAuthoringConditionalStepResolver, l as PlayAuthoringCsvInput, m as PlayAuthoringCsvOptions, n as PlayAuthoringDatasetBuilder, o as PlayAuthoringDatasetColumnDefinition, p as PlayAuthoringDatasetColumnRunInput, q as ToolExecuteResult, r as PlayAuthoringReferenceLike, s as PlayReturnObject$1, t as PlayAuthoringDefineConfig, u as PlayAuthoringDefinedPlay, v as PlayAuthoringFetchOptions, w as PlayAuthoringFileInput, x as PlayAuthoringBindings, y as PlayAuthoringCallExecution, z as PlayAuthoringCallOptions, A as PlayAuthoringFetchResponse, B as PlayAuthoringInputContract, C as PlayAuthoringStepProgramStep, E as PlayAuthoringRuntimeStepOptions, F as PlaySqlListenerDeclaration, G as PlaySqlListenerEvent, H as PlaySqlListenerOperation, I as PlaySqlQuery, J as PlayAuthoringStepOptions, K as PlayAuthoringStepProgram, L as PlayAuthoringStepProgramResolver, M as PlayAuthoringStepResolver, N as PlayToolExecutionRequest } from './compiler-manifest-Bl8kmLx9.js';
-export { O as DEEPLINE_EXTRACTOR_TARGETS, Q as DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, R as DeeplineEmailStatusGetterValue, S as DeeplineExtractorTarget, U as DeeplineGetterValue, V as DeeplineGetterValueMap, W as JOB_CHANGE_STATUS_VALUES, X as JobChangeStatus, Y as PHONE_STATUS_VALUES, Z as PhoneStatus, _ as PlayDataset, $ as PlayDatasetInput, a0 as PreviousCell, a1 as ProviderTransientError, a2 as ProviderTransientErrorCategory, a3 as ToolExecutionErrorCategory, a4 as ToolExecutionErrorOrigin, a5 as ToolExecutionFailureV1, a6 as ToolExecutionNetworkKind, a7 as ToolExecutionNetworkScope, a8 as isDeeplineExtractorTarget } from './compiler-manifest-Bl8kmLx9.js';
+import { e as PlayRuntimeBackendId, c as PlayCompilerManifest, D as DeeplineError, f as ToolExecutionError, g as ToolExecutionErrorOptions, h as PlayAuthoringColumnMap, i as PlayAuthoringColumnResolver, j as PlayAuthoringRuntimeContext, k as PlayAuthoringConditionalStepResolver, l as PlayAuthoringCsvInput, m as PlayAuthoringCsvOptions, n as PlayAuthoringDatasetBuilder, o as PlayAuthoringDatasetColumnDefinition, p as PlayAuthoringDatasetColumnRunInput, q as ToolExecuteResult, r as PlayAuthoringReferenceLike, s as PlayReturnObject$1, t as PlayAuthoringDefineConfig, u as PlayAuthoringDefinedPlay, v as PlayAuthoringFetchOptions, w as PlayAuthoringFileInput, x as PlayAuthoringBindings, y as PlayAuthoringCallExecution, z as PlayAuthoringCallOptions, A as PlayAuthoringFetchResponse, B as PlayAuthoringInputContract, C as PlayAuthoringStepProgramStep, E as PlayAuthoringRuntimeStepOptions, F as PlaySqlListenerDeclaration, G as PlaySqlListenerEvent, H as PlaySqlListenerOperation, I as PlaySqlQuery, J as PlayAuthoringStepOptions, K as PlayAuthoringStepProgram, L as PlayAuthoringStepProgramResolver, M as PlayAuthoringStepResolver, N as PlayToolExecutionRequest } from './compiler-manifest-TgaC4DeD.js';
+export { O as DEEPLINE_EXTRACTOR_TARGETS, Q as DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS, R as DeeplineEmailStatusGetterValue, S as DeeplineExtractorTarget, U as DeeplineGetterValue, V as DeeplineGetterValueMap, W as JOB_CHANGE_STATUS_VALUES, X as JobChangeStatus, Y as PHONE_STATUS_VALUES, Z as PhoneStatus, _ as PlayDataset, $ as PlayDatasetInput, a0 as PreviousCell, a1 as ProviderTransientError, a2 as ProviderTransientErrorCategory, a3 as ToolExecutionErrorCategory, a4 as ToolExecutionErrorOrigin, a5 as ToolExecutionFailureV1, a6 as ToolExecutionNetworkKind, a7 as ToolExecutionNetworkScope, a8 as isDeeplineExtractorTarget } from './compiler-manifest-TgaC4DeD.js';
 import '@sinclair/typebox';
 
 declare const FIXTURE_BEHAVIOR_VERSION: 1;

package/dist/index.js

@@ -763,7 +763,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.56",
+  version: "0.2.57",
   contracts: {
     api: {
       name: "sdk-http-api",

package/dist/index.mjs

@@ -689,7 +689,7 @@ var SDK_RELEASE = {
   // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
   // exposed storage-dependent synchronous access. This deliberate minor
   // release keeps lazy paging semantics independent of row residency.
-  version: "0.2.56",
+  version: "0.2.57",
   contracts: {
     api: {
       name: "sdk-http-api",

package/dist/install-integrity.json

@@ -225,8 +225,8 @@
     "dist/cli/index.d.ts",
     "dist/cli/index.js",
     "dist/cli/index.mjs",
-    "dist/compiler-manifest-Bl8kmLx9.d.mts",
-    "dist/compiler-manifest-Bl8kmLx9.d.ts",
+    "dist/compiler-manifest-TgaC4DeD.d.mts",
+    "dist/compiler-manifest-TgaC4DeD.d.ts",
     "dist/helpers.d.mts",
     "dist/helpers.d.ts",
     "dist/helpers.js",

package/dist/plays/bundle-play-file.d.mts

@@ -1,5 +1,5 @@
-import { T as ToolExecutionErrorSchemaVersion, P as PlayAuthoringContractEdition, a as PlayArtifactKind$1, b as PlaySandboxRuntimeDeclaration, c as PlayCompilerManifest } from '../compiler-manifest-Bl8kmLx9.mjs';
-export { d as PLAY_ARTIFACT_KINDS } from '../compiler-manifest-Bl8kmLx9.mjs';
+import { T as ToolExecutionErrorSchemaVersion, P as PlayAuthoringContractEdition, a as PlayArtifactKind$1, b as PlaySandboxRuntimeDeclaration, c as PlayCompilerManifest } from '../compiler-manifest-TgaC4DeD.mjs';
+export { d as PLAY_ARTIFACT_KINDS } from '../compiler-manifest-TgaC4DeD.mjs';
 import '@sinclair/typebox';
 
 type PlayPackageImport = {

package/dist/plays/bundle-play-file.d.ts

@@ -1,5 +1,5 @@
-import { T as ToolExecutionErrorSchemaVersion, P as PlayAuthoringContractEdition, a as PlayArtifactKind$1, b as PlaySandboxRuntimeDeclaration, c as PlayCompilerManifest } from '../compiler-manifest-Bl8kmLx9.js';
-export { d as PLAY_ARTIFACT_KINDS } from '../compiler-manifest-Bl8kmLx9.js';
+import { T as ToolExecutionErrorSchemaVersion, P as PlayAuthoringContractEdition, a as PlayArtifactKind$1, b as PlaySandboxRuntimeDeclaration, c as PlayCompilerManifest } from '../compiler-manifest-TgaC4DeD.js';
+export { d as PLAY_ARTIFACT_KINDS } from '../compiler-manifest-TgaC4DeD.js';
 import '@sinclair/typebox';
 
 type PlayPackageImport = {

package/dist/plays/bundle-play-file.mjs

@@ -4059,6 +4059,12 @@ function isDefinePlayCall(node) {
   }
   return false;
 }
+function definePlayName(node) {
+  const expression = unwrapStaticExpression(node);
+  if (!expression || expression.type !== "CallExpression") return null;
+  const first = astArray(expression.arguments)[0] ?? null;
+  return first?.type === "Literal" && typeof first.value === "string" ? first.value : null;
+}
 function listPlayFileExports(sourceCode) {
   const ast = parsePlaySourceForAnalysis(sourceCode);
   if (!ast) return null;
@@ -4108,13 +4114,24 @@ function listPlayFileExports(sourceCode) {
   if (defaultIsPlay) {
     const aliases = defaultLocalName ? [...namedExports.entries()].filter(([, local]) => local === defaultLocalName).map(([exported]) => exported) : [];
     if (defaultLocalName) aliasedLocals.add(defaultLocalName);
-    exports.push({ name: PLAY_DEFAULT_EXPORT, aliases });
+    exports.push({
+      name: PLAY_DEFAULT_EXPORT,
+      aliases,
+      playName: definePlayName(
+        defaultLocalName ? declarations.get(defaultLocalName) ?? null : defaultExpression
+      )
+    });
   }
   for (const [exportedName, localName] of namedExports) {
     if (exportedName === PLAY_DEFAULT_EXPORT) continue;
     if (aliasedLocals.has(localName)) continue;
-    if (!isDefinePlayCall(declarations.get(localName) ?? null)) continue;
-    exports.push({ name: exportedName, aliases: [] });
+    const declaration = declarations.get(localName) ?? null;
+    if (!isDefinePlayCall(declaration)) continue;
+    exports.push({
+      name: exportedName,
+      aliases: [],
+      playName: definePlayName(declaration)
+    });
   }
   return exports;
 }
@@ -4125,10 +4142,17 @@ function canonicalPlayExportName(exportName, exports) {
       return entry.name;
     }
   }
+  for (const entry of exports) {
+    if (entry.playName === requested) return entry.name;
+  }
   return null;
 }
 function playExportNamesForMessage(exports) {
-  return exports.flatMap((entry) => [entry.name, ...entry.aliases]);
+  return exports.flatMap((entry) => [
+    ...entry.playName ? [entry.playName] : [],
+    entry.name,
+    ...entry.aliases
+  ]);
 }
 
 // ../shared_libs/plays/docflow.ts
@@ -4150,6 +4174,7 @@ var ATTRIBUTE = /([A-Za-z][\w-]*)\s*:\s*"([^"\n]*)"/y;
 var MERMAID_NODE_ATTRIBUTES = ["label", "type", "in", "out", "arm"];
 var LEGACY_DOCFLOW_ATTRIBUTES = ["id", ...MERMAID_NODE_ATTRIBUTES];
 var MERMAID_NODE_ID = /^[A-Za-z][\w-]*/;
+var SKETCH_CLASS = /^\s*class\s+([A-Za-z][\w-]*(?:\s*,\s*[A-Za-z][\w-]*)*)\s+sketch\s*;?\s*$/;
 var MERMAID_NODE_SHAPES = [
   ["[[", "]]"],
   ["[(", ")]"],
@@ -4375,7 +4400,7 @@ function inferBindingIo(statement) {
 }
 var MERMAID_BLOCK = /\/\*\*\s*@mermaid(?:\s|\r?\n)([\s\S]*?)\*\//g;
 var LEGACY_BLOCK = /\/\*\*\s*@docflow(?:\s|\r?\n)([\s\S]*?)\*\//;
-var BLOCK_EXPORT_HEADER = /^[A-Za-z_$][\w$]*$/;
+var BLOCK_EXPORT_HEADER = /^[A-Za-z_$][\w$-]*$/;
 function cleanBlockBody(raw) {
   return raw.split(/\r?\n/).map((line) => /^\s*\*/.test(line) ? line.replace(/^\s*\* ?/, "") : line).join("\n").trim();
 }
@@ -4407,6 +4432,7 @@ function parseDocflowBlockGraph(mermaidSource, syntax, errors) {
   const edges = [];
   const subgraphs = /* @__PURE__ */ new Map();
   const ignoredDirectives = [];
+  const sketchIds = /* @__PURE__ */ new Set();
   const subgraphStack = [];
   const subgraphIds = /* @__PURE__ */ new Set();
   if (syntax === "mermaid") {
@@ -4483,7 +4509,15 @@ function parseDocflowBlockGraph(mermaidSource, syntax, errors) {
     let declaredOnThisLine = false;
     const isDirective = /^\s*(?:direction|classDef|class|style|linkStyle|click)\b/i.test(line);
     if (syntax === "mermaid" && isDirective) {
-      ignoredDirectives.push(line.trim());
+      const sketch = SKETCH_CLASS.exec(line);
+      if (sketch) {
+        for (const id of sketch[1].split(",")) {
+          const trimmed = id.trim();
+          if (trimmed) sketchIds.add(trimmed);
+        }
+      } else {
+        ignoredDirectives.push(line.trim());
+      }
     }
     if (syntax === "mermaid" && !isDirective) {
       declaredOnThisLine = addNodes(line, line);
@@ -4532,7 +4566,17 @@ function parseDocflowBlockGraph(mermaidSource, syntax, errors) {
       `Docflow node "${node.id}" is referenced by an edge but never declared with a shape and label, so the canvas would show its id. Declare it once, e.g. \`${node.id}["What this step does"]\`.`
     );
   }
-  return { direction, nodes, edges, subgraphs, ignoredDirectives };
+  for (const id of sketchIds) {
+    const node = nodes.get(id);
+    if (!node) {
+      errors.push(
+        subgraphs.has(id) ? `Docflow \`class ${id} sketch\` names a subgraph. A subgraph is a region, not a box, and never binds code \u2014 drop it from the class line.` : `Docflow \`class ${id} sketch\` names "${id}", which this diagram does not draw.`
+      );
+      continue;
+    }
+    node.sketch = true;
+  }
+  return { direction, nodes, edges, subgraphs, ignoredDirectives, sketchIds };
 }
 function materializeDocflow(block) {
   return {
@@ -4548,7 +4592,8 @@ function materializeDocflow(block) {
 }
 function parsePlayDocflowFile(sourceCode) {
   const errors = [];
-  const bindings = parseDocflowBindings(sourceCode, errors);
+  const rejectedNodeIds = /* @__PURE__ */ new Set();
+  const bindings = parseDocflowBindings(sourceCode, errors, rejectedNodeIds);
   const rawBlocks = [];
   MERMAID_BLOCK.lastIndex = 0;
   for (const match of sourceCode.matchAll(MERMAID_BLOCK)) {
@@ -4576,7 +4621,13 @@ function parsePlayDocflowFile(sourceCode) {
     });
   }
   resolveBlockExports(sourceCode, parsedBlocks, errors);
-  attachBindingsToBlocks(sourceCode, parsedBlocks, bindings, errors);
+  attachBindingsToBlocks(
+    sourceCode,
+    parsedBlocks,
+    bindings,
+    errors,
+    rejectedNodeIds
+  );
   return {
     blocks: parsedBlocks.filter((block) => block.exportName !== null).map((block) => ({
       exportName: block.exportName,
@@ -4723,7 +4774,7 @@ function projectRecordedArms(block, errors) {
     edge.arm = binding.arm;
   }
 }
-function attachBindingsToBlocks(sourceCode, blocks, bindings, errors) {
+function attachBindingsToBlocks(sourceCode, blocks, bindings, errors, rejectedNodeIds) {
   const lineStarts = sourceLineStartsForDocflow(sourceCode);
   const exportRanges = playExportSourceRanges(sourceCode);
   for (const binding of bindings) {
@@ -4764,17 +4815,22 @@ function attachBindingsToBlocks(sourceCode, blocks, bindings, errors) {
     for (const binding of block.bindings) {
       const node = block.nodes.get(binding.nodeId);
       if (binding.label) node.label = binding.label;
+      if (block.sketchIds.has(binding.nodeId)) {
+        errors.push(
+          `Docflow box "${binding.nodeId}" is declared \`class ${binding.nodeId} sketch\` and also bound by \`// @mermaid-node ${binding.nodeId}\` on line ${binding.line}. It is one or the other: drop it from the class line, or drop the annotation.`
+        );
+        continue;
+      }
       if (binding.kind) node.kind = binding.kind;
     }
     projectRecordedArms(block, errors);
-    if (block.syntax !== "docflow") continue;
     const bound = new Set(block.bindings.map((binding) => binding.nodeId));
     for (const node of block.nodes.values()) {
-      if (node.kind !== "conceptual" && !bound.has(node.id)) {
-        errors.push(
-          `Docflow node "${node.id}" has no code binding; mark it type:"conceptual" or bind it.`
-        );
-      }
+      if (node.sketch || node.kind === "conceptual" || bound.has(node.id) || rejectedNodeIds.has(node.id))
+        continue;
+      errors.push(
+        block.syntax === "docflow" ? `Docflow node "${node.id}" has no code binding; mark it type:"conceptual" or bind it.` : `Docflow box "${node.id}" in \`${blockLabel(block)}\` points at nothing, so the canvas can only draw it and say nothing about it. Either put \`// @mermaid-node ${node.id}\` above the statement it runs, or \u2014 if this play has no such statement, because the work happens in another module or inside a loop \u2014 add it to a \`class ${node.id} sketch\` line in the block to declare it a sketch.`
+      );
     }
   }
 }
@@ -4785,7 +4841,7 @@ function sourceLineStartsForDocflow(sourceCode) {
   }
   return starts;
 }
-function parseDocflowBindings(sourceCode, errors) {
+function parseDocflowBindings(sourceCode, errors, rejectedNodeIds) {
   const lines = sourceCode.split(/\r?\n/);
   const bindings = [];
   for (let index = 0; index < lines.length; index += 1) {
@@ -4794,6 +4850,8 @@ function parseDocflowBindings(sourceCode, errors) {
     const legacyMatch = PUT.exec(lines[index]);
     const mermaidMatch = MERMAID_NODE.exec(lines[index]);
     if (!legacyMatch && !mermaidMatch) continue;
+    const annotatedId = mermaidMatch?.[1]?.trim();
+    if (annotatedId) rejectedNodeIds.add(annotatedId);
     const attributes = parseAttributes(
       mermaidMatch ? mermaidMatch[2] ?? "" : legacyMatch[1],
       {
@@ -4803,11 +4861,12 @@ function parseDocflowBindings(sourceCode, errors) {
       }
     );
     if (!attributes) continue;
-    const id = (mermaidMatch ? mermaidMatch[1] : attributes.id)?.trim();
+    const id = (annotatedId ?? attributes.id)?.trim();
     if (!id) {
       errors.push(`Docflow annotation on line ${index + 1} requires id:"\u2026".`);
       continue;
     }
+    rejectedNodeIds.add(id);
     const kind = nodeKind(attributes.type);
     if (attributes.type && !kind) {
       errors.push(
@@ -4853,6 +4912,7 @@ function parseDocflowBindings(sourceCode, errors) {
       ...outputs ? { outputs } : {},
       ioConfidence: "explicit"
     } : inferBindingIo(lines[nextLine]);
+    rejectedNodeIds.delete(id);
     bindings.push({
       nodeId: id,
       line: nextLine + 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepline",
-  "version": "0.2.56",
+  "version": "0.2.57",
   "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
   "license": "MIT",
   "repository": {