@boboddy/sdk 0.5.1 → 0.5.3

package/dist/definitions/validation/index.js

@@ -207,22 +207,22 @@ function enumeratePaths(node, root, maxDepth = 3, limit = 40) {
   visit(node, "", 1);
   return [...new Set(out)].sort();
 }
-function resolveSourcePath(schema, sourcePath) {
+function resolvePathToNode(schema, sourcePath) {
   const segments = parseSourcePath(sourcePath);
   if (segments.length === 0)
-    return { kind: "resolved" };
+    return { kind: "resolved", node: schema };
   let candidates = [schema];
   let resolvedPrefix = "";
   for (const segment of segments) {
-    const expanded = candidates.flatMap((node) => flatten(node, schema) ?? []);
+    const expanded = candidates.flatMap((node2) => flatten(node2, schema) ?? []);
     if (expanded.length === 0)
       return { kind: "indeterminate" };
-    const outcome = combine(expanded.map((node) => stepInto(node, segment)));
+    const outcome = combine(expanded.map((node2) => stepInto(node2, segment)));
     if (outcome.kind === "indeterminate")
       return { kind: "indeterminate" };
     if (outcome.kind === "invalid") {
       const availablePaths = [
-        ...new Set(expanded.flatMap((node) => enumeratePaths(node, schema)))
+        ...new Set(expanded.flatMap((node2) => enumeratePaths(node2, schema)))
       ].sort();
       return {
         kind: "invalid",
@@ -235,7 +235,60 @@ function resolveSourcePath(schema, sourcePath) {
     candidates = [outcome.node];
     resolvedPrefix = resolvedPrefix ? `${resolvedPrefix}.${segment}` : segment;
   }
-  return { kind: "resolved" };
+  const [node] = candidates;
+  return node ? { kind: "resolved", node } : { kind: "indeterminate" };
+}
+function resolveSourcePath(schema, sourcePath) {
+  const result = resolvePathToNode(schema, sourcePath);
+  if (result.kind === "resolved")
+    return { kind: "resolved" };
+  if (result.kind === "indeterminate")
+    return { kind: "indeterminate" };
+  return {
+    kind: "invalid",
+    resolvedPrefix: result.resolvedPrefix,
+    segment: result.segment,
+    reason: result.reason,
+    availablePaths: result.availablePaths
+  };
+}
+var KNOWN_TYPES = new Set([
+  "string",
+  "number",
+  "boolean",
+  "object",
+  "array",
+  "null"
+]);
+function normalizeTypeName(name) {
+  return name === "integer" ? "number" : name;
+}
+function resolveSchemaType(node, root = node) {
+  const branches = flatten(node, root);
+  if (!branches || branches.length === 0)
+    return "unknown";
+  const types = new Set;
+  for (const branch of branches) {
+    const record = asRecord(branch);
+    if (!record)
+      return "unknown";
+    const names = [...typeNames(record)].map(normalizeTypeName);
+    if (names.length !== 1)
+      return "unknown";
+    const [name] = names;
+    if (!name || !KNOWN_TYPES.has(name))
+      return "unknown";
+    types.add(name);
+  }
+  if (types.size !== 1)
+    return "unknown";
+  return [...types][0];
+}
+function resolvePathType(schema, sourcePath) {
+  const result = resolvePathToNode(schema, sourcePath);
+  if (result.kind !== "resolved")
+    return "unknown";
+  return resolveSchemaType(result.node, schema);
 }
 // src/definitions/pipelines/chain-graph.ts
 function tryComputeTopoRanks(nodeDefinitions, dependencyEdges) {
@@ -288,6 +341,75 @@ function tryOrderNodeDefinitionsByTopoRank(nodeDefinitions, dependencyEdges) {
     return rankDiff !== 0 ? rankDiff : left.declarationIndex - right.declarationIndex;
   }).map(({ node }) => node);
 }
+function tryComputeDominators(nodeDefinitions, dependencyEdges, entryNodeKey) {
+  const nodeKeys = new Set(nodeDefinitions.map((node) => node.nodeKey));
+  if (!nodeKeys.has(entryNodeKey))
+    return null;
+  if (tryComputeTopoRanks(nodeDefinitions, dependencyEdges) === null) {
+    return null;
+  }
+  const outgoing = new Map;
+  const incoming = new Map;
+  for (const key of nodeKeys) {
+    outgoing.set(key, []);
+    incoming.set(key, []);
+  }
+  for (const edge of dependencyEdges) {
+    outgoing.get(edge.fromNodeKey)?.push(edge.toNodeKey);
+    incoming.get(edge.toNodeKey)?.push(edge.fromNodeKey);
+  }
+  const reachable = new Set([entryNodeKey]);
+  const queue = [entryNodeKey];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === undefined)
+      break;
+    for (const next of outgoing.get(current) ?? []) {
+      if (reachable.has(next))
+        continue;
+      reachable.add(next);
+      queue.push(next);
+    }
+  }
+  const dom = new Map;
+  dom.set(entryNodeKey, new Set([entryNodeKey]));
+  for (const key of reachable) {
+    if (key !== entryNodeKey)
+      dom.set(key, new Set(reachable));
+  }
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const key of reachable) {
+      if (key === entryNodeKey)
+        continue;
+      let intersection = null;
+      for (const predecessor of incoming.get(key) ?? []) {
+        if (!reachable.has(predecessor))
+          continue;
+        const predecessorDom = dom.get(predecessor);
+        if (!predecessorDom)
+          continue;
+        if (intersection === null) {
+          intersection = new Set(predecessorDom);
+          continue;
+        }
+        for (const candidate of intersection) {
+          if (!predecessorDom.has(candidate))
+            intersection.delete(candidate);
+        }
+      }
+      const nextDom = intersection ?? new Set;
+      nextDom.add(key);
+      const currentDom = dom.get(key);
+      if (!currentDom || currentDom.size !== nextDom.size || [...currentDom].some((item) => !nextDom.has(item))) {
+        dom.set(key, nextDom);
+        changed = true;
+      }
+    }
+  }
+  return dom;
+}
 
 // ../../../node_modules/.bun/zod@4.4.3/node_modules/zod/v4/classic/external.js
 var exports_external = {};
