deepline 0.2.55 → 0.2.57

package/dist/bundling-sources/shared_libs/play-runtime/runtime-pg-driver-pg.ts

@@ -11,6 +11,20 @@ import {
 } from './runtime-pg-driver';
 
 function wrapPgClient(client: PoolClient): RuntimePoolClient {
+  let released = false;
+  const releaseClient = (destroy = false) => {
+    if (released) return;
+    released = true;
+    client.release(destroy);
+  };
+  const destroyTransport = () => {
+    // `release(true)` is node-postgres' supported pool-client destruction
+    // path. The pool removes the client and Client.end() destroys the socket
+    // when a query is active, while keeping pool accounting correct. Runtime
+    // callers still run their ordinary `finally { release() }` path after a
+    // deadline destroys the transport, so this wrapper owns idempotence.
+    releaseClient(true);
+  };
   return {
     query: <R extends Record<string, unknown> = Record<string, unknown>>(
       text: string,
@@ -24,9 +38,10 @@ function wrapPgClient(client: PoolClient): RuntimePoolClient {
       )(text, params).then((result) => ({
         rows: result.rows,
       })),
-    release: () => {
-      client.release();
+    release: (destroy = false) => {
+      releaseClient(destroy);
     },
+    destroy: destroyTransport,
   };
 }
 

package/dist/bundling-sources/shared_libs/play-runtime/runtime-pg-driver.ts

@@ -13,7 +13,10 @@ export interface RuntimePoolClient {
     text: string,
     params?: unknown[],
   ): Promise<{ rows: R[] }>;
-  release(): void;
+  /** Destroy the physical connection when an active query exceeded its bound. */
+  release(destroy?: boolean): void;
+  /** Interrupt an active query by destroying the physical transport. */
+  destroy?(error?: Error): void;
 }
 
 export interface RuntimePool {

package/dist/bundling-sources/shared_libs/play-runtime/runtime-receipt-store-adapter.ts

@@ -9,7 +9,10 @@ import type {
   RuntimeStepReceipt,
   SkipRuntimeStepReceiptInput,
 } from './ctx-types';
-import { RUNTIME_RECEIPT_GATEWAY_BATCH_MAX_BYTES } from './output-size-limits';
+import {
+  RUNTIME_RECEIPT_GATEWAY_BATCH_MAX_BYTES,
+  RUNTIME_RECEIPT_WRITER_TARGET_BATCH_BYTES,
+} from './output-size-limits';
 import {
   acquireRuntimeReceiptExecutionLockViaAppRuntime,
   AppRuntimeApiResponseError,
@@ -106,6 +109,12 @@ export type RuntimeReceiptStoreHandlers = Required<
   Pick<ContextOptions, ReceiptHandlerName>
 >;
 
+// Four ambiguous 30-second receipt requests previously consumed the writer's
+// entire two-minute budget. Receipt operations are idempotent and buffered, so
+// keep retry ownership here and allow independent transports enough attempts
+// to recover from a short gateway/network impairment.
+export const RUNTIME_RECEIPT_STORE_RETRY_BUDGET_MS = 5 * 60_000;
+
 /**
  * The runner's single Work Receipt Adapter.
  *
@@ -116,6 +125,7 @@ export type RuntimeReceiptStoreHandlers = Required<
  */
 export class RuntimeReceiptStoreAdapter {
   readonly handlers: RuntimeReceiptStoreHandlers;
+  readonly claimsEstablishExecutionFence = true;
   readonly #writer: RuntimeReceiptWriter<ReceiptCommand, ReceiptOutput>;
   #serial = 0;
 
@@ -125,6 +135,7 @@ export class RuntimeReceiptStoreAdapter {
     runId: string;
     maxBatchSize?: number;
     maxBatchBytes?: number;
+    targetBatchBytes?: number;
     maxFlushMs?: number;
     maxBufferedBytes?: number;
     onRetryTelemetry?: (line: string) => void;
@@ -138,8 +149,11 @@ export class RuntimeReceiptStoreAdapter {
       maxBatchSize: options.maxBatchSize,
       maxBatchBytes:
         options.maxBatchBytes ?? RUNTIME_RECEIPT_GATEWAY_BATCH_MAX_BYTES,
+      targetBatchBytes:
+        options.targetBatchBytes ?? RUNTIME_RECEIPT_WRITER_TARGET_BATCH_BYTES,
       maxFlushMs: options.maxFlushMs,
       maxBufferedBytes: options.maxBufferedBytes,
+      maxRetryElapsedMs: RUNTIME_RECEIPT_STORE_RETRY_BUDGET_MS,
       classifyRetryableError: classifyReceiptRetry,
       onRetryEvent: (event) =>
         emitReceiptWriterRetryTelemetry({
@@ -309,6 +323,7 @@ function receiptRetryErrorTelemetry(error: unknown): Record<string, unknown> {
       errorName: error.name,
       transportAttempts: error.attempts,
       transportAction: error.action,
+      transportAttemptId: error.transportAttemptId,
     };
   }
   if (error instanceof AppRuntimeApiResponseError) {
@@ -343,6 +358,7 @@ function emitReceiptWriterRetryTelemetry(input: {
     action: receiptCommandTelemetryAction(event.firstInput),
     batchId: event.batchId,
     batchSize: event.batchSize,
+    batchBytes: event.batchBytes,
     attempt: event.attempt,
     elapsedMs: event.elapsedMs,
     retryAfterMs: event.retryAfterMs,

package/dist/bundling-sources/shared_libs/play-runtime/runtime-receipt-writer.ts

@@ -27,6 +27,7 @@ export type RuntimeReceiptWriterRetryEvent<Input> = {
   attempt: number;
   batchId: number;
   batchSize: number;
+  batchBytes: number;
   firstInput: Input;
   elapsedMs: number;
   retryAfterMs: number;
@@ -103,6 +104,7 @@ export class RuntimeReceiptWriter<Input, Output> {
   readonly #estimateBytes: (input: Input) => number;
   readonly #maxBatchSize: number;
   readonly #maxBatchBytes: number;
+  readonly #targetBatchBytes: number;
   readonly #maxBufferedBytes: number;
   readonly #maxFlushMs: number;
   readonly #maxRetryElapsedMs: number;
@@ -135,6 +137,7 @@ export class RuntimeReceiptWriter<Input, Output> {
     estimateBytes?: (input: Input) => number;
     maxBatchSize?: number;
     maxBatchBytes?: number;
+    targetBatchBytes?: number;
     maxBufferedBytes?: number;
     maxFlushMs?: number;
     maxRetryElapsedMs?: number;
@@ -154,6 +157,10 @@ export class RuntimeReceiptWriter<Input, Output> {
       normalizePositiveInteger(options.maxBatchBytes, this.#maxBufferedBytes),
       this.#maxBufferedBytes,
     );
+    this.#targetBatchBytes = Math.min(
+      normalizePositiveInteger(options.targetBatchBytes, this.#maxBatchBytes),
+      this.#maxBatchBytes,
+    );
     this.#maxFlushMs = Math.max(0, Math.floor(options.maxFlushMs ?? 5));
     this.#maxRetryElapsedMs = normalizePositiveInteger(
       options.maxRetryElapsedMs,
@@ -251,7 +258,7 @@ export class RuntimeReceiptWriter<Input, Output> {
     this.#bufferedBytes += pending.bytes;
     if (
       this.#queued.length >= this.#maxBatchSize ||
-      this.#queuedBytesAtHead() >= this.#maxBatchBytes
+      this.#queuedBytesAtHead() >= this.#targetBatchBytes
     ) {
       this.#clearFlushTimer();
       this.#startPump();
@@ -334,7 +341,10 @@ export class RuntimeReceiptWriter<Input, Output> {
     while (batch.length < this.#maxBatchSize) {
       const next = this.#queued[0];
       if (!next || !Object.is(this.#batchKey(next.input), key)) break;
-      if (batch.length > 0 && batchBytes + next.bytes > this.#maxBatchBytes) {
+      if (
+        batch.length > 0 &&
+        batchBytes + next.bytes > this.#targetBatchBytes
+      ) {
         break;
       }
       this.#queued.shift();
@@ -427,6 +437,10 @@ export class RuntimeReceiptWriter<Input, Output> {
         attempt: input.attempt,
         batchId: input.batchId,
         batchSize: input.batch.length,
+        batchBytes: input.batch.reduce(
+          (total, pending) => total + pending.bytes,
+          0,
+        ),
         firstInput,
         elapsedMs: Date.now() - input.startedAt,
         retryAfterMs: input.retryAfterMs,

package/dist/bundling-sources/shared_libs/play-runtime/runtime-sheet-row-writer.ts

@@ -70,6 +70,14 @@ export type RuntimeSheetRowWriterSummary = {
   terminalRows: number;
 };
 
+export type RuntimeSheetRowWriterDiagnostics = {
+  activeKind: 'terminal' | 'checkpoint' | null;
+  activeRows: number;
+  activeStartedAt: number | null;
+  blockedTerminalRows: number;
+  queuedTerminalRows: number;
+};
+
 export type RuntimeSheetRowSettlement = {
   /**
    * Resolves once the bounded live buffer owns this row. Awaiting this promise
@@ -159,6 +167,7 @@ export class RuntimeSheetRowWriter<Row, Update> {
   readonly #controller = new AbortController();
 
   #active: PendingWrite<Row, Update>[] | null = null;
+  #activeStartedAt: number | null = null;
   #bufferedBytes = 0;
   #liveBytes = 0;
   #timer: ReturnType<typeof setTimeout> | null = null;
@@ -264,6 +273,20 @@ export class RuntimeSheetRowWriter<Row, Update> {
     return this.#finishPromise;
   }
 
+  diagnostics(): RuntimeSheetRowWriterDiagnostics {
+    return {
+      activeKind: this.#active?.[0]?.kind ?? null,
+      activeRows: this.#active?.length ?? 0,
+      activeStartedAt: this.#activeStartedAt,
+      blockedTerminalRows: this.#blocked.filter(
+        (entry) => entry.kind === 'terminal',
+      ).length,
+      queuedTerminalRows: [...this.#live.values()].filter(
+        (entry) => entry.kind === 'terminal',
+      ).length,
+    };
+  }
+
   #enqueueCheckpointUpdate(update: Update): Promise<void> {
     const key = normalizedKey(this.#checkpointKey(update));
     if (this.#terminalAcceptedKeys.has(key)) return Promise.resolve();
@@ -403,6 +426,7 @@ export class RuntimeSheetRowWriter<Row, Update> {
       if (batch.length === 0) return;
       const batchKind = batch[0]!.kind;
       this.#active = batch;
+      this.#activeStartedAt = Date.now();
       try {
         const result = await this.#writeIdenticalBatchWithRetry(batch);
         const resultCommitted = result ? result.committed : undefined;
@@ -429,6 +453,7 @@ export class RuntimeSheetRowWriter<Row, Update> {
         );
         this.#bufferedBytes = Math.max(0, this.#bufferedBytes - releasedBytes);
         this.#active = null;
+        this.#activeStartedAt = null;
         this.#admitBlocked();
         this.#notifyStateChanged();
       }

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backend.ts

@@ -58,6 +58,9 @@ export type PlaySchedulerSubmitInput = {
   force?: boolean;
   /** Explicit cache bypass for completed ctx.tools.execute receipts. */
   forceToolRefresh?: boolean | null;
+  /** Validated per-run ceiling for provider-tool executions and ctx.fetch. */
+  maxConcurrentExternalCalls?: number | null;
+  maxConcurrentRows?: number | null;
   inputFile?: {
     name?: string;
     path?: string;

package/dist/bundling-sources/shared_libs/play-runtime/suspension.ts

@@ -56,6 +56,8 @@ export type PlayExecutionSuspension =
       exitCodePath: string;
       /** Exact customer-code completion fence inside the Daytona sandbox. */
       runtimeCompletedPath?: string;
+      /** Bounded watchdog-owned cause marker for crash-only diagnostics. */
+      terminationDiagnosticPath?: string;
       startedAtMs: number;
       /** Scheduler-owned liveness deadline. The sandbox can renew it only by
        * persisting `heartbeat_at` through the receipt gateway. */

package/dist/bundling-sources/shared_libs/play-runtime/test-runtime-seams.ts

@@ -1,4 +1,5 @@
 import { getRuntimeEnv } from '../runtime-env';
+import type { PlayRunnerEvent } from './protocol';
 
 export const PLAY_RUNTIME_TEST_FAULT_HEADER = 'x-deepline-test-fault';
 
@@ -13,7 +14,23 @@ export type RuntimeTestFaultName =
    * deterministic real-Pg-pool pressure window without changing an action's
    * SQL or outcome.
    */
-  | 'receipt_gateway_hold_ms';
+  | 'receipt_gateway_hold_ms'
+  /**
+   * Synthetic-only bulk-claim fault. The runner forwards this token on the
+   * first qualifying physical claim request only. The gateway holds the real
+   * checked-out scheduler client for the supplied milliseconds, allowing the
+   * claim-operation deadline and connection destruction path to be exercised
+   * end to end without making the fault Machine-local.
+   */
+  | 'receipt_claim_query_hold_once_ms'
+  /**
+   * Synthetic-only response-boundary fault. The runner fully receives a
+   * successful bulk receipt-claim response, then reports the configured first
+   * N physical requests as request timeouts. This proves ambiguous-delivery
+   * replay without depending on which gateway Machine accepted the request.
+   */
+  | 'receipt_claim_response_timeout'
+  | 'runtime_sheet_page_tail_hold_ms';
 
 export type RuntimeTestFaultRegistry = {
   consume(name: RuntimeTestFaultName): boolean;
@@ -75,6 +92,9 @@ const SUPPORTED_RUNTIME_TEST_FAULTS = new Set<RuntimeTestFaultName>([
   'worker_receipt_complete_write_fail',
   'invocation_response_delivery_abort',
   'receipt_gateway_hold_ms',
+  'receipt_claim_query_hold_once_ms',
+  'receipt_claim_response_timeout',
+  'runtime_sheet_page_tail_hold_ms',
 ]);
 
 const RUNTIME_TEST_POLICY_MS_FIELDS = new Set([
@@ -149,6 +169,65 @@ function parseRuntimeTestFaultHeader(
   return faults;
 }
 
+/** Parse a known fault count without authorizing a request. Unknown/skewed headers return 0. */
+export function recognizedRuntimeTestFaultCount(
+  rawHeader: string | null | undefined,
+  name: RuntimeTestFaultName,
+): number {
+  const header = rawHeader?.trim();
+  if (!header) return 0;
+  const parsed = parseRuntimeTestFaultHeader(header);
+  if ('error' in parsed) return 0;
+  return parsed.get(name) ?? 0;
+}
+
+export function runtimeSheetPageTailRowsContainTarget(
+  rows: readonly unknown[],
+): boolean {
+  return rows.some((row) => {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) return false;
+    const record = row as Record<string, unknown>;
+    return record.inputIndex === 999 || record.input_index === 999;
+  });
+}
+
+export function runtimeSheetPageTailWriteMarkerEvent(
+  runtimeTestFaultHeader: string | null | undefined,
+  rows: readonly Record<string, unknown>[],
+  tableNamespace: string,
+  dbSessionStrategy: string | null | undefined,
+): PlayRunnerEvent | null {
+  if (
+    dbSessionStrategy !== 'gateway_only' ||
+    recognizedRuntimeTestFaultCount(
+      runtimeTestFaultHeader,
+      'runtime_sheet_page_tail_hold_ms',
+    ) <= 0 ||
+    !runtimeSheetPageTailRowsContainTarget(rows)
+  ) {
+    return null;
+  }
+  return {
+    type: 'log',
+    at: new Date().toISOString(),
+    source: 'play',
+    line: `[runtime.sheet-page-tail-write] phase=start table=${tableNamespace} rows=${rows.length}`,
+  };
+}
+
+export function runtimeSheetPageTailHoldCompletedEvent(
+  holdMs: number | null | undefined,
+  tableNamespace: string,
+): PlayRunnerEvent | null {
+  if (!Number.isInteger(holdMs) || (holdMs ?? 0) <= 0) return null;
+  return {
+    type: 'log',
+    at: new Date().toISOString(),
+    source: 'play',
+    line: `[runtime.sheet-page-tail-hold] phase=finish table=${tableNamespace} hold_ms=${holdMs}`,
+  };
+}
+
 function readPositiveIntegerField(input: {
   value: unknown;
   path: string;

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,