@boboddy/sdk 0.2.10-alpha → 0.2.12-alpha

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

@@ -121,7 +121,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/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,409 @@
+// @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 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),
+    ...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";
+    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;

package/dist/push/collect-definitions.d.ts

@@ -0,0 +1,21 @@
+import type { PipelineDefinitionSpec } from "../definitions/pipelines";
+import { type DefaultPipelineAssignmentSpec } from "../definitions/pipelines/define-default-pipeline-assignment";
+import type { StepDefinitionSpec } from "../definitions/steps";
+export type CollectedDefinitions = {
+    readonly pipelines: readonly PipelineDefinitionSpec[];
+    /** Deduped by `key@vN`; named exports take precedence over embedded steps. */
+    readonly steps: readonly StepDefinitionSpec[];
+    /** Present only when `default-pipeline-assignment.ts` exists in the directory. */
+    readonly defaultPipelineAssignment: DefaultPipelineAssignmentSpec | null;
+};
+/**
+ * Imports every `.ts`/`.js` file in `dir` (except the push script itself and
+ * `default-pipeline-assignment.ts`) and collects the pipeline and step
+ * definitions they export. The assignment file, when present, is imported and
+ * validated too but returned separately — syncing it needs the server.
+ *
+ * Designed to run on the user's native runtime (bun, node-with-tsx, deno), NOT
+ * inside a `bun --compile`'d binary — that runtime can't resolve scoped package
+ * `exports` field remappings from external user files.
+ */
+export declare function collectDefinitionsFromDirectory(dir: string): Promise<CollectedDefinitions>;

package/dist/push/index.d.ts

@@ -1,2 +1,4 @@
+export { collectDefinitionsFromDirectory } from "./collect-definitions";
+export type { CollectedDefinitions } from "./collect-definitions";
 export { pushFromDirectory } from "./push-from-directory";
 export type { PushFromDirectoryOptions, PushFromDirectoryResult, } from "./push-from-directory";

package/dist/push/index.js

@@ -16784,10 +16784,397 @@ function isDefaultPipelineAssignmentSpec(value) {
     return false;
   return value["_tag"] === "default_pipeline_assignment";
 }
