@boboddy/sdk 0.2.10-alpha → 0.2.13-alpha

package/dist/boboddy-config-parser.d.ts

@@ -15,11 +15,6 @@ export type BoboddyServiceDefinition = {
         targetPort: number;
         protocol: string;
     };
-    healthcheck: {
-        protocol: string;
-        path: string | null;
-        expectedStatus: number | null;
-    };
 };
 export type BoboddyConfig = {
     commands: BoboddyCommandDefinition[];

package/dist/boboddy-config-parser.js

@@ -147,7 +147,6 @@ var parseServices = (raw) => {
     return [];
   return Object.entries(raw).map(([name, entry]) => {
     const expose = entry.expose ?? {};
-    const healthcheck = entry.healthcheck ?? {};
     const dependsOn = Array.isArray(entry.dependsOn) ? entry.dependsOn.filter((d) => typeof d === "string") : [];
     return {
       name,
@@ -158,11 +157,6 @@ var parseServices = (raw) => {
       expose: {
         targetPort: asNumber(expose.targetPort) ?? 0,
         protocol: asString(expose.protocol) ?? "http"
-      },
-      healthcheck: {
-        protocol: asString(healthcheck.protocol) ?? "http",
-        path: asString(healthcheck.path) ?? null,
-        expectedStatus: asNumber(healthcheck.expectedStatus) ?? null
       }
     };
   });

package/dist/definitions/steps/define-step.d.ts

@@ -29,6 +29,25 @@ type OpenCodeMcpServers = Record<string, {
 type OpenCodePluginEntry = string | [string, Record<string, unknown>];
 /** Full value of the OpenCode `plugin` config field. */
 type OpenCodePlugins = OpenCodePluginEntry[];
+type HealthCheckSeverity = "required" | "warn";
+/**
+ * A single step-declared health check: a real tool call made against the
+ * launched environment before the agent starts working.
+ *
+ * `tool` is a bare name when `mcp` is set (resolved at runtime to
+ * `${mcp}_${tool}`); otherwise it is a flat tool id. `mcp`, when present,
+ * must name a server declared in this step's `mcpServers`.
+ */
+type HealthCheck = {
+    tool: string;
+    mcp?: string;
+    name?: string;
+    args?: Record<string, unknown>;
+    severity?: HealthCheckSeverity;
+    timeoutMs?: number;
+};
+/** Full value of a step's `healthChecks` field. */
+type HealthChecks = HealthCheck[];
 type SignalTypeStr = "string" | "number" | "boolean" | "object" | "array";
 export type DotPaths<T, D extends readonly unknown[] = []> = D["length"] extends 4 ? string : unknown extends T ? string : T extends readonly unknown[] ? string : T extends object ? {
     [K in keyof T & string]: K | (NonNullable<T[K]> extends object ? `${K}.${DotPaths<NonNullable<T[K]>, [...D, unknown]> & string}` : never);
@@ -63,6 +82,7 @@ export type DefineStepInput<TInput extends ZodType = ZodType, TResult extends Zo
     features?: AnyStepFeature[];
     mcpServers?: OpenCodeMcpServers | null;
     plugins?: OpenCodePlugins | null;
+    healthChecks?: HealthChecks | null;
     status?: "draft" | "active";
     executionMode?: "workspace" | "no_workspace";
 };
@@ -94,6 +114,7 @@ export type StepDefinitionSpec = {
     }>;
     opencodeMcpJson: OpenCodeMcpServers | null;
     opencodePluginJson: OpenCodePlugins | null;
+    healthChecksJson: HealthChecks | null;
 };
 export type SignalTypeStrToTs<T extends SignalTypeStr> = T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : T extends "array" ? unknown[] : T extends "object" ? object : unknown;
 export type SignalTypeMapOf<TSignals extends readonly unknown[], TResult> = {
@@ -121,7 +142,7 @@ export declare function defineStep<TInput extends ZodType = ZodType, TResult ext
     sourcePath: string;
     key?: string;
 }> = never[], const TFeatures extends ReadonlyArray<AnyStepFeature> = never[]>(config: Omit<DefineStepInput<TInput, TResult>, "signals" | "features"> & {
-    signals?: TSignals;
+    signals?: TSignals & readonly SignalSpecInput<TResult["_output"]>[];
     features?: TFeatures;
 }): TypedStepDefinitionSpec<TInput["_output"], TResult["_output"] & FeatureResultExtensions<TFeatures>, SignalKeysOf<TSignals> | FeatureSignalKeys<TFeatures>, SignalTypeMapOf<TSignals, TResult["_output"]>>;
 export {};

package/dist/definitions/steps/index.js

@@ -12075,7 +12075,8 @@ ${feature._promptAddition}` : feature._promptAddition;
       }))
     ],
     opencodeMcpJson: config2.mcpServers ?? null,
-    opencodePluginJson: config2.plugins ?? null
+    opencodePluginJson: config2.plugins ?? null,
+    healthChecksJson: config2.healthChecks ?? null
   };
   return spec;
 }

package/dist/definitions/steps/step-definitions-client.d.ts

@@ -48,6 +48,16 @@ declare const buildStepDefinitionsClient: (stepDefinitions: StepDefinitions) =>
             };
         } | unknown;
         opencodePluginJson: Array<string | Array<unknown>> | unknown;
+        healthChecksJson: Array<{
+            tool: string;
+            mcp?: string;
+            name?: string;
+            args?: {
+                [key: string]: unknown;
+            };
+            severity: "required" | "warn";
+            timeoutMs: number;
+        }> | unknown;
         status: "draft" | "active" | "archived";
         signalExtractorDefinitions: Array<{
             id: string;
@@ -102,6 +112,16 @@ declare const buildStepDefinitionsClient: (stepDefinitions: StepDefinitions) =>
             };
         } | unknown;
         opencodePluginJson: Array<string | Array<unknown>> | unknown;
+        healthChecksJson: Array<{
+            tool: string;
+            mcp?: string;
+            name?: string;
+            args?: {
+                [key: string]: unknown;
+            };
+            severity: "required" | "warn";
+            timeoutMs: number;
+        }> | unknown;
         status: "draft" | "active" | "archived";
         signalExtractorDefinitions: Array<{
             id: string;
@@ -161,6 +181,16 @@ declare const buildStepDefinitionsClient: (stepDefinitions: StepDefinitions) =>
             };
         } | unknown;
         opencodePluginJson: Array<string | Array<unknown>> | unknown;
+        healthChecksJson: Array<{
+            tool: string;
+            mcp?: string;
+            name?: string;
+            args?: {
+                [key: string]: unknown;
+            };
+            severity: "required" | "warn";
+            timeoutMs: number;
+        }> | unknown;
         status: "draft" | "active" | "archived";
         signalExtractorDefinitions: Array<{
             id: string;

package/dist/definitions/validation/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./json-schema-paths";
+export * from "./validate-definition-specs";

package/dist/definitions/validation/index.js

@@ -0,0 +1,440 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/definitions/validation/json-schema-paths.ts
+var SEGMENT_PATTERN = /([^.[\]]+)|(\[(\d+)\])/g;
+var NUMERIC_SEGMENT = /^\d+$/;
+var SCALAR_TYPES = new Set([
+  "string",
+  "number",
+  "integer",
+  "boolean",
+  "null"
+]);
+var MAX_REF_HOPS = 16;
+var MAX_CANDIDATES = 64;
+function parseSourcePath(sourcePath) {
+  const trimmed = sourcePath.trim();
+  const normalized = trimmed === "$" ? "" : trimmed.startsWith("$.") ? trimmed.slice(2) : trimmed;
+  if (!normalized)
+    return [];
+  return [...normalized.matchAll(SEGMENT_PATTERN)].map((match) => match[1] ?? match[3]).filter((segment) => Boolean(segment));
+}
+function isSchemaNode(value) {
+  return typeof value === "boolean" || typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asRecord(node) {
+  return typeof node === "boolean" ? null : node;
+}
+function resolveRef(root, ref) {
+  if (!ref.startsWith("#"))
+    return null;
+  const pointer = ref.slice(1);
+  if (pointer === "" || pointer === "/")
+    return root;
+  if (!pointer.startsWith("/"))
+    return null;
+  let current = root;
+  for (const rawToken of pointer.slice(1).split("/")) {
+    const token = rawToken.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (typeof current !== "object" || current === null)
+      return null;
+    current = current[token];
+  }
+  return isSchemaNode(current) ? current : null;
+}
+function flatten(node, root) {
+  const out = [];
+  const queue = [
+    { node, hops: 0 }
+  ];
+  while (queue.length > 0) {
+    const entry = queue.shift();
+    if (!entry)
+      break;
+    if (out.length >= MAX_CANDIDATES)
+      return null;
+    if (entry.hops > MAX_REF_HOPS)
+      return null;
+    const record = asRecord(entry.node);
+    if (!record) {
+      out.push(entry.node);
+      continue;
+    }
+    const ref = record["$ref"];
+    if (typeof ref === "string") {
+      const target = resolveRef(root, ref);
+      if (!target)
+        return null;
+      queue.push({ node: target, hops: entry.hops + 1 });
+      continue;
+    }
+    const branches = ["anyOf", "oneOf", "allOf"].flatMap((keyword) => {
+      const value = record[keyword];
+      return Array.isArray(value) ? value.filter(isSchemaNode) : [];
+    });
+    if (branches.length > 0) {
+      for (const branch of branches) {
+        queue.push({ node: branch, hops: entry.hops + 1 });
+      }
+      continue;
+    }
+    out.push(entry.node);
+  }
+  return out;
+}
+function typeNames(record) {
+  const raw = record["type"];
+  if (typeof raw === "string")
+    return new Set([raw]);
+  if (Array.isArray(raw)) {
+    return new Set(raw.filter((entry) => typeof entry === "string"));
+  }
+  return new Set;
+}
+var INDETERMINATE = { kind: "indeterminate" };
+function stepIntoObject(record, segment) {
+  const properties = asRecord(isSchemaNode(record["properties"]) ? record["properties"] : {});
+  const declared = properties ?? {};
+  const child = declared[segment];
+  if (isSchemaNode(child))
+    return { kind: "child", node: child };
+  if (record["patternProperties"] !== undefined)
+    return INDETERMINATE;
+  if (record["additionalProperties"] !== false)
+    return INDETERMINATE;
+  return {
+    kind: "invalid",
+    reason: "unknown-property",
+    availablePaths: Object.keys(declared).sort()
+  };
+}
+function stepIntoArray(record, segment) {
+  if (!NUMERIC_SEGMENT.test(segment)) {
+    return {
+      kind: "invalid",
+      reason: "not-an-array-index",
+      availablePaths: []
+    };
+  }
+  const prefixItems = record["prefixItems"];
+  if (Array.isArray(prefixItems)) {
+    const positional = prefixItems[Number(segment)];
+    if (isSchemaNode(positional))
+      return { kind: "child", node: positional };
+  }
+  const items = record["items"];
+  if (isSchemaNode(items))
+    return { kind: "child", node: items };
+  return INDETERMINATE;
+}
+function stepInto(node, segment) {
+  const record = asRecord(node);
+  if (!record || Object.keys(record).length === 0)
+    return INDETERMINATE;
+  const types = typeNames(record);
+  const objectLike = types.has("object") || record["properties"] !== undefined || record["patternProperties"] !== undefined || record["additionalProperties"] !== undefined;
+  const arrayLike = types.has("array") || record["items"] !== undefined || record["prefixItems"] !== undefined;
+  const outcomes = [];
+  if (objectLike)
+    outcomes.push(stepIntoObject(record, segment));
+  if (arrayLike)
+    outcomes.push(stepIntoArray(record, segment));
+  if (outcomes.length === 0) {
+    if (types.size > 0 && [...types].every((name) => SCALAR_TYPES.has(name))) {
+      return {
+        kind: "invalid",
+        reason: "scalar-has-no-members",
+        availablePaths: []
+      };
+    }
+    return INDETERMINATE;
+  }
+  return combine(outcomes);
+}
+function combine(outcomes) {
+  const children = outcomes.filter((outcome) => outcome.kind === "child");
+  if (children.length > 0)
+    return children[0] ?? INDETERMINATE;
+  if (outcomes.some((outcome) => outcome.kind === "indeterminate")) {
+    return INDETERMINATE;
+  }
+  const invalid = outcomes.filter((outcome) => outcome.kind === "invalid");
+  const first = invalid[0];
+  if (!first)
+    return INDETERMINATE;
+  return {
+    kind: "invalid",
+    reason: first.reason,
+    availablePaths: [
+      ...new Set(invalid.flatMap((outcome) => outcome.availablePaths))
+    ].sort()
+  };
+}
+function enumeratePaths(node, root, maxDepth = 3, limit = 40) {
+  const out = [];
+  const visit = (current, prefix, depth) => {
+    if (out.length >= limit || depth > maxDepth)
+      return;
+    for (const branch of flatten(current, root) ?? []) {
+      const record = asRecord(branch);
+      const properties = record ? asRecord(isSchemaNode(record["properties"]) ? record["properties"] : {}) : null;
+      if (!properties)
+        continue;
+      for (const [key, child] of Object.entries(properties)) {
+        if (out.length >= limit)
+          return;
+        const path = prefix ? `${prefix}.${key}` : key;
+        out.push(path);
+        if (isSchemaNode(child))
+          visit(child, path, depth + 1);
+      }
+    }
+  };
+  visit(node, "", 1);
+  return [...new Set(out)].sort();
+}
+function resolveSourcePath(schema, sourcePath) {
+  const segments = parseSourcePath(sourcePath);
+  if (segments.length === 0)
+    return { kind: "resolved" };
+  let candidates = [schema];
+  let resolvedPrefix = "";
+  for (const segment of segments) {
+    const expanded = candidates.flatMap((node) => flatten(node, schema) ?? []);
+    if (expanded.length === 0)
+      return { kind: "indeterminate" };
+    const outcome = combine(expanded.map((node) => stepInto(node, segment)));
+    if (outcome.kind === "indeterminate")
+      return { kind: "indeterminate" };
+    if (outcome.kind === "invalid") {
+      const availablePaths = [
+        ...new Set(expanded.flatMap((node) => enumeratePaths(node, schema)))
+      ].sort();
+      return {
+        kind: "invalid",
+        resolvedPrefix,
+        segment,
+        reason: outcome.reason,
+        availablePaths
+      };
+    }
+    candidates = [outcome.node];
+    resolvedPrefix = resolvedPrefix ? `${resolvedPrefix}.${segment}` : segment;
+  }
+  return { kind: "resolved" };
+}
+// src/definitions/validation/validate-definition-specs.ts
+function listPaths(paths, limit = 24) {
+  if (paths.length === 0)
+    return "";
+  if (paths.length <= limit)
+    return paths.join(", ");
+  return `${paths.slice(0, limit).join(", ")}, \u2026 (${String(paths.length - limit)} more)`;
+}
+function quotedOrRoot(prefix) {
+  return prefix ? `"${prefix}"` : "the result root";
+}
+function checkSignalSourcePaths(steps) {
+  const issues = [];
+  for (const step of steps) {
+    const schema = step.resultSchemaJson ?? null;
+    if (!schema)
+      continue;
+    for (const signal of step.signalExtractorDefinitions) {
+      const resolution = resolveSourcePath(schema, signal.sourcePath);
+      if (resolution.kind !== "invalid")
+        continue;
+      const { resolvedPrefix, segment, reason, availablePaths } = resolution;
+      const cause = reason === "not-an-array-index" ? `${quotedOrRoot(resolvedPrefix)} is an array, so "${segment}" can never index it \u2014 array segments must be numeric (e.g. "${resolvedPrefix}[0]")` : reason === "scalar-has-no-members" ? `${quotedOrRoot(resolvedPrefix)} is a scalar, so it has no property "${segment}"` : `${quotedOrRoot(resolvedPrefix)} has no property "${segment}"`;
+      const suffix = availablePaths.length > 0 ? ` Valid sourcePaths ${resolvedPrefix ? `under "${resolvedPrefix}"` : "for this step"}: ${listPaths(availablePaths)}.` : "";
+      issues.push({
+        check: "signal-source-path",
+        message: `Step "${step.key}" declares signal "${signal.key}" with sourcePath ` + `"${signal.sourcePath}", which can never resolve against the step's ` + `result schema: ${cause}.${suffix}`
+      });
+    }
+  }
+  return issues;
+}
+function checkHealthChecks(steps) {
+  const issues = [];
+  for (const step of steps) {
+    const checks = step.healthChecksJson ?? [];
+    if (checks.length === 0)
+      continue;
+    const mcpServerKeys = Object.keys(step.opencodeMcpJson ?? {});
+    const mcpServerKeySet = new Set(mcpServerKeys);
+    checks.forEach((check, index) => {
+      const label = check.name ?? check.tool;
+      const where = `Step "${step.key}" health check #${String(index + 1)} ("${label}")`;
+      if (!check.mcp)
+        return;
+      if (!mcpServerKeySet.has(check.mcp)) {
+        issues.push({
+          check: "health-check-mcp-server",
+          message: `${where} names MCP server "${check.mcp}", but the step declares no ` + `such server in mcpServers. Declared servers: ${mcpServerKeys.length > 0 ? listPaths([...mcpServerKeys].sort()) : "(none)"}.`
+        });
+      }
+      const prefix = `${check.mcp}_`;
+      if (check.tool.startsWith(prefix)) {
+        issues.push({
+          check: "health-check-double-qualified",
+          message: `${where} sets mcp "${check.mcp}" and tool "${check.tool}", which already ` + `starts with "${prefix}". When "mcp" is set, "tool" should be the bare tool ` + `name \u2014 OpenCode resolves it to "${prefix}${check.tool}". Did you mean ` + `tool: "${check.tool.slice(prefix.length)}"?`
+        });
+      }
+    });
+  }
+  return issues;
+}
+function routeTargets(policy) {
+  const keys = [];
+  if (policy.defaultEventType === "route" && typeof policy.defaultEventParamsJson?.["pipelineKey"] === "string") {
+    keys.push(policy.defaultEventParamsJson["pipelineKey"]);
+  }
+  for (const rule of policy.rulesJson.rules) {
+    if (rule.event.type === "route" && typeof rule.event.params?.["pipelineKey"] === "string") {
+      keys.push(rule.event.params["pipelineKey"]);
+    }
+  }
+  return keys;
+}
+function checkRouteTargets(pipelines, knownPipelineKeys) {
+  const issues = [];
+  const known = new Set([
+    ...pipelines.map((pipeline) => pipeline.key),
+    ...knownPipelineKeys
+  ]);
+  for (const pipeline of pipelines) {
+    for (const step of pipeline.steps) {
+      for (const target of routeTargets(step.advancementPolicyDefinition)) {
+        if (known.has(target))
+          continue;
+        issues.push({
+          check: "route-target",
+          message: `Pipeline "${pipeline.key}" step "${step.stepKey}" 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.`
+        });
+      }
+    }
+  }
+  return issues;
+}
+function executionRanks(steps) {
+  const positions = steps.map((step) => step.position);
+  const usable = positions.every((value) => Number.isInteger(value) && value > 0) && new Set(positions).size === positions.length;
+  const indexes = steps.map((_, index) => index);
+  const ordered = usable ? [...indexes].sort((left, right) => (positions[left] ?? 0) - (positions[right] ?? 0)) : indexes;
+  return new Map(ordered.map((index, rank) => [index, rank]));
+}
+function bindingSource(binding) {
+  if (binding.source === "step_signal") {
+    return { stepKey: binding.stepKey, signalKey: binding.signalKey };
+  }
+  if (binding.source === "step_output") {
+    return { stepKey: binding.stepKey, signalKey: null };
+  }
+  return null;
+}
+function declaredSignalKeys(stepKey, stepsByKey, pipelineSteps) {
+  const specs = stepsByKey.get(stepKey);
+  if (!specs || specs.length === 0)
+    return null;
+  const keys = new Set;
+  for (const spec of specs) {
+    for (const signal of spec.signalExtractorDefinitions)
+      keys.add(signal.key);
+  }
+  for (const step of pipelineSteps) {
+    if (step.stepKey !== stepKey)
+      continue;
+    for (const computed of step.computedSignalDefinitions)
+      keys.add(computed.key);
+  }
+  return [...keys];
+}
+function checkSignalBindings(pipelines, stepsByKey) {
+  const issues = [];
+  for (const pipeline of pipelines) {
+    const ranks = executionRanks(pipeline.steps);
+    const order = [...pipeline.steps.keys()].sort((left, right) => (ranks.get(left) ?? 0) - (ranks.get(right) ?? 0)).map((index) => pipeline.steps[index]?.stepKey ?? "");
+    const orderHint = `Steps in "${pipeline.key}", in order: ${order.join(" \u2192 ")}.`;
+    pipeline.steps.forEach((step, index) => {
+      const consumerRank = ranks.get(index) ?? index;
+      const where = `Pipeline "${pipeline.key}" step "${step.stepKey}"`;
+      for (const [field, binding] of Object.entries(step.inputBindingsJson)) {
+        const source = bindingSource(binding);
+        if (!source)
+          continue;
+        const what = source.signalKey ? `binds input "${field}" to signal "${source.signalKey}" of step "${source.stepKey}"` : `binds input "${field}" to the output of step "${source.stepKey}"`;
+        const producerRanks = pipeline.steps.map((candidate, candidateIndex) => candidate.stepKey === source.stepKey ? ranks.get(candidateIndex) ?? candidateIndex : null).filter((rank) => rank !== null);
+        if (producerRanks.length === 0) {
+          issues.push({
+            check: "signal-binding",
+            message: `${where} ${what}, but no step with that key is in the pipeline. ${orderHint}`
+          });
+          continue;
+        }
+        if (!producerRanks.some((rank) => rank < consumerRank)) {
+          issues.push({
+            check: "signal-binding",
+            message: `${where} ${what}, but that step does not run before it, so the ` + `value will never exist. ${orderHint}`
+          });
+          continue;
+        }
+        if (source.signalKey === null)
+          continue;
+        const available = declaredSignalKeys(source.stepKey, stepsByKey, pipeline.steps);
+        if (available === null || available.includes(source.signalKey))
+          continue;
+        issues.push({
+          check: "signal-binding",
+          message: `${where} ${what}, but "${source.stepKey}" declares no such signal. ` + `Signals on "${source.stepKey}": ${available.length > 0 ? listPaths([...available].sort()) : "(none)"}.`
+        });
+      }
+    });
+  }
+  return issues;
+}
+function validateDefinitionSpecs(specs, options = {}) {
+  const stepsByKey = new Map;
+  for (const step of specs.steps) {
+    const existing = stepsByKey.get(step.key);
+    if (existing)
+      existing.push(step);
+    else
+      stepsByKey.set(step.key, [step]);
+  }
+  return [
+    ...checkSignalSourcePaths(specs.steps),
+    ...checkHealthChecks(specs.steps),
+    ...checkRouteTargets(specs.pipelines, options.knownPipelineKeys ?? []),
+    ...checkSignalBindings(specs.pipelines, stepsByKey)
+  ];
+}
+function assertValidDefinitionSpecs(specs, options = {}) {
+  const issues = validateDefinitionSpecs(specs, options);
+  if (issues.length === 0)
+    return;
+  const header = issues.length === 1 ? "Definition validation failed:" : `Definition validation failed with ${String(issues.length)} problems:`;
+  throw new Error([header, ...issues.map((issue) => `  \u2022 ${issue.message}`)].join(`
+`));
+}
+export {
+  validateDefinitionSpecs,
+  resolveSourcePath,
+  parseSourcePath,
+  enumeratePaths,
+  assertValidDefinitionSpecs
+};

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

