@dypai-ai/mcp 1.4.3 → 1.4.5

package/src/tools/sync/validate.js

@@ -188,6 +188,25 @@ function extractPlaceholders(s) {
   return out
 }
 
+/**
+ * Extract the first identifier (a-z, A-Z, _, 0-9 — JS-ident shape) from the
+ * head of an expression, ignoring any trailing template filter or coalesce
+ * operator. Examples:
+ *   "input.limit | default(100)"  → "input.limit"
+ *   "input.page ?? 1"              → "input.page"
+ *   "nodes.foo.bar || 'x'"         → "nodes.foo.bar"
+ *   "current_user_id | trim"       → "current_user_id"
+ * Returns the trimmed/cleaned head (NOT just the leaf identifier — keeps
+ * dotted paths intact so callers that split on '.' still work).
+ */
+function stripExprTail(expr) {
+  // Cut at the first character that can't be part of a path/identifier:
+  // whitespace, pipe (jinja-style filter), `?`, or `|`. Bracket access
+  // (e.g. items[0]) is preserved — callers split on '[' if they need to.
+  const m = /^[\s]*([A-Za-z_$][A-Za-z_$0-9.\[\]]*)/.exec(expr)
+  return m ? m[1] : expr.trim()
+}
+
 /** Minimal Levenshtein distance, caps at 3 for "did you mean" typo suggestions. */
 function levenshteinSmall(a, b) {
   if (a === b) return 0
@@ -223,12 +242,53 @@ async function readSchemaTables(rootDir) {
 /** Extract referenced table names from a SQL string: `FROM public.X`, `JOIN public.X`, `INTO public.X`, `UPDATE public.X`. */
 function extractSqlTables(sql) {
   const tables = new Set()
-  const re = /(?:FROM|JOIN|INTO|UPDATE)\s+public\.(\w+)/gi
+  if (typeof sql !== "string" || sql.length === 0) return tables
+  // Strip comments and string literals so words inside them are not mistaken
+  // for table refs (e.g. `'JOIN ...'` inside a string column, or `-- FROM x`).
+  const clean = sql
+    .replace(/--[^\n]*/g, " ")
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+    .replace(/'(?:[^']|'')*'/g, "''")
+  // Single regex that captures BOTH a possible schema and the table name,
+  // optionally preceded by `ONLY` (Postgres inheritance modifier). Splitting
+  // schema/table into separate groups makes filtering by schema trivial.
+  //   FROM x | FROM "x" | FROM <schema>.x | FROM "<schema>"."x" | FROM ONLY <schema>.x
+  const re = /(?:FROM|JOIN|INTO|UPDATE)\s+(?:ONLY\s+)?(?:"?([a-zA-Z_]\w*)"?\s*\.\s*)?(?:"([a-zA-Z_]\w*)"|([a-zA-Z_]\w*))/gi
   let m
-  while ((m = re.exec(sql)) !== null) tables.add(m[1])
+  while ((m = re.exec(clean)) !== null) {
+    const schema = m[1]              // undefined if no schema given
+    const tableName = m[2] || m[3]
+    if (!tableName) continue
+    // Skip Postgres modifiers that would accidentally land here as `tableName`
+    // when the regex was greedy enough (defensive — the optional `ONLY` above
+    // already handles the common case).
+    if (SQL_KEYWORDS_AFTER_FROM.has(tableName.toUpperCase())) continue
+    // Only validate tables in the user-managed `public` schema. System
+    // schemas (auth, system, ext, pg_catalog, information_schema) are
+    // managed by the engine and not present in dypai/schema.sql.
+    if (schema && schema.toLowerCase() !== "public") continue
+    tables.add(tableName)
+  }
   return tables
 }
 
+const SQL_KEYWORDS_AFTER_FROM = new Set([
+  "ONLY", "LATERAL", "SELECT", "VALUES", "TABLE",
+])
+
+// Legacy `dypai_database.operation` values that perform writes. New code
+// should use `operation: mutation`, but old YAMLs may still use these and
+// the engine still accepts them.
+const LEGACY_WRITE_OPS = new Set(["insert", "update", "delete", "upsert"])
+
+// Legacy ops whose SQL lives in `node.query` (custom_query, raw select).
+const LEGACY_OPS_THAT_USE_QUERY = new Set(["custom_query", "select"])
+
+// Legacy ops whose target table is in `node.table` (no SQL string).
+const LEGACY_OPS_THAT_USE_TABLE_FIELD = new Set([
+  "select", "insert", "update", "delete", "upsert", "aggregate",
+])
+
 // ─── Rules ──────────────────────────────────────────────────────────────────
 
 function ruleUsesJwt(trigger) {
@@ -259,11 +319,22 @@ function validateEndpoint(entry, ctx) {
   // Collect SQL tables referenced (before checking each individually)
   const referencedTables = new Set()
 
+  // Aggregate missing input.X refs across the whole endpoint so we emit ONE
+  // diagnostic per endpoint instead of N (an endpoint with 11 stray refs
+  // produces 11 near-identical errors otherwise — pure noise). Map keeps
+  // first-seen `loc` for context. Iteration order of Map preserves insertion.
+  const missingInputProps = new Map()  // propName -> { loc, expr }
+  const missingNodeRefs = new Map()    // nodeId  -> { loc, expr } — same idea for ${nodes.X.Y}
+
   for (const { source, loc, value } of sources) {
     // --- Placeholder checks ---
     for (const expr of extractPlaceholders(value)) {
-      // Strip leading/trailing whitespace in the expression
-      const e = expr.trim()
+      // Normalize: trim whitespace AND strip any template tail like
+      // ` | default(100)`, ` ?? 1`, ` || 'x'` — we only care about the
+      // path/identifier head. Without this, `${input.limit | default(100)}`
+      // would be parsed as property name "limit | default(100)" → false
+      // positive `input_placeholder_missing`.
+      const e = stripExprTail(expr)
 
       // ${input.X} or ${input.X.Y}
       // Only validate against the input schema if one is declared; DYPAI allows
@@ -273,13 +344,9 @@ function validateEndpoint(entry, ctx) {
         const first = e.slice(6).split(/[.\[]/)[0]
         const hasSchema = Object.keys(inputProps).length > 0
         if (hasSchema && !inputProps[first]) {
-          diagnostics.push({
-            severity: "error",
-            rule: "input_placeholder_missing",
-            endpoint: name, file, loc,
-            message: `\${${expr}} references input.${first}, but the endpoint's input schema has no '${first}' property.`,
-            fix_hint: `Valid properties: ${Object.keys(inputProps).join(", ")}`,
-          })
+          if (!missingInputProps.has(first)) {
+            missingInputProps.set(first, { loc, expr })
+          }
         } else if (!hasSchema) {
           // One warning per endpoint max — accumulate in a set
           ctx.schemaless ??= new Set()
@@ -300,15 +367,9 @@ function validateEndpoint(entry, ctx) {
       else if (e.startsWith("nodes.")) {
         const nodeId = e.slice(6).split(/[.\[]/)[0]
         if (!nodeIds.has(nodeId)) {
-          diagnostics.push({
-            severity: "error",
-            rule: "node_ref_missing",
-            endpoint: name, file, loc,
-            message: `\${${expr}} references node '${nodeId}' but that node is not declared in this workflow.`,
-            fix_hint: nodeIds.size
-              ? `Known nodes: ${[...nodeIds].join(", ")}`
-              : "This endpoint has no nodes yet.",
-          })
+          if (!missingNodeRefs.has(nodeId)) {
+            missingNodeRefs.set(nodeId, { loc, expr })
+          }
         }
       }
 
@@ -326,16 +387,73 @@ function validateEndpoint(entry, ctx) {
       }
     }
 
-    // --- SQL: collect referenced tables for later comparison against schema.sql ---
-    // Heuristic: look like SQL (contains SELECT/INSERT/UPDATE/DELETE/WITH)
-    if (/\b(SELECT|INSERT|UPDATE|DELETE|WITH)\b/i.test(value)) {
-      for (const t of extractSqlTables(value)) referencedTables.add(t)
+    // NOTE: SQL table extraction used to live here (anywhere a string looked
+    // like SQL). That generated false positives whenever a prompt, comment,
+    // or label happened to contain words like "INSERT" or "SELECT". Table
+    // extraction is now done ONLY inside the per-node loop below, restricted
+    // to dypai_database nodes' actual SQL fields. See the dedicated block.
+  }
+
+  // --- Emit aggregated input_placeholder_missing (one diag per endpoint) ---
+  // Single agg ergonomically beats N near-identical diagnostics: gives the
+  // agent ONE actionable item ("add these to input.properties OR drop these
+  // refs") instead of a wall of similar errors that visually drown the others.
+  if (missingInputProps.size > 0) {
+    const propNames = [...missingInputProps.keys()]
+    const validProps = Object.keys(inputProps)
+    if (propNames.length === 1) {
+      const [first] = propNames
+      const { loc, expr } = missingInputProps.get(first)
+      diagnostics.push({
+        severity: "error",
+        rule: "input_placeholder_missing",
+        endpoint: name, file, loc,
+        message: `\${${expr}} references input.${first}, but the endpoint's input schema has no '${first}' property.`,
+        fix_hint: `Valid properties: ${validProps.join(", ") || "(none declared)"}`,
+      })
+    } else {
+      // Aggregated form for endpoints with multiple stray refs.
+      const firstLoc = missingInputProps.values().next().value?.loc
+      diagnostics.push({
+        severity: "error",
+        rule: "input_placeholder_missing",
+        endpoint: name, file, loc: firstLoc,
+        message:
+          `Endpoint references ${propNames.length} input properties not declared in the input schema: ` +
+          `${propNames.join(", ")}.`,
+        fix_hint:
+          `Either add them to input.properties (so request validation lets them through) ` +
+          `OR remove the \${input.X} references that the workflow no longer uses. ` +
+          `Currently declared: ${validProps.join(", ") || "(none)"}.`,
+      })
+    }
+  }
 
-      // NOTE: an earlier version of this validator warned about manual
-      // `'${current_user_id}'::uuid` casts as "redundant", under the assumption
-      // that the engine auto-cast UUID-shaped values. That auto-cast was
-      // removed because it broke postgres.js binding in production. Manual
-      // ::uuid casts are now legitimate again, so no warning is emitted here.
+  // Same aggregation for ${nodes.X.Y} where X is not declared.
+  if (missingNodeRefs.size > 0) {
+    const nodeIdsMissing = [...missingNodeRefs.keys()]
+    const known = nodeIds.size ? `Known nodes: ${[...nodeIds].join(", ")}` : "This endpoint has no nodes yet."
+    if (nodeIdsMissing.length === 1) {
+      const [first] = nodeIdsMissing
+      const { loc, expr } = missingNodeRefs.get(first)
+      diagnostics.push({
+        severity: "error",
+        rule: "node_ref_missing",
+        endpoint: name, file, loc,
+        message: `\${${expr}} references node '${first}' but that node is not declared in this workflow.`,
+        fix_hint: known,
+      })
+    } else {
+      const firstLoc = missingNodeRefs.values().next().value?.loc
+      diagnostics.push({
+        severity: "error",
+        rule: "node_ref_missing",
+        endpoint: name, file, loc: firstLoc,
+        message:
+          `Endpoint references ${nodeIdsMissing.length} nodes that are not declared: ` +
+          `${nodeIdsMissing.join(", ")}.`,
+        fix_hint: known,
+      })
     }
   }
 
@@ -387,6 +505,30 @@ function validateEndpoint(entry, ctx) {
     // dypai_database — coherence checks for the new canonical operations.
     if (nodeType === "dypai_database") {
       const op = node.operation
+
+      // Extract referenced tables from real SQL fields ONLY. Doing this here
+      // (instead of in the generic walkStrings pass) eliminates the class of
+      // false positive where a prompt/comment/label happens to contain words
+      // like "INSERT" or "SELECT". Also covers `mutation` (table: <name>)
+      // since that's a guaranteed table reference.
+      if (op === "query" || (op && LEGACY_OPS_THAT_USE_QUERY.has(op))) {
+        const sqlText = typeof node.query === "string" ? node.query : ""
+        if (sqlText) {
+          for (const t of extractSqlTables(sqlText)) referencedTables.add(t)
+        }
+      }
+      if (op === "mutation" && typeof node.table === "string") {
+        referencedTables.add(node.table)
+      }
+      // Legacy ops like `select` / `insert` / `update` / `delete` use `table:`
+      // as the target table directly.
+      if (op && LEGACY_OPS_THAT_USE_TABLE_FIELD.has(op) && typeof node.table === "string") {
+        referencedTables.add(node.table)
+      }
+      // Resolved query_file content also counts as SQL (loaded by the codec).
+      if (typeof node.query === "string" && node.query.length > 0) {
+        for (const t of extractSqlTables(node.query)) referencedTables.add(t)
+      }
       const LEGACY_OPS = new Set(["select", "insert", "update", "delete", "upsert", "aggregate", "copy_to", "custom_query"])
       if (op && LEGACY_OPS.has(op)) {
         const suggested = (op === "custom_query") ? "query" : (op === "select") ? "query" : "mutation"
@@ -437,14 +579,26 @@ function validateEndpoint(entry, ctx) {
             fix_hint: `Pick exactly one: insert OR update OR delete (split into separate nodes if you need more).`,
           })
         }
-        if ((wantsUpdate || wantsDelete) && !node.where) {
-          diagnostics.push({
-            severity: "error",
-            rule: "mutation_missing_where",
-            endpoint: name, file, loc: `workflow.nodes[${node.id}]`,
-            message: `Node '${node.id}' (mutation ${wantsUpdate ? "update" : "delete"}) is missing 'where:' — refusing to operate on every row.`,
-            fix_hint: `Add 'where: { id: \${input.id}, user_id: \${current_user_id} }' (or whatever filter applies).`,
-          })
+        if (wantsUpdate || wantsDelete) {
+          // `where: {}` is just as dangerous as omitting `where:` entirely — both
+          // produce an unconstrained UPDATE/DELETE in the engine.
+          const whereVal = node.where
+          const whereIsEmpty =
+            whereVal === undefined ||
+            whereVal === null ||
+            (typeof whereVal === "object" && !Array.isArray(whereVal) && Object.keys(whereVal).length === 0)
+          if (whereIsEmpty) {
+            const action = wantsUpdate ? "update" : "delete"
+            diagnostics.push({
+              severity: "error",
+              rule: "mutation_missing_where",
+              endpoint: name, file, loc: `workflow.nodes[${node.id}]`,
+              message: whereVal === undefined || whereVal === null
+                ? `Node '${node.id}' (mutation ${action}) is missing 'where:' — refusing to operate on every row.`
+                : `Node '${node.id}' (mutation ${action}) has an empty 'where: {}' — that would ${action} every row in the table.`,
+              fix_hint: `Add at least one filter, e.g. 'where: { id: \${input.id}, user_id: \${current_user_id} }'.`,
+            })
+          }
         }
         // Foreign fields that belong to `operation: query`
         const QUERY_ONLY = ["query", "query_file", "params"]
@@ -520,12 +674,35 @@ function validateEndpoint(entry, ctx) {
       // automatically from displayOptions.show — so the catalog is the single
       // source of truth and we don't hardcode node names anywhere.
       const allRequired = []
+      const allOf = Array.isArray(schema.inputs?.allOf) ? schema.inputs.allOf : []
 
-      // Universal requirements
-      for (const req of required) allRequired.push({ name: req, condition: null })
+      // Polymorphic-node guard.
+      //
+      // Some node schemas in the catalog are polymorphic (the real param set
+      // depends on a discriminator like `operation`) but they declare ALL
+      // params from ALL branches inside a flat `required` without using
+      // `allOf[].if/then` to model the conditionality. The validator can't
+      // tell which branch the user picked, so it would emit a missing_required
+      // warning for every cross-branch param — pure noise.
+      //
+      // Heuristic: if the schema has an `operation` enum AND the node sets
+      // a value, OR if it's `dypai_database` (where the dedicated coherence
+      // block above already validates the real per-operation requirements),
+      // skip the flat `required` and rely on the catalog's `allOf` blocks
+      // (when present) for the actual conditional requirements.
+      const hasOperationEnum = schema.inputs?.properties?.operation?.enum?.length > 0
+      const isPolymorphicNode =
+        nodeType === "dypai_database" ||
+        (hasOperationEnum && node.operation !== undefined)
+      const trustFlatRequired = !isPolymorphicNode || allOf.length > 0
+
+      // Universal requirements (skipped for polymorphic nodes when the
+      // catalog provides no conditional structure to disambiguate).
+      if (trustFlatRequired) {
+        for (const req of required) allRequired.push({ name: req, condition: null })
+      }
 
       // Conditional requirements from allOf[]
-      const allOf = Array.isArray(schema.inputs?.allOf) ? schema.inputs.allOf : []
       for (const rule of allOf) {
         const ifProps = rule?.if?.properties || {}
         const thenRequired = rule?.then?.required || []
@@ -543,10 +720,26 @@ function validateEndpoint(entry, ctx) {
         }
       }
 
+      // The codec resolves user-friendly NAMES to engine UUIDs at push time:
+      //   credential: "openai-prod"   →   credential_id: "<uuid>"
+      //   tools:      ["my-endpoint"] →   tool_ids:      ["<uuid>"]
+      //   endpoint:   "my-endpoint"   →   endpoint_id:   "<uuid>"
+      // The catalog only knows the *_id form (what the engine ultimately
+      // receives), so a user who wrote `credential: openai-prod` correctly
+      // would otherwise be told `credential_id` is missing. Treat the
+      // human-friendly alias as satisfying the *_id requirement.
+      const ALIAS_FOR_REQUIRED = {
+        credential_id: "credential",
+        tool_ids: "tools",
+        endpoint_id: "endpoint",
+      }
+
       for (const { name: req, condition } of allRequired) {
         if (!paramKeys.includes(req)) {
           const hasFileEquivalent = META_KEYS.has(`${req}_file`) && node[`${req}_file`]
-          if (!hasFileEquivalent) {
+          const aliasField = ALIAS_FOR_REQUIRED[req]
+          const hasAlias = aliasField && node[aliasField] !== undefined && node[aliasField] !== null
+          if (!hasFileEquivalent && !hasAlias) {
             diagnostics.push({
               severity: "warn",
               rule: "missing_required_param",
@@ -562,11 +755,39 @@ function validateEndpoint(entry, ctx) {
         }
       }
 
-      // Unknown/typo params?
+      // Unknown/typo params? Two-phase emission to avoid catalog-staleness noise:
+      //   Phase 1: collect all unknowns + their typo suggestions
+      //   Phase 2: if 3+ unknowns AND none has a near-typo suggestion, treat
+      //   as catalog-staleness (one consolidated diag) rather than spamming
+      //   N near-identical warnings.
+      const knownKeys = Object.keys(properties)
+      const unknownsForNode = []
       for (const key of paramKeys) {
         if (!properties[key]) {
-          const knownKeys = Object.keys(properties)
           const suggestions = knownKeys.filter(k => levenshteinSmall(k, key) <= 2).slice(0, 2)
+          unknownsForNode.push({ key, suggestions })
+        }
+      }
+      const STALE_THRESHOLD = 3
+      const anyHasSuggestion = unknownsForNode.some(u => u.suggestions.length > 0)
+      if (unknownsForNode.length >= STALE_THRESHOLD && !anyHasSuggestion) {
+        // Likely catalog stale (or this node type just accepts more params
+        // than the catalog declares). One warning instead of N.
+        diagnostics.push({
+          severity: "warn",
+          rule: "unknown_params_bulk",
+          endpoint: name, file, loc: `workflow.nodes[${node.id}]`,
+          message:
+            `Node '${node.id}' (type '${nodeType}') has ${unknownsForNode.length} parameters not in the catalog: ` +
+            `${unknownsForNode.map(u => u.key).join(", ")}.`,
+          fix_hint:
+            `node-catalog.json may be stale (the engine often accepts more params than the catalog lists). ` +
+            `Run dypai_pull to refresh, or ignore if these params work in production. ` +
+            `Catalog-known params: ${knownKeys.slice(0, 8).join(", ")}${knownKeys.length > 8 ? "…" : ""}.`,
+        })
+      } else {
+        // Per-param emission — preserves "Did you mean?" hints when useful.
+        for (const { key, suggestions } of unknownsForNode) {
           diagnostics.push({
             severity: "warn",
             rule: "unknown_param",
@@ -576,7 +797,11 @@ function validateEndpoint(entry, ctx) {
               ? `Did you mean: ${suggestions.join(", ")}?`
               : `Valid params: ${knownKeys.slice(0, 8).join(", ")}${knownKeys.length > 8 ? "…" : ""}`,
           })
-        } else {
+        }
+      }
+      // Enum/range checks still need to run on every key that DID match the schema.
+      for (const key of paramKeys) {
+        if (properties[key]) {
           // Enum / range checks for primitive values
           const prop = properties[key]
           const v = node[key]
@@ -586,12 +811,23 @@ function validateEndpoint(entry, ctx) {
           // dypai_storage / dypai_database nodes.
           const hasPlaceholder = typeof v === "string" && v.includes("${")
           if (prop.enum && typeof v === "string" && !hasPlaceholder && !prop.enum.includes(v)) {
+            // WARN, not error: node-catalog.json is generated from the central
+            // control plane and routinely lags behind the actual engine
+            // (operations are added/renamed faster than catalog regeneration
+            // happens). When the catalog says `operation` ∈ [a, b, c] but
+            // the engine actually accepts `d` too, blocking push with an
+            // ERROR would be wrong — the engine is the source of truth at
+            // runtime. Surface as warning so the user sees a "double-check
+            // this" hint without blocking the workflow. Real typos (`fnid`
+            // for `find`) still surface clearly.
             diagnostics.push({
-              severity: "error",
+              severity: "warn",
               rule: "param_enum_violation",
               endpoint: name, file, loc: `workflow.nodes[${node.id}].${key}`,
-              message: `Node '${node.id}' parameter '${key}' = '${v}' is not one of: ${prop.enum.join(", ")}.`,
-              fix_hint: `Allowed values: ${prop.enum.join(", ")}`,
+              message: `Node '${node.id}' parameter '${key}' = '${v}' is not in the catalog enum: ${prop.enum.join(", ")}.`,
+              fix_hint:
+                `Either fix to one of: ${prop.enum.join(", ")} — OR if the engine accepts '${v}' ` +
+                `(catalog may be stale), refresh node-catalog.json with dypai_pull and ignore this if the warning persists.`,
             })
           }
           if (prop.type === "number" || prop.type === "integer") {
@@ -654,7 +890,138 @@ function validateEndpoint(entry, ctx) {
     }
   }
 
-  return diagnostics
+  // ── Edge sanity: catch typos in workflow.edges before runtime ────────────
+  // The engine silently skips edges whose `from`/`to` doesn't resolve to a
+  // node id, which manifests as "node never ran" — extremely hard to debug.
+  const edges = doc.workflow?.edges || []
+  if (Array.isArray(edges)) {
+    for (let i = 0; i < edges.length; i++) {
+      const edge = edges[i]
+      if (!edge || typeof edge !== "object") continue
+      const from = edge.from ?? edge.source
+      const to = edge.to ?? edge.target
+      const known = nodeIds.size ? `Known nodes: ${[...nodeIds].join(", ")}` : "Add the node to workflow.nodes[] first."
+      if (from && !nodeIds.has(from)) {
+        diagnostics.push({
+          severity: "error",
+          rule: "edge_unknown_node",
+          endpoint: name, file, loc: `workflow.edges[${i}].from`,
+          message: `Edge from '${from}' but no node with that id is declared.`,
+          fix_hint: known,
+        })
+      }
+      if (to && !nodeIds.has(to)) {
+        diagnostics.push({
+          severity: "error",
+          rule: "edge_unknown_node",
+          endpoint: name, file, loc: `workflow.edges[${i}].to`,
+          message: `Edge to '${to}' but no node with that id is declared.`,
+          fix_hint: known,
+        })
+      }
+    }
+  }
+
+  // ── Ambiguous response: multiple terminal nodes without explicit return ──
+  // The engine's behavior (graphScheduler.ts:202): if no node is marked
+  // is_return, it returns the result of whichever node ran LAST. With a
+  // single terminal node (linear chain or sole node) that's deterministic
+  // and fine — no warning needed. With MULTIPLE terminal nodes (branches
+  // that don't reconverge), "last to finish" is non-deterministic and
+  // almost certainly not what the author intended.
+  const allNodes = doc.workflow?.nodes || []
+  if (allNodes.length > 1) {
+    const hasReturn = allNodes.some(n => n?.return === true || n?.is_return === true)
+    if (!hasReturn) {
+      const triggerKeys = Object.keys(doc.trigger || {})
+      const NEEDS_RESPONSE = new Set(["http_api", "webhook"])
+      const needsResponse = triggerKeys.some(k => NEEDS_RESPONSE.has(k))
+      if (needsResponse) {
+        // Find terminal nodes (no outgoing edges).
+        const edgeList = Array.isArray(doc.workflow?.edges) ? doc.workflow.edges : []
+        const hasOutgoing = new Set()
+        for (const e of edgeList) {
+          const from = e?.from ?? e?.source
+          if (from) hasOutgoing.add(from)
+        }
+        const terminals = allNodes.filter(n => !hasOutgoing.has(n.id))
+        if (terminals.length > 1) {
+          diagnostics.push({
+            severity: "warn",
+            rule: "ambiguous_return",
+            endpoint: name, file, loc: "workflow.nodes",
+            message:
+              `Endpoint has ${terminals.length} terminal nodes (${terminals.map(t => t.id).join(", ")}) but none is marked 'return: true'. ` +
+              `The engine will return whichever finishes last, which is non-deterministic.`,
+            fix_hint: `Mark exactly one terminal node with 'return: true' to make the response unambiguous.`,
+          })
+        }
+      }
+    }
+  }
+
+  // ── tool: true requires tool_description ─────────────────────────────────
+  // Without a description, an agent's LLM has nothing to base "should I call
+  // this?" decisions on, and the engine will accept the tool but it will
+  // never actually be picked.
+  if (doc.tool === true && (!doc.tool_description || String(doc.tool_description).trim() === "")) {
+    diagnostics.push({
+      severity: "warn",
+      rule: "tool_missing_description",
+      endpoint: name, file,
+      message: `Endpoint marked 'tool: true' but has no 'tool_description' — LLMs won't know when to invoke it.`,
+      fix_hint: `Add 'tool_description: <plain-language description of what it does and when an agent should call it>'.`,
+    })
+  }
+
+  // ── auth_mode: public + write operation = security hole ──────────────────
+  // Public endpoints are anonymous and unrate-limited per-user; combining
+  // that with a write means anyone on the internet can mutate state.
+  const authMode = doc.trigger?.http_api?.auth_mode
+  if (authMode === "public") {
+    for (const node of allNodes) {
+      const nodeType = node?.type ?? node?.node_type
+      if (nodeType !== "dypai_database") continue
+      const op = node.operation
+      let writeKind = null
+      if (op === "mutation") {
+        if (node.insert !== undefined && node.insert !== null) writeKind = "INSERT"
+        else if (node.update !== undefined && node.update !== null) writeKind = "UPDATE"
+        else if (node.delete === true) writeKind = "DELETE"
+      } else if (op === "query") {
+        const sql = String(node.query || "")
+        if (/\b(INSERT|UPDATE|DELETE|TRUNCATE|DROP|ALTER|CREATE)\b/i.test(sql)) {
+          writeKind = "write SQL"
+        }
+      } else if (LEGACY_WRITE_OPS.has(op)) {
+        writeKind = op.toUpperCase()
+      }
+      if (writeKind) {
+        diagnostics.push({
+          severity: "error",
+          rule: "public_auth_with_write",
+          endpoint: name, file, loc: `workflow.nodes[${node.id}]`,
+          message: `auth_mode: public + ${writeKind} write — anyone can call this anonymously and mutate data.`,
+          fix_hint: `Change trigger.http_api.auth_mode to 'jwt' (user-scoped) or 'api_key' (server-to-server). 'public' is for anonymous READS only.`,
+        })
+      }
+    }
+  }
+
+  // Dedupe identical diagnostics within an endpoint (same rule + loc + message).
+  // The walkStrings pass naturally emits one diag per occurrence of a placeholder
+  // — but a SQL block with `${current_user_id}` repeated for INSERT and WHERE
+  // produces two literally-identical errors at the same loc. Collapsing them
+  // is harmless (one fix addresses both occurrences) and keeps the output clean.
+  const seen = new Set()
+  const unique = []
+  for (const d of diagnostics) {
+    const key = `${d.rule}|${d.loc || ""}|${d.message}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    unique.push(d)
+  }
+  return unique
 }
 
 // ─── Schema staleness detection ─────────────────────────────────────────────