@@ -15259,25 +15381,6 @@ function compileLoopState(stateKey, state, ctx) {
 function compileTerminalState(stateKey, kind) {
   return { nodeDefinitions: [{ nodeKey: stateKey, kind }], edges: [] };
 }
-function assertNoIllegalConvergentEdges(pipelineKey, nodeKindByKey, edges) {
-  const incoming = new Map;
-  for (const edge of edges) {
-    const list = incoming.get(edge.toNodeKey) ?? [];
-    list.push(edge);
-    incoming.set(edge.toNodeKey, list);
-  }
-  for (const [targetKey, incomingEdges] of incoming) {
-    if (incomingEdges.length <= 1)
-      continue;
-    const hasInvalidSource = incomingEdges.some((edge) => {
-      const kind = nodeKindByKey.get(edge.fromNodeKey);
-      return kind !== "choice" && kind !== "loop";
-    });
-    if (hasInvalidSource) {
-      throw new Error(`Pipeline "${pipelineKey}": state "${targetKey}" has more than one incoming edge, but not every source is a 'choice'/'loop' state (unconditional convergent edges are not allowed \u2014 see docs/research/flat-pipeline-sdk-and-visual-designer.md \xA76).`);
-    }
-  }
-}
 
 // src/definitions/pipelines/define-pipeline.ts
 function isWorkingNodeDefinition(node) {
@@ -15314,8 +15417,6 @@ function definePipeline(config2) {
     nodeDefinitions.push(...compiled.nodeDefinitions);
     dependencyEdges.push(...compiled.edges);
   }
-  const nodeKindByKey = new Map(nodeDefinitions.map((node) => [node.nodeKey, node.kind]));
-  assertNoIllegalConvergentEdges(config2.key, nodeKindByKey, dependencyEdges);
   let inputSchemaJson = null;
   if (config2.input) {
     try {
@@ -15331,13 +15432,14 @@ function definePipeline(config2) {
     version: config2.version ?? 1,
     status: config2.status ?? "active",
     inputSchemaJson,
+    entryNodeKey: config2.startAt,
     _stepDefinitions: [...stepDefMap.values()],
     nodeDefinitions,
     dependencyEdges
   };
 }
 
-// src/definitions/validation/validate-definition-specs.ts
+// src/definitions/validation/validation-issue.ts
 function listPaths(paths, limit = 24) {
   if (paths.length === 0)
     return "";
@@ -15345,6 +15447,250 @@ function listPaths(paths, limit = 24) {
     return paths.join(", ");
   return `${paths.slice(0, limit).join(", ")}, \u2026 (${String(paths.length - limit)} more)`;
 }
+
+// src/definitions/validation/validate-input-bindings.ts
+var WORK_ITEM_TOP_LEVEL_FIELD_SET = new Set(WORK_ITEM_TOP_LEVEL_FIELDS);
+function isAutoBoundWorkItemField(field) {
+  return field === "workItemTitle" || field === "workItemDescription";
+}
+function bindingContexts(pipeline) {
+  const contexts = [];
+  for (const node of pipeline.nodeDefinitions) {
+    if (isWorkingNodeDefinition(node)) {
+      contexts.push({
+        nodeKey: node.nodeKey,
+        branchKey: null,
+        stepKey: node.stepKey,
+        inputBindingsJson: node.inputBindingsJson ?? {}
+      });
+      continue;
+    }
+    if (node.kind === "parallel" && node.branches) {
+      for (const [branchKey, branch] of Object.entries(node.branches)) {
+        contexts.push({
+          nodeKey: node.nodeKey,
+          branchKey,
+          stepKey: branch.stepKey,
+          inputBindingsJson: branch.inputBindingsJson ?? {}
+        });
+      }
+    }
+  }
+  return contexts;
+}
+function bindingContextLabel(pipelineKey, ctx) {
+  return ctx.branchKey ? `Pipeline "${pipelineKey}" node "${ctx.nodeKey}" branch "${ctx.branchKey}"` : `Pipeline "${pipelineKey}" node "${ctx.nodeKey}"`;
+}
+function knownInputFields(specs) {
+  const fields = new Set;
+  for (const spec of specs) {
+    const schema = spec.inputSchemaJson;
+    if (!schema)
+      continue;
+    const properties = schema["properties"];
+    if (!properties || typeof properties !== "object" || Array.isArray(properties)) {
+      continue;
+    }
+    for (const key of Object.keys(properties))
+      fields.add(key);
+  }
+  return fields;
+}
+function requiredInputFields(specs) {
+  const fields = new Set;
+  for (const spec of specs) {
+    const schema = spec.inputSchemaJson;
+    if (!schema)
+      continue;
+    const required2 = schema["required"];
+    if (!Array.isArray(required2))
+      continue;
+    for (const entry of required2) {
+      if (typeof entry === "string")
+        fields.add(entry);
+    }
+  }
+  return fields;
+}
+function isJsonSchemaNode(value) {
+  return typeof value === "boolean" || typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function findPropertyNode(specs, field) {
+  for (const spec of specs) {
+    const schema = spec.inputSchemaJson;
+    if (!schema)
+      continue;
+    const properties = schema["properties"];
+    if (!properties || typeof properties !== "object" || Array.isArray(properties)) {
+      continue;
+    }
+    const node = properties[field];
+    if (isJsonSchemaNode(node))
+      return { node, root: schema };
+  }
+  return null;
+}
+function checkUnboundRequiredInputs(pipelines, stepsByKey) {
+  const issues = [];
+  for (const pipeline of pipelines) {
+    for (const ctx of bindingContexts(pipeline)) {
+      const specs = stepsByKey.get(ctx.stepKey);
+      if (!specs)
+        continue;
+      const required2 = requiredInputFields(specs);
+      if (required2.size === 0)
+        continue;
+      const bound = new Set(Object.keys(ctx.inputBindingsJson));
+      const missing = [...required2].filter((field) => !bound.has(field) && !isAutoBoundWorkItemField(field)).sort();
+      if (missing.length === 0)
+        continue;
+      const where = bindingContextLabel(pipeline.key, ctx);
+      const boundList = [
+        ...bound,
+        "workItemTitle",
+        "workItemDescription"
+      ].sort();
+      for (const field of missing) {
+        issues.push({
+          check: "unbound-required-input",
+          severity: "error",
+          pipelineKey: pipeline.key,
+          nodeKey: ctx.nodeKey,
+          branchKey: ctx.branchKey ?? undefined,
+          message: `${where} runs step "${ctx.stepKey}", which requires input "${field}", ` + `but no binding provides it. Bound inputs: ${listPaths(boundList)}.`
+        });
+      }
+    }
+  }
+  return issues;
+}
+function checkBindingTargetFields(pipelines, stepsByKey) {
+  const issues = [];
+  for (const pipeline of pipelines) {
+    for (const ctx of bindingContexts(pipeline)) {
+      const specs = stepsByKey.get(ctx.stepKey);
+      const knownFields = specs ? knownInputFields(specs) : null;
+      const where = bindingContextLabel(pipeline.key, ctx);
+      for (const [field, binding] of Object.entries(ctx.inputBindingsJson)) {
+        if (knownFields && !isAutoBoundWorkItemField(field) && !knownFields.has(field)) {
+          issues.push({
+            check: "binding-target-field",
+            severity: "info",
+            pipelineKey: pipeline.key,
+            nodeKey: ctx.nodeKey,
+            branchKey: ctx.branchKey ?? undefined,
+            message: `${where} is passing information ("${field}") to step "${ctx.stepKey}" ` + `that it isn't explicitly asking for \u2014 the step declares no such ` + `additionalInput field, so the value is dropped. Declared fields: ` + `${knownFields.size > 0 ? listPaths([...knownFields].sort()) : "(none)"}.`
+          });
+        }
+        if (binding.source === "work_item" && !binding.field.startsWith(WORK_ITEM_FIELDS_PATH_PREFIX) && !WORK_ITEM_TOP_LEVEL_FIELD_SET.has(binding.field)) {
+          issues.push({
+            check: "binding-target-field",
+            severity: "error",
+            pipelineKey: pipeline.key,
+            nodeKey: ctx.nodeKey,
+            branchKey: ctx.branchKey ?? undefined,
+            message: `${where} binds input "${field}" to work_item field "${binding.field}", ` + `which is not a known top-level work-item field and does not start ` + `with "${WORK_ITEM_FIELDS_PATH_PREFIX}". Known top-level fields: ` + `${listPaths(WORK_ITEM_TOP_LEVEL_FIELDS)}.`
+          });
+        }
+      }
+    }
+  }
+  return issues;
+}
+function describeBindingSource(binding) {
+  switch (binding.source) {
+    case "step_signal":
+      return `signal "${binding.signalKey}" of node "${binding.stepKey}"`;
+    case "step_output":
+      return `the output of node "${binding.stepKey}"`;
+    case "signals_list":
+      return `the signals list of fan-out node "${binding.stepKey}"`;
+    case "pipeline_input":
+      return `pipeline input "${binding.path}"`;
+    case "work_item":
+      return `work_item field "${binding.field}"`;
+    case "literal":
+      return "a literal value";
+    case "fan_out_item":
+      return "the fan-out item";
+  }
+}
+function bindingSourceType(binding, pipeline, nodeByKey, stepsByKey) {
+  if (binding.source === "step_signal") {
+    const producerNode = nodeByKey.get(binding.stepKey);
+    if (!producerNode || !isWorkingNodeDefinition(producerNode))
+      return "unknown";
+    const specs = stepsByKey.get(producerNode.stepKey) ?? [];
+    for (const spec of specs) {
+      const signal2 = spec.signalExtractorDefinitions.find((candidate) => candidate.key === binding.signalKey);
+      if (signal2)
+        return signal2.type;
+    }
+    return "unknown";
+  }
+  if (binding.source === "step_output") {
+    const producerNode = nodeByKey.get(binding.stepKey);
+    if (!producerNode || !isWorkingNodeDefinition(producerNode))
+      return "unknown";
+    const specs = stepsByKey.get(producerNode.stepKey) ?? [];
+    for (const spec of specs) {
+      if (spec.resultSchemaJson)
+        return resolveSchemaType(spec.resultSchemaJson);
+    }
+    return "unknown";
+  }
+  if (binding.source === "signals_list")
+    return "array";
+  if (binding.source === "pipeline_input") {
+    return pipeline.inputSchemaJson ? resolvePathType(pipeline.inputSchemaJson, binding.path) : "unknown";
+  }
+  if (binding.source === "work_item") {
+    if (binding.field.startsWith(WORK_ITEM_FIELDS_PATH_PREFIX))
+      return "unknown";
+    return WORK_ITEM_TOP_LEVEL_FIELD_SET.has(binding.field) ? "string" : "unknown";
+  }
+  return "unknown";
+}
+function checkBindingTypeCompatibility(pipelines, stepsByKey) {
+  const issues = [];
+  for (const pipeline of pipelines) {
+    const nodeByKey = new Map(pipeline.nodeDefinitions.map((node) => [node.nodeKey, node]));
+    for (const ctx of bindingContexts(pipeline)) {
+      const specs = stepsByKey.get(ctx.stepKey);
+      const where = bindingContextLabel(pipeline.key, ctx);
+      for (const [field, binding] of Object.entries(ctx.inputBindingsJson)) {
+        if (binding.source === "fan_out_item")
+          continue;
+        if (isAutoBoundWorkItemField(field))
+          continue;
+        if (!specs)
+          continue;
+        const target = findPropertyNode(specs, field);
+        if (!target)
+          continue;
+        const targetType = resolveSchemaType(target.node, target.root);
+        if (targetType === "unknown")
+          continue;
+        const sourceType = bindingSourceType(binding, pipeline, nodeByKey, stepsByKey);
+        if (sourceType === "unknown")
+          continue;
+        if (sourceType === targetType)
+          continue;
+        issues.push({
+          check: "binding-type-mismatch",
+          severity: "warning",
+          pipelineKey: pipeline.key,
+          nodeKey: ctx.nodeKey,
+          branchKey: ctx.branchKey ?? undefined,
+          message: `${where} binds input "${field}" (declared type "${targetType}") to ` + `${describeBindingSource(binding)}, which resolves to type ` + `"${sourceType}" \u2014 the types disagree.`
+        });
+      }
+    }
+  }
+  return issues;
+}
+
+// src/definitions/validation/validate-definition-specs.ts
 function quotedOrRoot(prefix) {
   return prefix ? `"${prefix}"` : "the result root";
 }
@@ -15363,6 +15709,7 @@ function checkSignalSourcePaths(steps) {
       const suffix = availablePaths.length > 0 ? ` Valid sourcePaths ${resolvedPrefix ? `under "${resolvedPrefix}"` : "for this step"}: ${listPaths(availablePaths)}.` : "";
       issues.push({
         check: "signal-source-path",
+        severity: "error",
         message: `Step "${step.key}" declares signal "${signal2.key}" with sourcePath ` + `"${signal2.sourcePath}", which can never resolve against the step's ` + `result schema: ${cause}.${suffix}`
       });
     }
@@ -15385,6 +15732,7 @@ function checkHealthChecks(steps) {
       if (!mcpServerKeySet.has(check2.mcp)) {
         issues.push({
           check: "health-check-mcp-server",
+          severity: "error",
           message: `${where} names MCP server "${check2.mcp}", but the step declares no ` + `such server in mcpServers. Declared servers: ${mcpServerKeys.length > 0 ? listPaths([...mcpServerKeys].sort()) : "(none)"}.`
         });
       }
@@ -15392,6 +15740,7 @@ function checkHealthChecks(steps) {
       if (check2.tool.startsWith(prefix)) {
         issues.push({
           check: "health-check-double-qualified",
+          severity: "error",
           message: `${where} sets mcp "${check2.mcp}" and tool "${check2.tool}", which already ` + `starts with "${prefix}". When "mcp" is set, "tool" should be the bare tool ` + `name \u2014 OpenCode resolves it to "${prefix}${check2.tool}". Did you mean ` + `tool: "${check2.tool.slice(prefix.length)}"?`
         });
       }
@@ -15428,6 +15777,7 @@ function checkRouteTargets(pipelines, knownPipelineKeys) {
           continue;
         issues.push({
           check: "route-target",
+          severity: "error",
           pipelineKey: pipeline.key,
           nodeKey: node.nodeKey,
           message: `Pipeline "${pipeline.key}" step "${stepLabel}" routes to pipeline ` + `"${target}", but no pipeline with that key was found on the server or ` + `in the current push batch. Push the target pipeline first.`
@@ -15483,6 +15833,7 @@ function checkSignalBindings(pipelines, stepsByKey) {
     const order = [...pipeline.nodeDefinitions.keys()].sort((left, right) => (ranks.get(left) ?? 0) - (ranks.get(right) ?? 0)).map((index) => pipeline.nodeDefinitions[index]?.nodeKey ?? "");
     const orderHint = `Nodes in "${pipeline.key}", in order: ${order.join(" \u2192 ")}.`;
     const nodeByKey = new Map(pipeline.nodeDefinitions.map((node) => [node.nodeKey, node]));
+    const dominatorSets = tryComputeDominators(pipeline.nodeDefinitions, pipeline.dependencyEdges, pipeline.entryNodeKey);
     pipeline.nodeDefinitions.forEach((node, index) => {
       const consumerRank = ranks.get(index) ?? index;
       const where = `Pipeline "${pipeline.key}" node "${node.nodeKey}"`;
@@ -15493,6 +15844,7 @@ function checkSignalBindings(pipelines, stepsByKey) {
           continue;
         const what = source.kind === "signal" ? `binds input "${field}" to signal "${source.signalKey ?? ""}" of node "${source.nodeKey}"` : source.kind === "signals_list" ? `binds input "${field}" to the signals list of fan-out node "${source.nodeKey}"` : `binds input "${field}" to the output of node "${source.nodeKey}"`;
         const issueBase = {
+          severity: "error",
           pipelineKey: pipeline.key,
           nodeKey: node.nodeKey,
           targetNodeKey: source.nodeKey
@@ -15507,11 +15859,12 @@ function checkSignalBindings(pipelines, stepsByKey) {
           });
           continue;
         }
-        if (producerRank >= consumerRank) {
+        const producesBeforeConsumer = dominatorSets !== null ? source.nodeKey !== node.nodeKey && (dominatorSets.get(node.nodeKey)?.has(source.nodeKey) ?? false) : producerRank < consumerRank;
+        if (!producesBeforeConsumer) {
           issues.push({
             check: "signal-binding",
             ...issueBase,
-            message: `${where} ${what}, but that node does not run before it, so the ` + `value will never exist. ${orderHint}`
+            message: `${where} ${what}, but that node does not run on every path ` + `leading to this node, so the value may not exist. ${orderHint}`
           });
           continue;
         }
@@ -15543,11 +15896,14 @@ function validateDefinitionSpecs(specs, options = {}) {
     ...checkSignalSourcePaths(specs.steps),
     ...checkHealthChecks(specs.steps),
     ...checkRouteTargets(specs.pipelines, options.knownPipelineKeys ?? []),
-    ...checkSignalBindings(specs.pipelines, stepsByKey)
+    ...checkSignalBindings(specs.pipelines, stepsByKey),
+    ...checkUnboundRequiredInputs(specs.pipelines, stepsByKey),
+    ...checkBindingTargetFields(specs.pipelines, stepsByKey),
+    ...checkBindingTypeCompatibility(specs.pipelines, stepsByKey)
   ];
 }
 function assertValidDefinitionSpecs(specs, options = {}) {
-  const issues = validateDefinitionSpecs(specs, options);
+  const issues = validateDefinitionSpecs(specs, options).filter((issue2) => issue2.severity === "error");
   if (issues.length === 0)
     return;
   const header = issues.length === 1 ? "Definition validation failed:" : `Definition validation failed with ${String(issues.length)} problems:`;
@@ -15556,8 +15912,14 @@ function assertValidDefinitionSpecs(specs, options = {}) {
 }
 export {
   assertValidDefinitionSpecs,
+  checkBindingTargetFields,
+  checkBindingTypeCompatibility,
+  checkUnboundRequiredInputs,
   enumeratePaths,
+  listPaths,
   parseSourcePath,
+  resolvePathType,
+  resolveSchemaType,
   resolveSourcePath,
   validateDefinitionSpecs
 };

package/dist/definitions/validation/json-schema-paths.d.ts

@@ -43,3 +43,32 @@ export declare function enumeratePaths(node: JsonSchemaNode, root: JsonSchemaNod
  * `$ref`s are resolved against the root.
  */
 export declare function resolveSourcePath(schema: JsonSchemaNode, sourcePath: string): PathResolution;
+/**
+ * The type vocabulary a schema node is reduced to. `"integer"` (a JSON
+ * Schema refinement Zod emits for `z.number().int()`) collapses into
+ * `"number"`; anything the schema doesn't pin to exactly one of these is
+ * `"unknown"`.
+ */
+export type SchemaType = "string" | "number" | "boolean" | "object" | "array" | "null" | "unknown";
+/**
+ * Reduces a JSON Schema node to its top-level type, per `SchemaType`.
+ *
+ * Follows the same `$ref` / `anyOf` / `oneOf` / `allOf` flattening
+ * `resolveSourcePath` uses, so a `$ref` is resolved against `root` (default:
+ * `node` itself — pass the document root explicitly when `node` came from
+ * deeper inside it). Returns `"unknown"` — never a guess — when: the schema
+ * is absent (`{}`, e.g. `z.unknown()`) or a boolean schema (`true` / `false`);
+ * a `$ref` fails to resolve; or the branches disagree on type (a union of
+ * a string and a number, say). A false "this is definitely a string" is
+ * worse than an honest "unknown" here, same bias as path resolution.
+ */
+export declare function resolveSchemaType(node: JsonSchemaNode, root?: JsonSchemaNode): SchemaType;
+/**
+ * The type `sourcePath` resolves to within `schema` — `"unknown"` whenever
+ * the path doesn't provably resolve to a single node (indeterminate or
+ * invalid) or the node it resolves to doesn't pin down a single type.
+ *
+ * Pass the step's `resultSchemaJson` as `schema`; `$ref`s are resolved
+ * against it as the document root, matching `resolveSourcePath`.
+ */
+export declare function resolvePathType(schema: JsonSchemaNode, sourcePath: string): SchemaType;

package/dist/definitions/validation/validate-definition-specs.d.ts

@@ -1,5 +1,6 @@
 import { type PipelineDefinitionSpec } from "../pipelines/define-pipeline";
 import type { StepDefinitionSpec } from "../steps/define-step";
+import { type DefinitionValidationIssue } from "./validation-issue";
 export type DefinitionSpecSet = {
     readonly pipelines: readonly PipelineDefinitionSpec[];
     readonly steps: readonly StepDefinitionSpec[];
@@ -12,32 +13,20 @@ export type ValidateDefinitionSpecsOptions = {
      */
     readonly knownPipelineKeys?: readonly string[];
 };
-export type DefinitionValidationIssue = {
-    readonly check: "signal-source-path" | "route-target" | "signal-binding" | "health-check-mcp-server" | "health-check-double-qualified";
-    readonly message: string;
-    /**
-     * The pipeline this issue belongs to, when the check is pipeline-scoped
-     * (`route-target`/`signal-binding`) — absent for step-only checks
-     * (`signal-source-path`/`health-check-*`), which have no pipeline
-     * context of their own. Required before the designer (Phase 5) can
-     * attach an error to the right graph node.
-     */
-    readonly pipelineKey?: string;
-    /** The node this issue is about, when pipeline-scoped. */
-    readonly nodeKey?: string;
-    /**
-     * A second, related node this issue is about — e.g. `signal-binding`'s
-     * producer node, when different from `nodeKey`'s consumer. Absent when
-     * the issue is about a single node, or when the "other end" isn't a
-     * node in this pipeline at all (`route-target`'s target is a different
-     * *pipeline*, not a node).
-     */
-    readonly targetNodeKey?: string;
-};
 /**
  * Runs every offline check over a batch of definitions and returns the issues
  * found, in check order. An empty array means the batch is clean.
  */
 export declare function validateDefinitionSpecs(specs: DefinitionSpecSet, options?: ValidateDefinitionSpecsOptions): DefinitionValidationIssue[];
-/** `validateDefinitionSpecs`, but throws a single aggregated error. */
+/**
+ * `validateDefinitionSpecs`, but throws a single aggregated error.
+ *
+ * Only counts and lists `severity: "error"` issues — `"warning"`-tier issues
+ * (`binding-type-mismatch`) and `"info"`-tier issues (`binding-target-field`'s
+ * unbound-field-name sub-check) never block a push and are silently dropped
+ * from both the header count and the body here. They're still present in
+ * `validateDefinitionSpecs`'s own return value for any caller that wants to
+ * surface them (e.g. the designer, in a later phase); this is the one entry
+ * point whose whole job is "should this push be blocked."
+ */
 export declare function assertValidDefinitionSpecs(specs: DefinitionSpecSet, options?: ValidateDefinitionSpecsOptions): void;

package/dist/definitions/validation/validate-input-bindings.d.ts

@@ -0,0 +1,7 @@
+import { type PipelineDefinitionSpec } from "../pipelines/define-pipeline";
+import type { StepDefinitionSpec } from "../steps/define-step";
+import { type DefinitionValidationIssue } from "./validation-issue";
+declare function checkUnboundRequiredInputs(pipelines: readonly PipelineDefinitionSpec[], stepsByKey: Map<string, readonly StepDefinitionSpec[]>): DefinitionValidationIssue[];
+declare function checkBindingTargetFields(pipelines: readonly PipelineDefinitionSpec[], stepsByKey: Map<string, readonly StepDefinitionSpec[]>): DefinitionValidationIssue[];
+declare function checkBindingTypeCompatibility(pipelines: readonly PipelineDefinitionSpec[], stepsByKey: Map<string, readonly StepDefinitionSpec[]>): DefinitionValidationIssue[];
+export { checkBindingTargetFields, checkBindingTypeCompatibility, checkUnboundRequiredInputs, };