@@ -0,0 +1,45 @@
+/** A JSON Schema node. `true` / `false` are the boolean schema forms. */
+export type JsonSchemaNode = boolean | {
+    readonly [key: string]: unknown;
+};
+export type PathFailureReason = 
+/** The parent is a closed object with no such property. */
+"unknown-property"
+/** The parent is an array and the segment is not a numeric index. */
+ | "not-an-array-index"
+/** The parent is a scalar, so it has no members at all. */
+ | "scalar-has-no-members";
+export type PathResolution = 
+/** The whole path resolves to a node in the schema. */
+{
+    readonly kind: "resolved";
+}
+/** Neither provably valid nor provably invalid — the schema is too loose. */
+ | {
+    readonly kind: "indeterminate";
+} | {
+    readonly kind: "invalid";
+    /** Dot path of the prefix that did resolve; `""` at the root. */
+    readonly resolvedPrefix: string;
+    /** The first segment that could not resolve. */
+    readonly segment: string;
+    readonly reason: PathFailureReason;
+    /** Paths that DO resolve below `resolvedPrefix`, relative to it. */
+    readonly availablePaths: readonly string[];
+};
+/** Splits a `sourcePath` exactly as the runtime signal extractor does. */
+export declare function parseSourcePath(sourcePath: string): string[];
+/**
+ * Enumerates dot paths that resolve below `node`, for error messages.
+ *
+ * Depth-limited and count-limited: this is a hint for a human reading a push
+ * failure, not an exhaustive schema dump. Arrays are treated as leaves.
+ */
+export declare function enumeratePaths(node: JsonSchemaNode, root: JsonSchemaNode, maxDepth?: number, limit?: number): string[];
+/**
+ * Whether `sourcePath` can resolve against `schema`.
+ *
+ * Pass the step's `resultSchemaJson` as both the node and the document root;
+ * `$ref`s are resolved against the root.
+ */
+export declare function resolveSourcePath(schema: JsonSchemaNode, sourcePath: string): PathResolution;

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

@@ -0,0 +1,25 @@
+import type { PipelineDefinitionSpec } from "../pipelines/define-pipeline";
+import type { StepDefinitionSpec } from "../steps/define-step";
+export type DefinitionSpecSet = {
+    readonly pipelines: readonly PipelineDefinitionSpec[];
+    readonly steps: readonly StepDefinitionSpec[];
+};
+export type ValidateDefinitionSpecsOptions = {
+    /**
+     * Pipeline keys that exist outside this batch — in practice, the keys already
+     * on the server. Route targets may name these as well as keys in
+     * `specs.pipelines`. Omit it and only the batch counts.
+     */
+    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;
+};
+/**
+ * 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. */
+export declare function assertValidDefinitionSpecs(specs: DefinitionSpecSet, options?: ValidateDefinitionSpecsOptions): void;