-// src/push/push-from-directory.ts
+// 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 resolveRef2(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 record2 = asRecord(entry.node);
+    if (!record2) {
+      out.push(entry.node);
+      continue;
+    }
+    const ref = record2["$ref"];
+    if (typeof ref === "string") {
+      const target = resolveRef2(root, ref);
+      if (!target)
+        return null;
+      queue.push({ node: target, hops: entry.hops + 1 });
+      continue;
+    }
+    const branches = ["anyOf", "oneOf", "allOf"].flatMap((keyword) => {
+      const value = record2[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(record2) {
+  const raw = record2["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(record2, segment) {
+  const properties = asRecord(isSchemaNode(record2["properties"]) ? record2["properties"] : {});
+  const declared = properties ?? {};
+  const child = declared[segment];
+  if (isSchemaNode(child))
+    return { kind: "child", node: child };
+  if (record2["patternProperties"] !== undefined)
+    return INDETERMINATE;
+  if (record2["additionalProperties"] !== false)
+    return INDETERMINATE;
+  return {
+    kind: "invalid",
+    reason: "unknown-property",
+    availablePaths: Object.keys(declared).sort()
+  };
+}
+function stepIntoArray(record2, segment) {
+  if (!NUMERIC_SEGMENT.test(segment)) {
+    return {
+      kind: "invalid",
+      reason: "not-an-array-index",
+      availablePaths: []
+    };
+  }
+  const prefixItems = record2["prefixItems"];
+  if (Array.isArray(prefixItems)) {
+    const positional = prefixItems[Number(segment)];
+    if (isSchemaNode(positional))
+      return { kind: "child", node: positional };
+  }
+  const items = record2["items"];
+  if (isSchemaNode(items))
+    return { kind: "child", node: items };
+  return INDETERMINATE;
+}
+function stepInto(node, segment) {
+  const record2 = asRecord(node);
+  if (!record2 || Object.keys(record2).length === 0)
+    return INDETERMINATE;
+  const types = typeNames(record2);
+  const objectLike = types.has("object") || record2["properties"] !== undefined || record2["patternProperties"] !== undefined || record2["additionalProperties"] !== undefined;
+  const arrayLike = types.has("array") || record2["items"] !== undefined || record2["prefixItems"] !== undefined;
+  const outcomes = [];
+  if (objectLike)
+    outcomes.push(stepIntoObject(record2, segment));
+  if (arrayLike)
+    outcomes.push(stepIntoArray(record2, 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 record2 = asRecord(branch);
+      const properties = record2 ? asRecord(isSchemaNode(record2["properties"]) ? record2["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 signal2 of step.signalExtractorDefinitions) {
+      const resolution = resolveSourcePath(schema, signal2.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 "${signal2.key}" with sourcePath ` + `"${signal2.sourcePath}", which can never resolve against the step's ` + `result schema: ${cause}.${suffix}`
+      });
+    }
+  }
+  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((pipeline2) => pipeline2.key),
+    ...knownPipelineKeys
+  ]);
+  for (const pipeline2 of pipelines) {
+    for (const step of pipeline2.steps) {
+      for (const target of routeTargets(step.advancementPolicyDefinition)) {
+        if (known.has(target))
+          continue;
+        issues.push({
+          check: "route-target",
+          message: `Pipeline "${pipeline2.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 signal2 of spec.signalExtractorDefinitions)
+      keys.add(signal2.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 pipeline2 of pipelines) {
+    const ranks = executionRanks(pipeline2.steps);
+    const order = [...pipeline2.steps.keys()].sort((left, right) => (ranks.get(left) ?? 0) - (ranks.get(right) ?? 0)).map((index) => pipeline2.steps[index]?.stepKey ?? "");
+    const orderHint = `Steps in "${pipeline2.key}", in order: ${order.join(" \u2192 ")}.`;
+    pipeline2.steps.forEach((step, index) => {
+      const consumerRank = ranks.get(index) ?? index;
+      const where = `Pipeline "${pipeline2.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 = pipeline2.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, pipeline2.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),
+    ...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((issue2) => `  \u2022 ${issue2.message}`)].join(`
+`));
+}
+// src/push/collect-definitions.ts
 import { existsSync, readdirSync } from "fs";
 import { join, resolve } from "path";
 import { pathToFileURL } from "url";
+var PUSH_SCRIPT_NAMES = new Set(["push.ts", "push.mjs", "push.js"]);
 function isStepDefinitionSpec(value) {
   if (typeof value !== "object" || value === null)
     return false;
@@ -16800,38 +17187,21 @@ function isPipelineDefinitionSpec(value) {
   const obj = value;
   return typeof obj["key"] === "string" && typeof obj["name"] === "string" && typeof obj["version"] === "number" && Array.isArray(obj["steps"]);
 }
-function extractRoutePipelineKeys(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;
+async function importModule(path) {
+  return await import(pathToFileURL(path).href);
 }
-var PUSH_SCRIPT_NAMES = new Set(["push.ts", "push.mjs", "push.js"]);
-async function pushFromDirectory(dir, opts) {
-  const log = opts.log ?? ((msg) => {
-    console.warn(msg);
-  });
-  const headers = { Authorization: `Bearer ${opts.accessToken}` };
+async function collectDefinitionsFromDirectory(dir) {
   const absDir = resolve(dir);
-  const allFiles = readdirSync(absDir).filter((f) => f.endsWith(".ts") || f.endsWith(".js"));
-  const hasAssignmentFile = existsSync(join(absDir, DEFAULT_PIPELINE_ASSIGNMENT_FILENAME));
-  const sourceFiles = allFiles.filter((f) => !PUSH_SCRIPT_NAMES.has(f) && f !== DEFAULT_PIPELINE_ASSIGNMENT_FILENAME);
-  const pipelineSpecs = [];
+  const allFiles = readdirSync(absDir).filter((file2) => file2.endsWith(".ts") || file2.endsWith(".js"));
+  const sourceFiles = allFiles.filter((file2) => !PUSH_SCRIPT_NAMES.has(file2) && file2 !== DEFAULT_PIPELINE_ASSIGNMENT_FILENAME);
+  const pipelines = [];
   const stepMap = new Map;
   for (const file2 of sourceFiles) {
-    const absPath = join(absDir, file2);
-    const mod = await import(pathToFileURL(absPath).href);
+    const mod = await importModule(join(absDir, file2));
     for (const [exportName, value] of Object.entries(mod)) {
       if (exportName === "default") {
-        if (isPipelineDefinitionSpec(value)) {
-          pipelineSpecs.push(value);
-        }
+        if (isPipelineDefinitionSpec(value))
+          pipelines.push(value);
         continue;
       }
       if (isStepDefinitionSpec(value)) {
@@ -16839,38 +17209,48 @@ async function pushFromDirectory(dir, opts) {
       }
     }
   }
-  for (const spec of pipelineSpecs) {
+  for (const spec of pipelines) {
     for (const embedded of spec._stepDefinitions ?? []) {
       const key = `${embedded.key}@v${String(embedded.version)}`;
-      if (!stepMap.has(key)) {
+      if (!stepMap.has(key))
         stepMap.set(key, embedded);
-      }
     }
   }
-  log(`Found ${String(pipelineSpecs.length)} pipeline(s) and ${String(stepMap.size)} step(s).`);
+  return {
+    pipelines,
+    steps: [...stepMap.values()],
+    defaultPipelineAssignment: await collectDefaultPipelineAssignment(absDir)
+  };
+}
+async function collectDefaultPipelineAssignment(absDir) {
+  const path = join(absDir, DEFAULT_PIPELINE_ASSIGNMENT_FILENAME);
+  if (!existsSync(path))
+    return null;
+  const mod = await importModule(path);
+  const spec = mod["default"];
+  if (!isDefaultPipelineAssignmentSpec(spec)) {
+    throw new Error(`${DEFAULT_PIPELINE_ASSIGNMENT_FILENAME} must have a default export produced by defaultPipelineAssignment(({ assign, skip, ... }) => ({ default: ..., rules: [...] })). Got: ${typeof spec}`);
+  }
+  return spec;
+}
+// src/push/push-from-directory.ts
+async function pushFromDirectory(dir, opts) {
+  const log = opts.log ?? ((msg) => {
+    console.warn(msg);
+  });
+  const headers = { Authorization: `Bearer ${opts.accessToken}` };
+  const collected = await collectDefinitionsFromDirectory(dir);
+  const { pipelines, steps } = collected;
+  log(`Found ${String(pipelines.length)} pipeline(s) and ${String(steps.length)} step(s).`);
   const stepsClient = createStepDefinitionsClient(opts.baseUrl);
-  for (const spec of stepMap.values()) {
+  const pipelinesClient = createPipelineDefinitionsClient(opts.baseUrl);
+  const serverPipelineKeys = pipelines.length > 0 ? (await pipelinesClient.listByProjectId(opts.projectId, { headers })).map((pipeline2) => pipeline2.key) : [];
+  assertValidDefinitionSpecs({ pipelines, steps }, { knownPipelineKeys: serverPipelineKeys });
+  for (const spec of steps) {
     await stepsClient.upsertFromSpec(opts.projectId, spec, { headers });
     log(`\u2713 step ${spec.key} v${String(spec.version)} \u2192 upserted`);
   }
-  const pipelinesClient = createPipelineDefinitionsClient(opts.baseUrl);
-  let pushedPipelinesCount = 0;
-  if (pipelineSpecs.length > 0) {
-    const existingPipelines = await pipelinesClient.listByProjectId(opts.projectId, { headers });
-    const knownPipelineKeys = new Set([
-      ...pipelineSpecs.map((s) => s.key),
-      ...existingPipelines.map((p) => p.key)
-    ]);
-    for (const spec of pipelineSpecs) {
-      for (const step of spec.steps) {
-        const routeKeys = extractRoutePipelineKeys(step.advancementPolicyDefinition);
-        for (const routeKey of routeKeys) {
-          if (!knownPipelineKeys.has(routeKey)) {
-            throw new Error(`Pipeline "${spec.key}" step "${step.stepKey}" routes to pipeline "${routeKey}", but no pipeline with that key was found on the server or in the current push batch. Push the target pipeline first.`);
-          }
-        }
-      }
-    }
+  if (pipelines.length > 0) {
     const serverSteps = await stepsClient.listByProjectId(opts.projectId, {
       headers
     });
@@ -16879,27 +17259,17 @@ async function pushFromDirectory(dir, opts) {
       key: s.key,
       version: s.version
     }));
-    for (const spec of pipelineSpecs) {
+    for (const spec of pipelines) {
       await pipelinesClient.upsertFromSpec(opts.projectId, spec, stepDefs, {
         headers
       });
       log(`\u2713 pipeline ${spec.key} v${String(spec.version)} \u2192 upserted`);
     }
-    pushedPipelinesCount = pipelineSpecs.length;
-  }
-  let syncedDefaultPipelineAssignment = false;
-  if (hasAssignmentFile) {
-    const assignmentFilePath = join(absDir, DEFAULT_PIPELINE_ASSIGNMENT_FILENAME);
-    const assignmentMod = await import(pathToFileURL(assignmentFilePath).href);
-    const assignmentSpec = assignmentMod["default"];
-    if (!isDefaultPipelineAssignmentSpec(assignmentSpec)) {
-      throw new Error(`${DEFAULT_PIPELINE_ASSIGNMENT_FILENAME} must have a default export produced by defaultPipelineAssignment(({ assign, skip, ... }) => ({ default: ..., rules: [...] })). Got: ${typeof assignmentSpec}`);
-    }
-    syncedDefaultPipelineAssignment = await syncDefaultPipelineAssignment(assignmentSpec, opts, headers, pipelinesClient, log);
   }
+  const syncedDefaultPipelineAssignment = collected.defaultPipelineAssignment ? await syncDefaultPipelineAssignment(collected.defaultPipelineAssignment, opts, headers, pipelinesClient, log) : false;
   return {
-    pushedSteps: stepMap.size,
-    pushedPipelines: pushedPipelinesCount,
+    pushedSteps: steps.length,
+    pushedPipelines: pipelines.length,
     syncedDefaultPipelineAssignment
   };
 }
@@ -16921,7 +17291,7 @@ async function syncDefaultPipelineAssignment(spec, opts, headers, pipelinesClien
   }
   for (const key of referencedKeys) {
     if (!pipelineKeyToId.has(key)) {
-      throw new Error(`default-pipeline-assignment.ts references pipeline "${key}", but no pipeline with that key was found on the server. Push the pipeline first with \`boboddy pipelines push\`.`);
+      throw new Error(`${DEFAULT_PIPELINE_ASSIGNMENT_FILENAME} references pipeline "${key}", ` + `but no pipeline with that key was found on the server. ` + `Push the pipeline first with \`boboddy pipelines push\`.`);
     }
   }
   const linearPipelineDefinitionId = pipelineKeyToId.get(serialized.linearPipelineDefinitionKey);
@@ -16933,7 +17303,7 @@ async function syncDefaultPipelineAssignment(spec, opts, headers, pipelinesClien
       const pKey = rule.event.params["pipelineKey"];
       const pId = pipelineKeyToId.get(pKey);
       if (!pId) {
-        throw new Error(`default-pipeline-assignment.ts assign() references pipeline "${pKey}" which was not found on the server.`);
+        throw new Error(`${DEFAULT_PIPELINE_ASSIGNMENT_FILENAME} assign() references pipeline "${pKey}" ` + `which was not found on the server.`);
       }
       return {
         ...rule,
@@ -16971,5 +17341,6 @@ async function syncDefaultPipelineAssignment(spec, opts, headers, pipelinesClien
   return true;
 }
 export {
-  pushFromDirectory
+  pushFromDirectory,
+  collectDefinitionsFromDirectory
 };

package/dist/push/push-from-directory.d.ts

@@ -14,12 +14,18 @@ export interface PushFromDirectoryResult {
 /**
  * Imports every `.ts`/`.js` file in `dir` (except the push script itself and
  * `default-pipeline-assignment.ts`), collects all pipeline and step
- * definitions, then upserts them via the strongly-typed SDK clients.
+ * definitions, validates them, then upserts them via the strongly-typed SDK
+ * clients.
  *
  * If `default-pipeline-assignment.ts` is present, it is imported separately
  * after pipelines are pushed, and the project default pipeline assignment is
  * updated on the server.
  *
+ * Collection is `collectDefinitionsFromDirectory` (offline, no token) and
+ * validation is `validateDefinitionSpecs` (pure). Both run before the first
+ * mutating request, so a batch with a dead signal `sourcePath`, a dangling
+ * route target, or a backwards signal binding fails without half-pushing.
+ *
  * Designed to run on the user's native runtime (bun, node-with-tsx, deno),
  * NOT inside a `bun --compile`'d binary — that runtime can't resolve scoped
  * package `exports` field remappings from external user files.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@boboddy/sdk",
-  "version": "0.2.10-alpha",
+  "version": "0.2.12-alpha",
   "type": "module",
   "exports": {
     ".": {
@@ -28,6 +28,10 @@
       "import": "./dist/definitions/advancement-policies/index.js",
       "types": "./dist/definitions/advancement-policies/index.d.ts"
     },
+    "./definitions/validation": {
+      "import": "./dist/definitions/validation/index.js",
+      "types": "./dist/definitions/validation/index.d.ts"
+    },
     "./defaults": {
       "import": "./dist/defaults/index.js",
       "types": "./dist/defaults/index.d.ts"