deepline 0.2.53 → 0.2.55

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

@@ -26,8 +26,7 @@ import {
   sep
 } from "path";
 import { builtinModules } from "module";
-import { Parser } from "acorn";
-import { tsPlugin } from "acorn-typescript";
+import { Parser as Parser2 } from "acorn";
 import { build, transformSync } from "esbuild";
 
 // ../shared_libs/play-runtime/backend.ts
@@ -3449,6 +3448,22 @@ var PLAY_AUTHORING_FIELD_REGISTRY = {
     description: "Whether the dataset returns all rows or only newly admitted rows.",
     errorMessage: 'ctx.dataset run mode must be "upsert" or "net_new".'
   },
+  "ctx.dataset.run.undrawnColumns": {
+    schema: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+    fixtures: {
+      valid: ["miss_reason"],
+      invalid: [],
+      absent: void 0,
+      unresolved: { expression: "undrawnColumns" },
+      edition1: ["miss_reason"]
+    },
+    referenceType: "readonly string[]",
+    required: false,
+    resolution: "static-when-present",
+    issueCode: "play_authoring_dataset_option_invalid",
+    description: "Computed columns deliberately left out of the authored @mermaid diagram.",
+    errorMessage: "ctx.dataset run undrawnColumns must be a non-empty array of static column-name strings."
+  },
   "ctx.step.id": {
     schema: Type.String({ minLength: 1 }),
     fixtures: {
@@ -3936,7 +3951,7 @@ var PLAY_AUTHORING_CLOUD_TYPE_DECLARATIONS = [
   "export type StepProgramOutput<TProgram> = TProgram extends StepProgram<unknown, infer Output, unknown> ? Output : never;",
   "export type DatasetRowKey<InputRow extends object> = (keyof InputRow & string) | readonly (keyof InputRow & string)[] | ((row: InputRow, index: number) => string | number | readonly unknown[]);",
   "export type DatasetDefinitionOptions<InputRow extends object> = { key?: DatasetRowKey<InputRow> };",
-  `export type DatasetRunOptions<InputRow extends object> = { description?: ${cloudReferenceType("ctx.dataset.run.description")}; key?: DatasetRowKey<InputRow>; onRowError?: ${cloudReferenceType("ctx.dataset.run.onRowError")}; mode?: ${cloudReferenceType("ctx.dataset.run.mode")} };`,
+  `export type DatasetRunOptions<InputRow extends object> = { description?: ${cloudReferenceType("ctx.dataset.run.description")}; key?: DatasetRowKey<InputRow>; onRowError?: ${cloudReferenceType("ctx.dataset.run.onRowError")}; mode?: ${cloudReferenceType("ctx.dataset.run.mode")}; undrawnColumns?: ${cloudReferenceType("ctx.dataset.run.undrawnColumns")} };`,
   "export type DatasetBuilder<InputRow extends object, OutputRow extends object> = {",
   "  withColumn<Name extends string, Value>(name: Name, resolver: ColumnResolver<OutputRow, Value>): DatasetBuilder<InputRow, OutputRow & Record<Name, Value>>;",
   "  withColumn<Name extends string, Value>(name: Name, definition: DatasetColumnDefinition<OutputRow, Value> & { readonly runIf: (row: OutputRow, index: number) => boolean | Promise<boolean> }): DatasetBuilder<InputRow, OutputRow & Record<Name, Value | null>>;",
@@ -3989,6 +4004,1123 @@ function buildPlayContractCompatibility(input) {
   };
 }
 
+// ../shared_libs/plays/ts-ast.ts
+import { Parser } from "acorn";
+import { tsPlugin } from "acorn-typescript";
+var TypeScriptParser = Parser.extend(
+  tsPlugin({
+    allowSatisfies: true,
+    jsx: {
+      allowNamespaces: true,
+      allowNamespacedObjects: true
+    }
+  })
+);
+function isAstNode(value) {
+  return value !== null && typeof value === "object" && "type" in value;
+}
+function astArray(value) {
+  return Array.isArray(value) ? value.filter(isAstNode) : [];
+}
+function parsePlaySourceForAnalysis(sourceCode) {
+  try {
+    return TypeScriptParser.parse(sourceCode, {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      allowHashBang: true
+    });
+  } catch {
+    return null;
+  }
+}
+
+// ../shared_libs/plays/play-exports.ts
+var PLAY_DEFAULT_EXPORT = "default";
+function getIdentifierName(node) {
+  return isAstNode(node) && node.type === "Identifier" ? typeof node.name === "string" ? node.name : null : null;
+}
+function unwrapStaticExpression(node) {
+  let current = node;
+  while (current && (current.type === "TSAsExpression" || current.type === "TSSatisfiesExpression" || current.type === "TSTypeAssertion" || current.type === "TSNonNullExpression" || current.type === "ParenthesizedExpression")) {
+    current = isAstNode(current.expression) ? current.expression : null;
+  }
+  return current;
+}
+function isDefinePlayCall(node) {
+  const expression = unwrapStaticExpression(node);
+  if (!expression || expression.type !== "CallExpression") return false;
+  const callee = isAstNode(expression.callee) ? expression.callee : null;
+  if (!callee) return false;
+  if (callee.type === "Identifier") {
+    return callee.name === "definePlay" || callee.name === "defineWorkflow";
+  }
+  if (callee.type === "MemberExpression" && !callee.computed && isAstNode(callee.property) && callee.property.type === "Identifier") {
+    return callee.property.name === "definePlay" || callee.property.name === "defineWorkflow";
+  }
+  return false;
+}
+function listPlayFileExports(sourceCode) {
+  const ast = parsePlaySourceForAnalysis(sourceCode);
+  if (!ast) return null;
+  const declarations = /* @__PURE__ */ new Map();
+  const namedExports = /* @__PURE__ */ new Map();
+  let defaultExpression = null;
+  const recordDeclarations = (declaration, exported) => {
+    for (const declarator of astArray(declaration.declarations)) {
+      const name = getIdentifierName(declarator.id);
+      if (!name) continue;
+      declarations.set(
+        name,
+        isAstNode(declarator.init) ? declarator.init : null
+      );
+      if (exported) namedExports.set(name, name);
+    }
+  };
+  for (const statement of astArray(ast.body)) {
+    if (statement.type === "VariableDeclaration") {
+      recordDeclarations(statement, false);
+      continue;
+    }
+    if (statement.type === "ExportDefaultDeclaration") {
+      defaultExpression = isAstNode(statement.declaration) ? statement.declaration : null;
+      continue;
+    }
+    if (statement.type === "TSExportAssignment") {
+      defaultExpression = isAstNode(statement.expression) ? statement.expression : null;
+      continue;
+    }
+    if (statement.type !== "ExportNamedDeclaration") continue;
+    if (isAstNode(statement.declaration) && statement.declaration.type === "VariableDeclaration") {
+      recordDeclarations(statement.declaration, true);
+    }
+    for (const specifier of astArray(statement.specifiers)) {
+      const localName = getIdentifierName(specifier.local);
+      const exportedName = getIdentifierName(specifier.exported);
+      if (localName && exportedName) namedExports.set(exportedName, localName);
+    }
+  }
+  const defaultLocalName = getIdentifierName(
+    unwrapStaticExpression(defaultExpression)
+  );
+  const defaultIsPlay = defaultLocalName ? isDefinePlayCall(declarations.get(defaultLocalName) ?? null) : isDefinePlayCall(defaultExpression);
+  const exports = [];
+  const aliasedLocals = /* @__PURE__ */ new Set();
+  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 });
+  }
+  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: [] });
+  }
+  return exports;
+}
+function canonicalPlayExportName(exportName, exports) {
+  const requested = exportName?.trim() || PLAY_DEFAULT_EXPORT;
+  for (const entry of exports) {
+    if (entry.name === requested || entry.aliases.includes(requested)) {
+      return entry.name;
+    }
+  }
+  return null;
+}
+function playExportNamesForMessage(exports) {
+  return exports.flatMap((entry) => [entry.name, ...entry.aliases]);
+}
+
+// ../shared_libs/plays/docflow.ts
+var PLAY_DOCFLOW_NODE_KINDS = [
+  "action",
+  "decision",
+  "dataset",
+  "play",
+  "conceptual"
+];
+var PLAY_DOCFLOW_ARMS = [
+  "run",
+  "else"
+];
+var FLOW_START = /^\s*(?:flowchart|graph)\s+(LR|RL|TB|TD|BT)\s*$/i;
+var PUT = /^\s*\/\/\s*put\s+(.+)$/;
+var MERMAID_NODE = /^\s*\/\/\s*@mermaid-node\s+([A-Za-z][\w-]*)(?:\s+(.*))?$/;
+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 MERMAID_NODE_SHAPES = [
+  ["[[", "]]"],
+  ["[(", ")]"],
+  ["([", "])"],
+  ["{{", "}}"],
+  ["((", "))"],
+  ["[/", "/]"],
+  ["[\\", "\\]"],
+  ["[/", "\\]"],
+  ["[\\", "/]"],
+  ["[", "]"],
+  ["{", "}"],
+  ["(", ")"],
+  [">", "]"]
+];
+var SUBGRAPH_OPEN = /^\s*subgraph\s+([A-Za-z][\w-]*)\s*(?:\[(.*)\])?\s*$/i;
+var SUBGRAPH_END = /^\s*end\s*$/i;
+var DOCFLOW_EDGE_CONNECTOR = /^\s*-->(?:\|([^|]+)\|)?/;
+var MERMAID_EDGE_CONNECTOR = /^\s*(?:-->|-\.->|==>|---)(?:\|([^|]+)\|)?/;
+var DOCFLOW_PATH = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/;
+var IDENTIFIER = /[A-Za-z_$][\w$]*/g;
+var JS_WORDS = /* @__PURE__ */ new Set([
+  "async",
+  "await",
+  "const",
+  "else",
+  "false",
+  "if",
+  "let",
+  "new",
+  "null",
+  "return",
+  "true",
+  "undefined",
+  "var"
+]);
+function parseAttributes(source, input) {
+  const attributes = {};
+  const validAttributes = input.annotation === "@mermaid-node" ? MERMAID_NODE_ATTRIBUTES : LEGACY_DOCFLOW_ATTRIBUTES;
+  let cursor = 0;
+  while (cursor < source.length) {
+    cursor += /^\s*/.exec(source.slice(cursor))?.[0].length ?? 0;
+    if (cursor >= source.length) break;
+    ATTRIBUTE.lastIndex = cursor;
+    const match = ATTRIBUTE.exec(source);
+    if (!match) {
+      const fragment = source.slice(cursor).split(/\s+/)[0] ?? source.slice(cursor);
+      input.errors.push(
+        `Docflow annotation on line ${input.line} has malformed attribute ${JSON.stringify(fragment)}. Use key:"value" pairs. Valid attributes: ${validAttributes.map((name2) => `"${name2}"`).join(", ")}.`
+      );
+      return null;
+    }
+    const name = match[1];
+    if (!validAttributes.includes(name)) {
+      input.errors.push(
+        `Docflow annotation on line ${input.line} has unknown attribute "${name}". Valid attributes: ${validAttributes.map((option) => `"${option}"`).join(", ")}.`
+      );
+      return null;
+    }
+    if (Object.prototype.hasOwnProperty.call(attributes, name)) {
+      input.errors.push(
+        `Docflow annotation on line ${input.line} repeats attribute "${name}". Write each attribute once.`
+      );
+      return null;
+    }
+    attributes[name] = match[2];
+    cursor = ATTRIBUTE.lastIndex;
+  }
+  return attributes;
+}
+function nodeKind(value) {
+  if (!value) return void 0;
+  return PLAY_DOCFLOW_NODE_KINDS.includes(value) ? value : null;
+}
+function nodeArm(value) {
+  if (!value) return void 0;
+  return PLAY_DOCFLOW_ARMS.includes(value) ? value : null;
+}
+var SHAPE_KINDS = {
+  "{": "decision",
+  "[[": "play"
+};
+var MERMAID_LABEL_LOOKS_LIKE_SOURCE = /^(?:\[|\{|\(|>)/;
+function parseMermaidNodeAtStart(source) {
+  const leadingWhitespace = /^\s*/.exec(source)?.[0].length ?? 0;
+  const idMatch = MERMAID_NODE_ID.exec(source.slice(leadingWhitespace));
+  if (!idMatch) return null;
+  const id = idMatch[0];
+  let cursor = leadingWhitespace + id.length;
+  cursor += /^\s*/.exec(source.slice(cursor))?.[0].length ?? 0;
+  const shape = MERMAID_NODE_SHAPES.find(
+    ([open2]) => source.startsWith(open2, cursor)
+  );
+  if (!shape) {
+    return { id, label: id, kind: "action", length: cursor, shaped: false };
+  }
+  const [open, close] = shape;
+  const labelStart = cursor + open.length;
+  const openingQuote = source[labelStart];
+  let labelEnd = -1;
+  if (openingQuote === '"' || openingQuote === "'") {
+    for (let index = labelStart + 1; index < source.length; index += 1) {
+      if (source[index] === "\\") {
+        index += 1;
+        continue;
+      }
+      if (source[index] !== openingQuote) continue;
+      const whitespace = /^\s*/.exec(source.slice(index + 1))?.[0].length ?? 0;
+      const candidate = index + 1 + whitespace;
+      if (source.startsWith(close, candidate)) {
+        labelEnd = candidate;
+        break;
+      }
+    }
+  } else {
+    labelEnd = source.indexOf(close, labelStart);
+  }
+  if (labelEnd < 0) {
+    return {
+      id,
+      label: id,
+      kind: "action",
+      length: cursor + open.length,
+      shaped: false,
+      unterminated: { open, close }
+    };
+  }
+  const rawLabel = source.slice(labelStart, labelEnd).trim();
+  const label = rawLabel.length >= 2 && (rawLabel.startsWith('"') && rawLabel.endsWith('"') || rawLabel.startsWith("'") && rawLabel.endsWith("'")) ? rawLabel.slice(1, -1) : rawLabel;
+  return {
+    id,
+    label: label || id,
+    kind: SHAPE_KINDS[open] ?? "action",
+    length: labelEnd + close.length,
+    shaped: true
+  };
+}
+function parseShapedMermaidNodes(fragment) {
+  const nodes = [];
+  let cursor = 0;
+  while (cursor < fragment.length) {
+    const identifier = /[A-Za-z][\w-]*/.exec(fragment.slice(cursor));
+    if (!identifier) break;
+    const start = cursor + (identifier.index ?? 0);
+    const parsed = parseMermaidNodeAtStart(fragment.slice(start));
+    if (parsed?.shaped || parsed?.unterminated) nodes.push(parsed);
+    cursor = start + Math.max(parsed?.length ?? identifier[0].length, 1);
+  }
+  return nodes;
+}
+function parseEdgeChain(line, syntax) {
+  let remaining = line;
+  const first = parseMermaidNodeAtStart(remaining);
+  if (!first) return null;
+  const nodes = [first];
+  const labels = [];
+  remaining = remaining.slice(first.length);
+  while (remaining.trim()) {
+    const connector = (syntax === "mermaid" ? MERMAID_EDGE_CONNECTOR : DOCFLOW_EDGE_CONNECTOR).exec(remaining);
+    if (!connector) return null;
+    remaining = remaining.slice(connector[0].length);
+    const next = parseMermaidNodeAtStart(remaining);
+    if (!next) return null;
+    labels.push(connector[1]?.trim() || void 0);
+    nodes.push(next);
+    remaining = remaining.slice(next.length);
+  }
+  return nodes.length > 1 ? { nodes, labels } : null;
+}
+function parseContractPaths(value, attribute, nodeId, line, errors) {
+  if (value === void 0) return void 0;
+  const paths = value.split(",").map((path) => path.trim()).filter(Boolean);
+  if (paths.some((path) => !DOCFLOW_PATH.test(path))) {
+    errors.push(
+      `Docflow annotation "${nodeId}" on line ${line} has an invalid ${attribute}:"\u2026" contract. Use comma-separated identifiers or property paths only.`
+    );
+    return void 0;
+  }
+  return [...new Set(paths)];
+}
+function inferBindingIo(statement) {
+  const returned = /^return\s+(.+?);?\s*$/.exec(statement.trim());
+  if (returned) {
+    const inputs2 = /* @__PURE__ */ new Set();
+    const expression2 = returned[1].replace(/(['"`])(?:\\.|(?!\1).)*\1/g, "");
+    IDENTIFIER.lastIndex = 0;
+    for (const match of expression2.matchAll(IDENTIFIER)) {
+      const identifier = match[0];
+      const index = match.index ?? 0;
+      if (JS_WORDS.has(identifier) || expression2[index - 1] === ".") continue;
+      inputs2.add(identifier);
+    }
+    return {
+      inputs: [...inputs2],
+      ioConfidence: "inferred"
+    };
+  }
+  const assignment = /^(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*([^;]+);?\s*$/.exec(
+    statement.trim()
+  );
+  if (!assignment || assignment[2].includes("await")) {
+    return { ioConfidence: "ambiguous" };
+  }
+  const output = assignment[1];
+  const expression = assignment[2];
+  const inputs = /* @__PURE__ */ new Set();
+  IDENTIFIER.lastIndex = 0;
+  for (const match of expression.matchAll(IDENTIFIER)) {
+    const identifier = match[0];
+    const index = match.index ?? 0;
+    const previous = expression[index - 1] ?? "";
+    const next = expression[index + identifier.length] ?? "";
+    if (JS_WORDS.has(identifier) || identifier === output || previous === "." || next === ":" || /^\s*\(/.test(expression.slice(index + identifier.length))) {
+      continue;
+    }
+    inputs.add(identifier);
+  }
+  return {
+    inputs: [...inputs],
+    outputs: [output],
+    ioConfidence: "inferred"
+  };
+}
+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$]*$/;
+function cleanBlockBody(raw) {
+  return raw.split(/\r?\n/).map((line) => /^\s*\*/.test(line) ? line.replace(/^\s*\* ?/, "") : line).join("\n").trim();
+}
+function splitBlockExportHeader(body) {
+  const newlineIndex = body.indexOf("\n");
+  const firstLine = (newlineIndex < 0 ? body : body.slice(0, newlineIndex)).trim();
+  if (!BLOCK_EXPORT_HEADER.test(firstLine) || /^(?:flowchart|graph)$/i.test(firstLine)) {
+    return { exportName: null, diagram: body };
+  }
+  return {
+    exportName: firstLine,
+    diagram: newlineIndex < 0 ? "" : body.slice(newlineIndex + 1).trim()
+  };
+}
+function blockLabel(block) {
+  const tag = block.syntax === "mermaid" ? "@mermaid" : "@docflow";
+  return block.authoredExportName ? `${tag} ${block.authoredExportName}` : tag;
+}
+function parseDocflowBlockGraph(mermaidSource, syntax, errors) {
+  const docLines = mermaidSource.split(/\r?\n/).filter((line) => line.trim() && !line.trim().startsWith("%%"));
+  const direction = FLOW_START.exec(docLines[0] ?? "")?.[1]?.toUpperCase();
+  if (!direction) {
+    errors.push(
+      "Docflow must start with `flowchart` or `graph` and direction `LR`, `RL`, `TB`, `TD`, or `BT`."
+    );
+    return null;
+  }
+  const nodes = /* @__PURE__ */ new Map();
+  const edges = [];
+  const subgraphs = /* @__PURE__ */ new Map();
+  const ignoredDirectives = [];
+  const subgraphStack = [];
+  const subgraphIds = /* @__PURE__ */ new Set();
+  if (syntax === "mermaid") {
+    for (const line of docLines.slice(1)) {
+      const opened = SUBGRAPH_OPEN.exec(line);
+      if (opened) subgraphIds.add(opened[1]);
+    }
+  }
+  const declaredIds = /* @__PURE__ */ new Set();
+  const addNodes = (fragment, line) => {
+    let sawDeclaration = false;
+    for (const node of parseShapedMermaidNodes(fragment)) {
+      const { id, label, kind } = node;
+      if (node.unterminated) {
+        sawDeclaration = true;
+        errors.push(
+          `Docflow node "${id}" opens with \`${node.unterminated.open}\` but never closes with \`${node.unterminated.close}\`: ${line.trim()}`
+        );
+        continue;
+      }
+      sawDeclaration = true;
+      if (subgraphIds.has(id)) {
+        errors.push(
+          `Docflow subgraph "${id}" collides with a node of the same id.`
+        );
+        continue;
+      }
+      if (MERMAID_LABEL_LOOKS_LIKE_SOURCE.test(label)) {
+        errors.push(
+          `Docflow node "${id}" has an unreadable label \`${label}\` \u2014 the shape around it is not one this parser knows, so its own syntax became the label. Supported shapes: ${MERMAID_NODE_SHAPES.map(([open, close]) => `${open}\u2026${close}`).join(", ")}. Line: ${line.trim()}`
+        );
+        continue;
+      }
+      declaredIds.add(id);
+      const existing = nodes.get(id);
+      if (existing && existing.label === existing.id && label !== id) {
+        existing.label = label;
+        existing.kind = kind;
+      } else if (existing && existing.label !== label) {
+        errors.push(`Docflow node "${id}" has conflicting labels.`);
+      } else if (!existing) {
+        nodes.set(id, { id, label, kind });
+        subgraphStack[subgraphStack.length - 1]?.memberIds.push(id);
+      }
+    }
+    return sawDeclaration;
+  };
+  for (const line of docLines.slice(1)) {
+    if (syntax === "mermaid") {
+      const opened = SUBGRAPH_OPEN.exec(line);
+      if (opened) {
+        const id = opened[1];
+        const rawLabel = opened[2]?.trim() ?? "";
+        const label = rawLabel.length >= 2 && (rawLabel.startsWith('"') && rawLabel.endsWith('"') || rawLabel.startsWith("'") && rawLabel.endsWith("'")) ? rawLabel.slice(1, -1) : rawLabel;
+        const subgraph = {
+          id,
+          label: label || id,
+          memberIds: []
+        };
+        subgraphs.set(id, subgraph);
+        subgraphStack.push(subgraph);
+        continue;
+      }
+      if (SUBGRAPH_END.test(line)) {
+        if (subgraphStack.length === 0) {
+          errors.push(
+            "Docflow has an `end` with no open `subgraph` above it. Every `end` closes exactly one `subgraph`."
+          );
+        }
+        subgraphStack.pop();
+        continue;
+      }
+    }
+    let declaredOnThisLine = false;
+    const isDirective = /^\s*(?:direction|classDef|class|style|linkStyle|click)\b/i.test(line);
+    if (syntax === "mermaid" && isDirective) {
+      ignoredDirectives.push(line.trim());
+    }
+    if (syntax === "mermaid" && !isDirective) {
+      declaredOnThisLine = addNodes(line, line);
+    }
+    const chain = parseEdgeChain(line, syntax);
+    if (!chain) {
+      if (syntax === "docflow") {
+        errors.push(`Unsupported docflow line: ${line.trim()}`);
+      } else if (!isDirective && !declaredOnThisLine) {
+        errors.push(
+          `Docflow line is not an edge, a node declaration, or a directive this parser understands: ${line.trim()}`
+        );
+      }
+      continue;
+    }
+    if (syntax === "docflow") addNodes(line, line);
+    for (const node of chain.nodes) {
+      if (subgraphIds.has(node.id)) continue;
+      const existing = nodes.get(node.id);
+      if (!existing) {
+        nodes.set(node.id, node);
+        subgraphStack[subgraphStack.length - 1]?.memberIds.push(node.id);
+      } else if (existing.label === existing.id && node.label !== node.id) {
+        existing.label = node.label;
+        existing.kind = node.kind;
+      }
+    }
+    for (let index = 0; index < chain.nodes.length - 1; index += 1) {
+      edges.push({
+        from: chain.nodes[index].id,
+        to: chain.nodes[index + 1].id,
+        ...chain.labels[index] ? { label: chain.labels[index] } : {}
+      });
+    }
+  }
+  if (subgraphStack.length > 0) {
+    errors.push(
+      `Docflow subgraph${subgraphStack.length === 1 ? "" : "s"} ${subgraphStack.map((subgraph) => `"${subgraph.id}"`).join(
+        ", "
+      )} ${subgraphStack.length === 1 ? "is" : "are"} never closed with \`end\`. Everything below an unclosed subgraph is silently drawn inside it.`
+    );
+  }
+  for (const node of nodes.values()) {
+    if (declaredIds.has(node.id) || subgraphIds.has(node.id)) continue;
+    errors.push(
+      `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 };
+}
+function materializeDocflow(block) {
+  return {
+    direction: block.direction,
+    nodes: [...block.nodes.values()],
+    edges: block.edges,
+    bindings: block.bindings,
+    syntax: block.syntax,
+    mermaidSource: block.mermaidSource,
+    ...block.subgraphs.size ? { subgraphs: [...block.subgraphs.values()] } : {},
+    ...block.ignoredDirectives.length ? { ignoredDirectives: block.ignoredDirectives } : {}
+  };
+}
+function parsePlayDocflowFile(sourceCode) {
+  const errors = [];
+  const bindings = parseDocflowBindings(sourceCode, errors);
+  const rawBlocks = [];
+  MERMAID_BLOCK.lastIndex = 0;
+  for (const match of sourceCode.matchAll(MERMAID_BLOCK)) {
+    rawBlocks.push({ syntax: "mermaid", body: cleanBlockBody(match[1]) });
+  }
+  if (rawBlocks.length === 0) {
+    const legacy = LEGACY_BLOCK.exec(sourceCode);
+    if (legacy) {
+      rawBlocks.push({ syntax: "docflow", body: cleanBlockBody(legacy[1]) });
+    }
+  }
+  if (rawBlocks.length === 0) return { blocks: [], bindings, errors };
+  const parsedBlocks = [];
+  for (const raw of rawBlocks) {
+    const { exportName, diagram } = splitBlockExportHeader(raw.body);
+    const graph = parseDocflowBlockGraph(diagram, raw.syntax, errors);
+    if (!graph) continue;
+    parsedBlocks.push({
+      ...graph,
+      authoredExportName: exportName,
+      exportName: null,
+      syntax: raw.syntax,
+      mermaidSource: diagram,
+      bindings: []
+    });
+  }
+  resolveBlockExports(sourceCode, parsedBlocks, errors);
+  attachBindingsToBlocks(sourceCode, parsedBlocks, bindings, errors);
+  return {
+    blocks: parsedBlocks.filter((block) => block.exportName !== null).map((block) => ({
+      exportName: block.exportName,
+      docflow: materializeDocflow(block)
+    })),
+    bindings,
+    errors
+  };
+}
+function resolveBlockExports(sourceCode, blocks, errors) {
+  const fileExports = blocks.some((block) => block.authoredExportName !== null) ? listPlayFileExports(sourceCode) : null;
+  const claimed = /* @__PURE__ */ new Map();
+  for (const block of blocks) {
+    if (block.authoredExportName === null) {
+      block.exportName = PLAY_DEFAULT_EXPORT;
+    } else if (fileExports === null) {
+      block.exportName = block.authoredExportName;
+    } else {
+      const canonical = canonicalPlayExportName(
+        block.authoredExportName,
+        fileExports
+      );
+      if (!canonical) {
+        const available = playExportNamesForMessage(fileExports);
+        errors.push(
+          `Docflow block \`${blockLabel(block)}\` names an export this file does not define. ` + (available.length ? `Exported plays: ${available.map((name) => `"${name}"`).join(", ")}.` : "This file exports no play.")
+        );
+        continue;
+      }
+      block.exportName = canonical;
+    }
+    const existing = claimed.get(block.exportName);
+    if (existing) {
+      errors.push(
+        `Docflow blocks \`${blockLabel(existing)}\` and \`${blockLabel(block)}\` both describe export "${block.exportName}". One diagram per export.`
+      );
+      block.exportName = null;
+      continue;
+    }
+    claimed.set(block.exportName, block);
+  }
+}
+function unwrapExportExpression(node) {
+  let current = node;
+  while (current && (current.type === "TSAsExpression" || current.type === "TSSatisfiesExpression" || current.type === "TSTypeAssertion" || current.type === "TSNonNullExpression" || current.type === "ParenthesizedExpression")) {
+    current = isAstNode(current.expression) ? current.expression : null;
+  }
+  return current;
+}
+function playExportSourceRanges(sourceCode) {
+  const ast = parsePlaySourceForAnalysis(sourceCode);
+  const fileExports = listPlayFileExports(sourceCode);
+  if (!ast || !fileExports) return [];
+  const declarations = /* @__PURE__ */ new Map();
+  const namedExports = /* @__PURE__ */ new Map();
+  let defaultExpression = null;
+  for (const statement of astArray(ast.body)) {
+    const recordDeclarations = (declaration, exported) => {
+      for (const declarator of astArray(declaration.declarations)) {
+        const id = isAstNode(declarator.id) ? declarator.id : null;
+        const name = id?.type === "Identifier" && typeof id.name === "string" ? id.name : null;
+        if (!name) continue;
+        declarations.set(
+          name,
+          isAstNode(declarator.init) ? declarator.init : null
+        );
+        if (exported) namedExports.set(name, name);
+      }
+    };
+    if (statement.type === "VariableDeclaration") {
+      recordDeclarations(statement, false);
+    } else if (statement.type === "ExportDefaultDeclaration") {
+      defaultExpression = isAstNode(statement.declaration) ? statement.declaration : null;
+    } else if (statement.type === "TSExportAssignment") {
+      defaultExpression = isAstNode(statement.expression) ? statement.expression : null;
+    } else if (statement.type === "ExportNamedDeclaration") {
+      if (isAstNode(statement.declaration) && statement.declaration.type === "VariableDeclaration") {
+        recordDeclarations(statement.declaration, true);
+      }
+      for (const specifier of astArray(statement.specifiers)) {
+        const local = isAstNode(specifier.local) ? specifier.local : null;
+        const exported = isAstNode(specifier.exported) ? specifier.exported : null;
+        if (local?.type === "Identifier" && typeof local.name === "string" && exported?.type === "Identifier" && typeof exported.name === "string") {
+          namedExports.set(exported.name, local.name);
+        }
+      }
+    }
+  }
+  const resolveCall = (expression, seen = /* @__PURE__ */ new Set()) => {
+    const unwrapped = unwrapExportExpression(expression);
+    if (!unwrapped) return null;
+    if (isDefinePlayCall(unwrapped)) return unwrapped;
+    if (unwrapped.type !== "Identifier" || typeof unwrapped.name !== "string" || seen.has(unwrapped.name)) {
+      return null;
+    }
+    seen.add(unwrapped.name);
+    return resolveCall(declarations.get(unwrapped.name) ?? null, seen);
+  };
+  const defaultCall = resolveCall(defaultExpression);
+  const ranges = [];
+  for (const fileExport of fileExports) {
+    const call = fileExport.name === PLAY_DEFAULT_EXPORT ? defaultCall : resolveCall(
+      declarations.get(namedExports.get(fileExport.name) ?? "") ?? null
+    );
+    if (call && typeof call.start === "number" && typeof call.end === "number") {
+      ranges.push({
+        exportName: fileExport.name,
+        start: call.start,
+        end: call.end
+      });
+    }
+  }
+  return ranges;
+}
+function projectRecordedArms(block, errors) {
+  const declaredBy = /* @__PURE__ */ new Map();
+  for (const binding of block.bindings) {
+    if (!binding.arm) continue;
+    const incoming = block.edges.filter(
+      (edge2) => edge2.to === binding.nodeId && block.nodes.get(edge2.from)?.kind === "decision"
+    );
+    if (incoming.length === 0) {
+      errors.push(
+        `Docflow annotation "${binding.nodeId}" declares arm:"${binding.arm}" but no decision points at it. Put arm:"\u2026" on the node a decision's labelled edge leads to.`
+      );
+      continue;
+    }
+    if (incoming.length > 1) {
+      errors.push(
+        `Docflow annotation "${binding.nodeId}" declares arm:"${binding.arm}" but ${incoming.length} decisions point at it, so the arm names no single edge. Give each decision its own arm node.`
+      );
+      continue;
+    }
+    const edge = incoming[0];
+    const key = `${edge.from}\0${binding.arm}`;
+    const already = declaredBy.get(key);
+    if (already !== void 0) {
+      errors.push(
+        `Decision "${edge.from}" has two arms declaring arm:"${binding.arm}" ("${already}" and "${binding.nodeId}"). A conditional has one run arm and one else arm.`
+      );
+      continue;
+    }
+    declaredBy.set(key, binding.nodeId);
+    edge.arm = binding.arm;
+  }
+}
+function attachBindingsToBlocks(sourceCode, blocks, bindings, errors) {
+  const lineStarts = sourceLineStartsForDocflow(sourceCode);
+  const exportRanges = playExportSourceRanges(sourceCode);
+  for (const binding of bindings) {
+    let owners = blocks.filter((block) => block.nodes.has(binding.nodeId));
+    if (owners.length === 0) {
+      errors.push(
+        `Docflow annotation "${binding.nodeId}" does not name a graph node.`
+      );
+      continue;
+    }
+    if (owners.length > 1) {
+      const lineStart = lineStarts[binding.line - 1];
+      if (lineStart !== void 0) {
+        const scoped = owners.filter(
+          (owner2) => exportRanges.some(
+            (range) => range.exportName === owner2.exportName && lineStart >= range.start && lineStart < range.end
+          )
+        );
+        if (scoped.length === 1) owners = scoped;
+      }
+    }
+    if (owners.length > 1) {
+      errors.push(
+        `Docflow annotation "${binding.nodeId}" names a node in ${owners.map((owner2) => `\`${blockLabel(owner2)}\``).join(" and ")}, and its enclosing play could not identify one owner. Put the annotation inside the definePlay handler for the export it describes.`
+      );
+      continue;
+    }
+    const owner = owners[0];
+    if (owner.bindings.some((candidate) => candidate.nodeId === binding.nodeId)) {
+      errors.push(
+        `Docflow node "${binding.nodeId}" has more than one code binding.`
+      );
+      continue;
+    }
+    owner.bindings.push(binding);
+  }
+  for (const block of blocks) {
+    for (const binding of block.bindings) {
+      const node = block.nodes.get(binding.nodeId);
+      if (binding.label) node.label = binding.label;
+      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.`
+        );
+      }
+    }
+  }
+}
+function sourceLineStartsForDocflow(sourceCode) {
+  const starts = [0];
+  for (let index = 0; index < sourceCode.length; index += 1) {
+    if (sourceCode[index] === "\n") starts.push(index + 1);
+  }
+  return starts;
+}
+function parseDocflowBindings(sourceCode, errors) {
+  const lines = sourceCode.split(/\r?\n/);
+  const bindings = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    PUT.lastIndex = 0;
+    MERMAID_NODE.lastIndex = 0;
+    const legacyMatch = PUT.exec(lines[index]);
+    const mermaidMatch = MERMAID_NODE.exec(lines[index]);
+    if (!legacyMatch && !mermaidMatch) continue;
+    const attributes = parseAttributes(
+      mermaidMatch ? mermaidMatch[2] ?? "" : legacyMatch[1],
+      {
+        line: index + 1,
+        annotation: mermaidMatch ? "@mermaid-node" : "put",
+        errors
+      }
+    );
+    if (!attributes) continue;
+    const id = (mermaidMatch ? mermaidMatch[1] : attributes.id)?.trim();
+    if (!id) {
+      errors.push(`Docflow annotation on line ${index + 1} requires id:"\u2026".`);
+      continue;
+    }
+    const kind = nodeKind(attributes.type);
+    if (attributes.type && !kind) {
+      errors.push(
+        `Docflow annotation "${id}" has unsupported type "${attributes.type}". Valid types: ${PLAY_DOCFLOW_NODE_KINDS.map((nodeType) => `"${nodeType}"`).join(", ")}.`
+      );
+      continue;
+    }
+    const arm = nodeArm(attributes.arm);
+    if (attributes.arm && !arm) {
+      errors.push(
+        `Docflow annotation "${id}" has unsupported arm "${attributes.arm}". Valid arms: ${PLAY_DOCFLOW_ARMS.map((token) => `"${token}"`).join(", ")}. The arm names which side of the conditional this node is, not what the edge is labelled.`
+      );
+      continue;
+    }
+    let nextLine = index + 1;
+    while (nextLine < lines.length && (!lines[nextLine].trim() || lines[nextLine].trim().startsWith("//")))
+      nextLine += 1;
+    if (nextLine === lines.length) {
+      errors.push(
+        `Docflow annotation "${id}" must be followed by executable code.`
+      );
+      continue;
+    }
+    const inputs = parseContractPaths(
+      attributes.in,
+      "in",
+      id,
+      index + 1,
+      errors
+    );
+    const outputs = parseContractPaths(
+      attributes.out,
+      "out",
+      id,
+      index + 1,
+      errors
+    );
+    if (attributes.in !== void 0 && !inputs || attributes.out !== void 0 && !outputs) {
+      continue;
+    }
+    const inferred = inputs || outputs ? {
+      ...inputs ? { inputs } : {},
+      ...outputs ? { outputs } : {},
+      ioConfidence: "explicit"
+    } : inferBindingIo(lines[nextLine]);
+    bindings.push({
+      nodeId: id,
+      line: nextLine + 1,
+      ...attributes.label ? { label: attributes.label } : {},
+      ...kind ? { kind } : {},
+      // Spread, never `arm: arm ?? undefined` — see `PlayDocflowEdge.arm`. An
+      // explicit `undefined` key survives `JSON.stringify` round-trips in some
+      // callers and would reintroduce the hash drift this omission avoids.
+      ...arm ? { arm } : {},
+      ...inferred
+    });
+  }
+  return bindings;
+}
+
+// ../shared_libs/plays/docflow-binding.ts
+function sourceLineStarts(sourceCode) {
+  const starts = [0];
+  for (let index = 0; index < sourceCode.length; index += 1) {
+    if (sourceCode[index] === "\n") starts.push(index + 1);
+  }
+  return starts;
+}
+function astNodeBounds(node) {
+  return typeof node.start === "number" && typeof node.end === "number" ? { start: node.start, end: node.end } : null;
+}
+function findDocflowBoundStatement(ast, line, lineStarts) {
+  const lineStart = lineStarts[line - 1];
+  const lineEnd = lineStarts[line] ?? Number.POSITIVE_INFINITY;
+  if (lineStart === void 0) return null;
+  let match = null;
+  const pending = [ast];
+  const statementTypes = /* @__PURE__ */ new Set([
+    "ExpressionStatement",
+    "IfStatement",
+    "ReturnStatement",
+    "ThrowStatement",
+    "VariableDeclaration"
+  ]);
+  while (pending.length > 0) {
+    const node = pending.pop();
+    const bounds = astNodeBounds(node);
+    if (bounds && bounds.start < lineEnd && bounds.end > lineStart && statementTypes.has(node.type)) {
+      if (!match || bounds.end - bounds.start < (astNodeBounds(match)?.end ?? 0) - (astNodeBounds(match)?.start ?? 0)) {
+        match = node;
+      }
+    }
+    for (const child of Object.values(node)) {
+      if (Array.isArray(child)) pending.push(...child.filter(isAstNode));
+      else if (isAstNode(child)) pending.push(child);
+    }
+  }
+  return match;
+}
+var DOCFLOW_STATEMENT_TYPES = /* @__PURE__ */ new Set([
+  "ExpressionStatement",
+  "IfStatement",
+  "ReturnStatement",
+  "ThrowStatement",
+  "VariableDeclaration"
+]);
+function docflowOutputRoot(binding) {
+  const first = binding.outputs?.[0];
+  if (!first) return null;
+  const root = first.split(".")[0];
+  if (!root || root === "$output") return null;
+  return root;
+}
+function buildDocflowParentIndex(ast) {
+  const parents = /* @__PURE__ */ new Map();
+  const pending = [ast];
+  while (pending.length > 0) {
+    const node = pending.pop();
+    for (const child of Object.values(node)) {
+      const children = Array.isArray(child) ? child.filter(isAstNode) : isAstNode(child) ? [child] : [];
+      for (const nested of children) {
+        parents.set(nested, node);
+        pending.push(nested);
+      }
+    }
+  }
+  return parents;
+}
+function enclosingDocflowStatement(node, parents) {
+  let current = node;
+  while (current) {
+    if (DOCFLOW_STATEMENT_TYPES.has(current.type)) return current;
+    current = parents.get(current) ?? null;
+  }
+  return null;
+}
+function isWithColumnCallForName(node, columnName) {
+  if (node.type !== "CallExpression") return false;
+  const callee = isAstNode(node.callee) ? node.callee : null;
+  if (!callee || callee.type !== "MemberExpression" || callee.computed || !isAstNode(callee.property) || callee.property.type !== "Identifier" || callee.property.name !== "withColumn") {
+    return false;
+  }
+  const firstArg = astArray(node.arguments)[0];
+  return Boolean(
+    firstArg && firstArg.type === "Literal" && typeof firstArg.value === "string" && firstArg.value === columnName
+  );
+}
+function isDocflowStepCallForName(node, stepName) {
+  if (node.type !== "CallExpression") return false;
+  const callee = isAstNode(node.callee) ? node.callee : null;
+  if (!callee || callee.type !== "MemberExpression" || callee.computed || !isAstNode(callee.property) || callee.property.type !== "Identifier" || callee.property.name !== "step") {
+    return false;
+  }
+  const firstArg = astArray(node.arguments)[0];
+  return Boolean(
+    firstArg && firstArg.type === "Literal" && typeof firstArg.value === "string" && firstArg.value === stepName
+  );
+}
+function docflowExpressionWrapsStepBuilder(expression, stepName) {
+  const unwrapped = expression.type === "AwaitExpression" && isAstNode(expression.argument) ? expression.argument : expression;
+  if (isDocflowStepCallForName(unwrapped, stepName)) return false;
+  const pending = [unwrapped];
+  while (pending.length > 0) {
+    const node = pending.pop();
+    if (node !== unwrapped && isDocflowStepCallForName(node, stepName)) {
+      return true;
+    }
+    for (const child of Object.values(node)) {
+      if (Array.isArray(child)) pending.push(...child.filter(isAstNode));
+      else if (isAstNode(child)) pending.push(child);
+    }
+  }
+  return false;
+}
+function getIdentifierName2(node) {
+  return isAstNode(node) && node.type === "Identifier" ? typeof node.name === "string" ? node.name : null : null;
+}
+function enclosingDefinePlayCall(ast, line, lineStarts) {
+  const lineStart = lineStarts[line - 1];
+  const lineEnd = lineStarts[line] ?? Number.POSITIVE_INFINITY;
+  if (lineStart === void 0) return null;
+  let match = null;
+  const pending = [ast];
+  while (pending.length > 0) {
+    const node = pending.pop();
+    const bounds = astNodeBounds(node);
+    if (bounds && bounds.start < lineEnd && bounds.end > lineStart && isDefinePlayCall(node)) {
+      const matchBounds = match ? astNodeBounds(match) : null;
+      if (!match || !matchBounds || bounds.end - bounds.start < matchBounds.end - matchBounds.start) {
+        match = node;
+      }
+    }
+    for (const child of Object.values(node)) {
+      if (Array.isArray(child)) pending.push(...child.filter(isAstNode));
+      else if (isAstNode(child)) pending.push(child);
+    }
+  }
+  return match;
+}
+function isVariableDeclarationForName(node, name) {
+  if (node.type !== "VariableDeclaration") return false;
+  return astArray(node.declarations).some(
+    (declarator) => getIdentifierName2(declarator.id) === name
+  );
+}
+function resolveDocflowBindingSymbol(ast, binding, lineStarts, parents) {
+  const root = docflowOutputRoot(binding);
+  if (!root) return { kind: "abstain" };
+  const parentIndex = parents ?? buildDocflowParentIndex(ast);
+  const scope = enclosingDefinePlayCall(ast, binding.line, lineStarts) ?? ast;
+  const inScope = (node) => {
+    if (scope === ast) return true;
+    const bounds = astNodeBounds(node);
+    const scopeBounds = astNodeBounds(scope);
+    return Boolean(
+      bounds && scopeBounds && bounds.start >= scopeBounds.start && bounds.end <= scopeBounds.end
+    );
+  };
+  const matchesColumn = (node) => isWithColumnCallForName(node, root) && inScope(node);
+  const matchesStep = (node) => isDocflowStepCallForName(node, root) && inScope(node);
+  const matchesVariable = (node) => isVariableDeclarationForName(node, root) && inScope(node);
+  const collectStatements = (predicate) => {
+    const statements = /* @__PURE__ */ new Map();
+    const pending = [scope];
+    while (pending.length > 0) {
+      const node = pending.pop();
+      if (predicate(node)) {
+        const statement = enclosingDocflowStatement(node, parentIndex);
+        const kind = matchesColumn(node) ? "declaredColumn" : matchesStep(node) ? "declaredStep" : "variable";
+        if (statement && (!statements.has(statement) || kind === "declaredColumn")) {
+          statements.set(statement, kind);
+        }
+      }
+      for (const child of Object.values(node)) {
+        if (Array.isArray(child)) pending.push(...child.filter(isAstNode));
+        else if (isAstNode(child)) pending.push(child);
+      }
+    }
+    return statements;
+  };
+  let candidates = collectStatements(
+    (node) => matchesColumn(node) || matchesStep(node)
+  );
+  if (candidates.size === 0) candidates = collectStatements(matchesVariable);
+  if (candidates.size === 0) return { kind: "abstain" };
+  const resolved = (statement) => ({
+    kind: "resolved",
+    statement,
+    symbolKind: candidates.get(statement) ?? "variable"
+  });
+  const lineStart = lineStarts[binding.line - 1];
+  const lineEnd = lineStarts[binding.line] ?? Number.POSITIVE_INFINITY;
+  if (lineStart !== void 0) {
+    const containing = [...candidates.keys()].filter((statement) => {
+      const bounds = astNodeBounds(statement);
+      return bounds && bounds.start < lineEnd && bounds.end > lineStart;
+    });
+    if (containing.length === 1) return resolved(containing[0]);
+    if (containing.length > 1) {
+      return { kind: "ambiguous", candidates: containing };
+    }
+  }
+  if (candidates.size === 1) {
+    return resolved([...candidates.keys()][0]);
+  }
+  return { kind: "ambiguous", candidates: [...candidates.keys()] };
+}
+function statementLine(statement, lineStarts) {
+  const bounds = statement ? astNodeBounds(statement) : null;
+  if (!bounds) return null;
+  let line = 1;
+  for (let index = 0; index < lineStarts.length; index += 1) {
+    if (lineStarts[index] > bounds.start) break;
+    line = index + 1;
+  }
+  return line;
+}
+function resolveDocflowBinding(ast, binding, lineStarts, parents) {
+  const positional = findDocflowBoundStatement(ast, binding.line, lineStarts);
+  const symbol = resolveDocflowBindingSymbol(ast, binding, lineStarts, parents);
+  const root = docflowOutputRoot(binding);
+  if (symbol.kind === "ambiguous") {
+    return {
+      binding,
+      statement: positional,
+      symbolKind: null,
+      drift: {
+        binding,
+        symbol: root ?? "",
+        annotatedLine: statementLine(positional, lineStarts),
+        symbolLine: statementLine(symbol.candidates[0] ?? null, lineStarts),
+        ambiguous: true
+      }
+    };
+  }
+  if (symbol.kind === "resolved") {
+    const drift = positional && positional !== symbol.statement ? {
+      binding,
+      symbol: root ?? "",
+      annotatedLine: statementLine(positional, lineStarts),
+      symbolLine: statementLine(symbol.statement, lineStarts),
+      ambiguous: false
+    } : null;
+    return {
+      binding,
+      statement: symbol.statement,
+      symbolKind: symbol.symbolKind,
+      drift
+    };
+  }
+  return { binding, statement: positional, symbolKind: null, drift: null };
+}
+
 // ../shared_libs/plays/secret-guardrails.ts
 var SECRET_ENV_PATTERN = /\bprocess(?:\.env|\[['"]env['"]\])(?:\.|\[['"])([A-Z0-9_]*(?:API[_-]?KEY|TOKEN|SECRET|PASSWORD|PRIVATE[_-]?KEY|ACCESS[_-]?KEY)[A-Z0-9_]*)(?:['"]\])?/g;
 var PRIVATE_KEY_PATTERN = /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/;
@@ -4029,7 +5161,7 @@ function validatePlaySourceFilesHaveNoInlineSecrets(sourceFiles) {
 var MAX_PLAY_BUNDLE_BYTES = 30 * 1024 * 1024;
 
 // ../shared_libs/plays/bundling/index.ts
-var PLAY_BUNDLE_CACHE_VERSION = 28;
+var PLAY_BUNDLE_CACHE_VERSION = 33;
 var PLAY_ARTIFACT_CACHE_DIR = join(
   tmpdir(),
   `deepline-play-artifacts-v${PLAY_BUNDLE_CACHE_VERSION}`
@@ -4188,15 +5320,6 @@ function findSourceImportReferences(sourceCode) {
 function extractDefinedPlayName(sourceCode) {
   return extractDefinedPlayMetadata(sourceCode, null)?.name ?? null;
 }
-var TypeScriptParser = Parser.extend(
-  tsPlugin({
-    allowSatisfies: true,
-    jsx: {
-      allowNamespaces: true,
-      allowNamespacedObjects: true
-    }
-  })
-);
 function parsePlaySourceAst(sourceCode) {
   try {
     return TypeScriptParser.parse(sourceCode, {
@@ -4213,7 +5336,7 @@ function parsePlaySourceAst(sourceCode) {
         legalComments: "none",
         sourcemap: false
       }).code;
-      return Parser.parse(transformed, {
+      return Parser2.parse(transformed, {
         ecmaVersion: "latest",
         sourceType: "module",
         allowHashBang: true
@@ -4223,17 +5346,11 @@ function parsePlaySourceAst(sourceCode) {
     }
   }
 }
-function getIdentifierName(node) {
+function getIdentifierName3(node) {
   return isAstNode(node) && node.type === "Identifier" ? typeof node.name === "string" ? node.name : null : null;
 }
-function isAstNode(value) {
-  return value !== null && typeof value === "object" && "type" in value;
-}
-function astArray(value) {
-  return Array.isArray(value) ? value.filter(isAstNode) : [];
-}
 function memberExpressionPath(node) {
-  const expression = unwrapStaticExpression(node);
+  const expression = unwrapStaticExpression2(node);
   if (!expression) return null;
   if (expression.type === "Identifier" && typeof expression.name === "string") {
     return [expression.name];
@@ -4291,7 +5408,7 @@ function buildPlayMetadataContext(ast) {
   for (const statement of astArray(ast.body)) {
     if (statement.type === "VariableDeclaration") {
       for (const declaration of astArray(statement.declarations)) {
-        const name = getIdentifierName(declaration.id);
+        const name = getIdentifierName3(declaration.id);
         if (!name) continue;
         const initializer = isAstNode(declaration.init) ? declaration.init : null;
         declarations.set(
@@ -4314,7 +5431,7 @@ function buildPlayMetadataContext(ast) {
         for (const declaration of astArray(
           statement.declaration.declarations
         )) {
-          const name = getIdentifierName(declaration.id);
+          const name = getIdentifierName3(declaration.id);
           if (!name) continue;
           const initializer = isAstNode(declaration.init) ? declaration.init : null;
           declarations.set(
@@ -4328,8 +5445,8 @@ function buildPlayMetadataContext(ast) {
         }
       }
       for (const specifier of astArray(statement.specifiers)) {
-        const localName = getIdentifierName(specifier.local);
-        const exportedName = getIdentifierName(specifier.exported) ?? (isAstNode(specifier.exported) && specifier.exported.type === "Literal" && typeof specifier.exported.value === "string" ? specifier.exported.value : null);
+        const localName = getIdentifierName3(specifier.local);
+        const exportedName = getIdentifierName3(specifier.exported) ?? (isAstNode(specifier.exported) && specifier.exported.type === "Literal" && typeof specifier.exported.value === "string" ? specifier.exported.value : null);
         if (localName && exportedName) {
           namedExports.set(exportedName, localName);
         }
@@ -4346,7 +5463,7 @@ function buildPlayMetadataContext(ast) {
   }
   return { declarations, namedExports, commonJsExports, defaultExport };
 }
-function unwrapStaticExpression(node) {
+function unwrapStaticExpression2(node) {
   let current = node ?? null;
   while (current && (current.type === "TSAsExpression" || current.type === "TSSatisfiesExpression" || current.type === "TSTypeAssertion" || current.type === "TSNonNullExpression" || current.type === "ParenthesizedExpression")) {
     current = isAstNode(current.expression) ? current.expression : null;
@@ -4354,7 +5471,7 @@ function unwrapStaticExpression(node) {
   return current;
 }
 function staticStringFromExpression(node, context, seen = /* @__PURE__ */ new Set(), trimResult = true) {
-  const expression = unwrapStaticExpression(node);
+  const expression = unwrapStaticExpression2(node);
   if (!expression) return null;
   if (expression.type === "Literal") {
     const value = expression.value;
@@ -4384,7 +5501,7 @@ function staticStringFromExpression(node, context, seen = /* @__PURE__ */ new Se
     if (!value?.trim()) return null;
     return trimResult ? value.trim() : value;
   }
-  const identifier = getIdentifierName(expression);
+  const identifier = getIdentifierName3(expression);
   if (!identifier || seen.has(identifier)) return null;
   seen.add(identifier);
   return staticStringFromExpression(
@@ -4409,10 +5526,10 @@ function propertyNameFromKey(property) {
   return null;
 }
 function objectExpressionFromNode(node, context, seen = /* @__PURE__ */ new Set()) {
-  const expression = unwrapStaticExpression(node);
+  const expression = unwrapStaticExpression2(node);
   if (!expression) return null;
   if (expression.type === "ObjectExpression") return expression;
-  const identifier = getIdentifierName(expression);
+  const identifier = getIdentifierName3(expression);
   if (!identifier || seen.has(identifier)) return null;
   seen.add(identifier);
   return objectExpressionFromNode(
@@ -4479,12 +5596,12 @@ function staticPropertyNames(node, context, ancestors = /* @__PURE__ */ new Set(
   return names;
 }
 function staticNumberFromExpression(node, context, seen = /* @__PURE__ */ new Set()) {
-  const expression = unwrapStaticExpression(node);
+  const expression = unwrapStaticExpression2(node);
   if (!expression) return null;
   if (expression.type === "Literal" && typeof expression.value === "number") {
     return expression.value;
   }
-  const identifier = getIdentifierName(expression);
+  const identifier = getIdentifierName3(expression);
   if (!identifier || seen.has(identifier)) return null;
   seen.add(identifier);
   return staticNumberFromExpression(
@@ -4573,7 +5690,7 @@ function stringPropertyFromObjectExpression(node, propertyName, context, seenObj
   return value;
 }
 function isDefinePlayCallee(node) {
-  const callee = unwrapStaticExpression(node);
+  const callee = unwrapStaticExpression2(node);
   if (!callee) return false;
   if (callee.type === "Identifier" && (callee.name === "definePlay" || callee.name === "defineWorkflow")) {
     return true;
@@ -4585,7 +5702,7 @@ function isDefinePlayCallee(node) {
   return false;
 }
 function playMetadataFromDefinePlayCall(node, context) {
-  const expression = unwrapStaticExpression(node);
+  const expression = unwrapStaticExpression2(node);
   if (!expression || expression.type !== "CallExpression" || !isDefinePlayCallee(isAstNode(expression.callee) ? expression.callee : null)) {
     return null;
   }
@@ -4631,13 +5748,13 @@ function resolveExportExpression(exportName, context) {
   if (exportName === "default") {
     const commonJsDefault = context.commonJsExports.get("default");
     if (commonJsDefault) {
-      const commonJsDefaultIdentifier = getIdentifierName(
-        unwrapStaticExpression(commonJsDefault)
+      const commonJsDefaultIdentifier = getIdentifierName3(
+        unwrapStaticExpression2(commonJsDefault)
       );
       return commonJsDefaultIdentifier ? context.declarations.get(commonJsDefaultIdentifier) ?? commonJsDefault : commonJsDefault;
     }
-    const defaultExpression = unwrapStaticExpression(context.defaultExport);
-    const defaultIdentifier = getIdentifierName(defaultExpression);
+    const defaultExpression = unwrapStaticExpression2(context.defaultExport);
+    const defaultIdentifier = getIdentifierName3(defaultExpression);
     if (!defaultIdentifier) {
       const defaultExportName = context.namedExports.get("default");
       return defaultExportName ? context.declarations.get(defaultExportName) ?? null : defaultExpression;
@@ -4647,8 +5764,8 @@ function resolveExportExpression(exportName, context) {
   if (exportName) {
     const commonJsExport = context.commonJsExports.get(exportName);
     if (commonJsExport) {
-      const commonJsExportIdentifier = getIdentifierName(
-        unwrapStaticExpression(commonJsExport)
+      const commonJsExportIdentifier = getIdentifierName3(
+        unwrapStaticExpression2(commonJsExport)
       );
       return commonJsExportIdentifier ? context.declarations.get(commonJsExportIdentifier) ?? commonJsExport : commonJsExport;
     }
@@ -4674,7 +5791,7 @@ function extractDefinedPlayMetadata(sourceCode, exportName) {
       context
     );
     if (directDefaultMetadata) return directDefaultMetadata;
-    const defaultIdentifier = getIdentifierName(context.defaultExport);
+    const defaultIdentifier = getIdentifierName3(context.defaultExport);
     if (defaultIdentifier) {
       const defaultMetadata = playMetadataFromDefinePlayCall(
         context.declarations.get(defaultIdentifier),
@@ -4765,6 +5882,201 @@ function localSdkAliasPlugin(adapter) {
     }
   };
 }
+function sourceLoaderForPath(path) {
+  const extension = extname(path).toLowerCase();
+  if (extension === ".tsx") return "tsx";
+  if (extension === ".jsx") return "jsx";
+  if (extension === ".js" || extension === ".mjs" || extension === ".cjs") {
+    return "js";
+  }
+  return "ts";
+}
+function docflowContextIdentifierFromCall(call) {
+  if (!isDefinePlayCallExpression(call)) return null;
+  const args = astArray(call.arguments);
+  const callback = args.find(
+    (argument) => argument.type === "ArrowFunctionExpression" || argument.type === "FunctionExpression"
+  );
+  if (!callback) return null;
+  return getIdentifierName3(astArray(callback.params)[0]);
+}
+function findDocflowContextIdentifier(input) {
+  let owner = input.statement;
+  while (owner) {
+    const contextName = docflowContextIdentifierFromCall(owner);
+    if (contextName) return contextName;
+    owner = input.parents.get(owner) ?? null;
+  }
+  const lineStart = input.lineStarts[input.bindingLine - 1];
+  const lineEnd = input.lineStarts[input.bindingLine] ?? Number.POSITIVE_INFINITY;
+  if (lineStart === void 0) return null;
+  let best = null;
+  const pending = [input.ast];
+  while (pending.length > 0) {
+    const value = pending.pop();
+    if (!isAstNode(value)) continue;
+    if (isDefinePlayCallExpression(value)) {
+      const bounds = astNodeBounds(value);
+      if (bounds && bounds.start < lineEnd && bounds.end > lineStart && (!best || bounds.end - bounds.start < (astNodeBounds(best)?.end ?? 0) - (astNodeBounds(best)?.start ?? 0))) {
+        best = value;
+      }
+    }
+    for (const child of Object.values(value)) {
+      if (Array.isArray(child)) pending.push(...child);
+      else if (isAstNode(child)) pending.push(child);
+    }
+  }
+  return best ? docflowContextIdentifierFromCall(best) : null;
+}
+function docflowInputCaptureSource(paths) {
+  return `[${paths.map((path) => {
+    const [root, ...properties] = path.split(".");
+    return `{path:${JSON.stringify(path)},readRoot:()=>${root},properties:${JSON.stringify(properties)}}`;
+  }).join(",")}]`;
+}
+function docflowObservationTarget(statement) {
+  if (!statement) return null;
+  let expression = null;
+  if (statement.type === "VariableDeclaration") {
+    const declarations = astArray(statement.declarations);
+    if (declarations.length === 1 && isAstNode(declarations[0].init)) {
+      expression = declarations[0].init;
+    }
+  } else if (statement.type === "ReturnStatement" && isAstNode(statement.argument)) {
+    expression = statement.argument;
+  } else if (statement.type === "ExpressionStatement" && isAstNode(statement.expression)) {
+    expression = statement.expression;
+  } else if (statement.type === "IfStatement" && isAstNode(statement.test)) {
+    expression = statement.test;
+  }
+  if (!expression) return null;
+  const bounds = astNodeBounds(expression);
+  if (!bounds) return null;
+  return {
+    ...bounds,
+    awaitsResult: expressionContainsTopLevelAwait(expression),
+    expression
+  };
+}
+function docflowObservedExpression(input) {
+  const callback = input.awaitsResult ? `async()=>(${input.expression})` : `()=>(${input.expression})`;
+  const observation = `${input.contextName}.__deeplineObserveDocflowNode(${JSON.stringify(input.nodeId)},${docflowInputCaptureSource(input.inputs)},${JSON.stringify(input.outputs)},${callback})`;
+  return input.awaitsResult ? `await ${observation}` : observation;
+}
+function expressionContainsTopLevelAwait(expression) {
+  const pending = [expression];
+  while (pending.length > 0) {
+    const node = pending.pop();
+    if (node.type === "AwaitExpression") return true;
+    if (node !== expression && (node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression" || node.type === "FunctionDeclaration")) {
+      continue;
+    }
+    for (const child of Object.values(node)) {
+      if (Array.isArray(child)) pending.push(...child.filter(isAstNode));
+      else if (isAstNode(child)) pending.push(child);
+    }
+  }
+  return false;
+}
+function instrumentPlayDocflowRuntimeHits(sourceCode) {
+  const parsed = parsePlayDocflowFile(sourceCode);
+  if (parsed.blocks.length === 0 || parsed.errors.length > 0) return sourceCode;
+  const ast = parsePlaySourceAst(sourceCode);
+  if (!ast) return sourceCode;
+  const lineStarts = sourceLineStarts(sourceCode);
+  const replacements = [];
+  const targets = [];
+  const parents = buildDocflowParentIndex(ast);
+  for (const binding of parsed.bindings) {
+    const resolution = resolveDocflowBinding(ast, binding, lineStarts, parents);
+    const contextName = findDocflowContextIdentifier({
+      ast,
+      statement: resolution.statement,
+      bindingLine: binding.line,
+      lineStarts,
+      parents
+    });
+    if (!contextName) continue;
+    const target = docflowObservationTarget(resolution.statement);
+    const observedRoot = docflowOutputRoot(binding);
+    if (target && observedRoot && docflowExpressionWrapsStepBuilder(target.expression, observedRoot)) {
+      continue;
+    }
+    if (target) {
+      targets.push({ ...target, contextName, binding });
+      continue;
+    }
+    const lineStart = lineStarts[binding.line - 1];
+    if (lineStart !== void 0) {
+      const indentationLength = /^\s*/.exec(sourceCode.slice(lineStart))?.[0].length ?? 0;
+      replacements.push({
+        start: lineStart + indentationLength,
+        end: lineStart + indentationLength,
+        value: `await ${contextName}.__deeplineDocflowHit(${JSON.stringify(binding.nodeId)}); `
+      });
+    }
+  }
+  targets.sort(
+    (left, right) => left.start - right.start || right.end - left.end
+  );
+  const groups = [];
+  for (const target of targets) {
+    const open = groups[groups.length - 1];
+    if (open && target.start < open.end) {
+      open.bindings.push(target.binding);
+    } else {
+      groups.push({
+        start: target.start,
+        end: target.end,
+        awaitsResult: target.awaitsResult,
+        contextName: target.contextName,
+        bindings: [target.binding]
+      });
+    }
+  }
+  for (const group of groups) {
+    let expression = sourceCode.slice(group.start, group.end);
+    for (const binding of [...group.bindings].reverse()) {
+      expression = docflowObservedExpression({
+        contextName: group.contextName,
+        nodeId: binding.nodeId,
+        inputs: binding.inputs ?? [],
+        outputs: binding.outputs ?? [],
+        expression,
+        awaitsResult: group.awaitsResult
+      });
+    }
+    replacements.push({
+      start: group.start,
+      end: group.end,
+      value: expression
+    });
+  }
+  return replacements.sort((left, right) => right.start - left.start).reduce(
+    (source, replacement) => `${source.slice(0, replacement.start)}${replacement.value}${source.slice(replacement.end)}`,
+    sourceCode
+  );
+}
+function docflowRuntimeInstrumentationPlugin(customerSourceFilePaths) {
+  const customerSourceFiles = new Set(
+    customerSourceFilePaths.filter((path) => extname(path).toLowerCase() !== ".json").map((path) => resolve(path))
+  );
+  return {
+    name: "deepline-docflow-runtime-instrumentation",
+    setup(buildContext) {
+      buildContext.onLoad({ filter: /./ }, (args) => {
+        if (!customerSourceFiles.has(resolve(args.path))) return void 0;
+        return {
+          contents: instrumentPlayDocflowRuntimeHits(
+            readFileSync(args.path, "utf8")
+          ),
+          loader: sourceLoaderForPath(args.path),
+          resolveDir: dirname(args.path)
+        };
+      });
+    }
+  };
+}
 function buildImportedPlayProxyModule(playName) {
   const serializedName = JSON.stringify(playName);
   return `
@@ -5102,9 +6414,13 @@ function getBundleSizeError(filePath, bundledCode, artifactKind) {
     artifactKind
   );
 }
-async function runEsbuildForCjsNode(entryFile, _customerSourceFilePaths, importedPlayDependencies, adapter, exportName) {
+async function runEsbuildForCjsNode(entryFile, customerSourceFilePaths, importedPlayDependencies, adapter, exportName) {
   const sdkAliasPlugin = localSdkAliasPlugin(adapter);
   const playProxyPlugin = importedPlayProxyPlugin(importedPlayDependencies);
+  const docflowPlugin = docflowRuntimeInstrumentationPlugin([
+    entryFile,
+    ...customerSourceFilePaths
+  ]);
   const namedExportShim = exportName === "default" ? null : `export { ${exportName} as default } from ${JSON.stringify(entryFile)};
 `;
   const result = await build({
@@ -5128,7 +6444,7 @@ async function runEsbuildForCjsNode(entryFile, _customerSourceFilePaths, importe
     sourcesContent: false,
     logLevel: "silent",
     legalComments: "none",
-    plugins: [sdkAliasPlugin, playProxyPlugin].filter(
+    plugins: [docflowPlugin, sdkAliasPlugin, playProxyPlugin].filter(
       (plugin) => plugin != null
     )
   });
@@ -5718,7 +7034,7 @@ async function discoverPackagedLocalFiles(entryFile) {
 }
 
 // src/plays/bundle-play-file.ts
-var PLAY_BUNDLE_CACHE_VERSION2 = 31;
+var PLAY_BUNDLE_CACHE_VERSION2 = 33;
 var MODULE_DIR = dirname3(fileURLToPath(import.meta.url));
 var SDK_PACKAGE_ROOT = resolve3(MODULE_DIR, "..", "..");
 var SOURCE_REPO_ROOT = resolve3(SDK_PACKAGE_ROOT, "..");