@hyperdrive.bot/paseo-protocol 0.3.42 → 0.3.44

package/dist/workflow/compile.js

@@ -0,0 +1,172 @@
+import { defaultLoopParams, validateLoopParams } from "../fleet/params.js";
+import { createWorkflowTokenPattern, renderWorkflowInputValue, SUBSTITUTABLE_STEP_FIELDS, validateWorkflowDefinition, WorkflowDefinitionError, } from "./definition.js";
+/**
+ * Compile one definition against one set of input values.
+ *
+ * Validates BEFORE it emits, and reports EVERY issue in one throw rather than stopping
+ * at the first: a definition can carry a bad input value, an undeclared token and an
+ * unknown agent name simultaneously, and three sequential throws would hide the second
+ * and third until the first is fixed. On any issue nothing is returned and no partial
+ * graph is observable.
+ *
+ * @throws {WorkflowDefinitionError} carrying the union of the value issues, the
+ *   definition issues, and the unresolved-reference issues this module adds.
+ */
+export function compileWorkflowDefinition(args) {
+    const { definition, session, values } = args;
+    // Defaults on the LEFT so a supplied value always wins over a declared default.
+    // `defaultLoopParams` only emits a key when the field's `default` parses as a
+    // `LoopParamValue`, so a field with no default contributes nothing here - which is
+    // exactly the gap the declared-but-unresolved issue below closes.
+    const merged = {
+        ...defaultLoopParams({ fields: definition.inputs }),
+        ...values,
+    };
+    const declaredKeys = new Set(definition.inputs.map((field) => field.key));
+    const valueIssues = validateLoopParams({ fields: definition.inputs }, merged);
+    // Each of the three failure shapes has exactly ONE reporter. A required input that is
+    // missing is already located at `inputs[<key>]`, so the reference pass below stays
+    // silent about it rather than restating the same root cause at every step that
+    // mentions it.
+    const reportedKeys = new Set(valueIssues.map((issue) => issue.key));
+    const rendered = definition.steps.map((step) => renderStepFields({ step, values: merged, declaredKeys, reportedKeys }));
+    const issues = [
+        ...valueIssues.map((issue) => ({
+            path: `inputs[${issue.key}]`,
+            message: issue.message,
+        })),
+        // Deliberately duplicated with `parseWorkflowDefinition`, and it stays: the two
+        // guard different entry points - a CLI that parsed a file, versus any caller
+        // invoking this compiler directly with a hand-built object.
+        ...validateWorkflowDefinition(definition),
+        ...rendered.flatMap((entry) => entry.issues),
+    ];
+    if (issues.length > 0) {
+        throw new WorkflowDefinitionError(issues);
+    }
+    const graph = {
+        // What the manager's `title ?? graph.goal` default reads, so `--title` stays optional.
+        goal: definition.name,
+        // Ported ballast: the CLI's reusable master-prompt template. Zero readers on
+        // 25fe57635 (only the TS interface and the Zod schema mention it).
+        masterPrompt: "",
+        metadata: {
+            // Emitted EMPTY on purpose. `resolveExecutionLayers` honours a declared list only
+            // when non-empty, then falls through to Kahn layering over `dependencies`. A
+            // precomputed list here would be a second derivation that can disagree with `needs`.
+            executionLayers: [],
+            // Upper bound, not a cap - nothing enforces it. Zero readers.
+            maxParallelism: definition.steps.length,
+            totalTasks: definition.steps.length,
+            // Unknown. Zero readers.
+            estimatedDuration: 0,
+            // Per-file task generation is a CLI concept with no paseo reader.
+            perFileMode: false,
+            // `storyFormat` and `totalFiles` are omitted, not defaulted: both are optional and
+            // neither has a definition-side vocabulary, so `false`/`0` would be a claim where
+            // an absent key is honestly "not specified".
+        },
+        // Ambient run identity, supplied by the caller so this stays a pure function.
+        // `outputDirectory` has zero readers on 25fe57635 but is schema-required.
+        session,
+        tasks: rendered.map(buildTask),
+    };
+    // Shallow copy: a caller mutating the returned presets must not reach back into the
+    // definition. Populating them onto the wire is Story 3.3's job.
+    return { graph, agentPresets: { ...definition.agents } };
+}
+/** Substitute every token in one field's text, iterating Story 3.1's scanner. */
+function substituteTokens(args) {
+    const issues = [];
+    // A FRESH pattern per call. A module-level `/g` regex carries `lastIndex` between
+    // calls, which would make the result depend on scan order.
+    const text = args.text.replace(createWorkflowTokenPattern(), (raw, body) => {
+        const name = body.trim();
+        if (!args.declaredKeys.has(name)) {
+            // Undeclared, or malformed (a body that is not a bare identifier is never a
+            // declared key). `validateWorkflowDefinition` already reports both, located at
+            // this same path, so reporting again here would double-count one mistake. The
+            // raw token is returned unrendered; the union above is non-empty, so the caller
+            // throws and this interim string is never observable.
+            return raw;
+        }
+        const value = args.values[name];
+        if (value === undefined) {
+            if (args.reportedKeys.has(name)) {
+                // Already located at `inputs[<name>]` by the value pass (required and missing).
+                return raw;
+            }
+            // Declared, referenced, and has no value. `validateLoopParams` cannot catch this
+            // (a non-required field with no value is legal to it) and Story 3.1 cannot
+            // (the input IS declared). Only the compiler knows the token is referenced.
+            // Reporting it is what keeps the token from rendering as "" or "undefined".
+            issues.push({
+                path: args.path,
+                message: `step "${args.stepId}" references ${raw}, which is a declared input with no value: supply --input ${name}=... or give the field a default`,
+            });
+            return raw;
+        }
+        return renderWorkflowInputValue(value);
+    });
+    return { text, issues };
+}
+/**
+ * Render every substitutable field of one step.
+ *
+ * Iterates `SUBSTITUTABLE_STEP_FIELDS` rather than a second hard-coded list, so this
+ * module and Story 3.1's validator cannot disagree about which fields accept a token.
+ * `id` and `needs` are absent from that constant on purpose: a topology that depends on
+ * runtime values could not be validated at authoring time.
+ */
+function renderStepFields(args) {
+    const fields = {};
+    const issues = [];
+    for (const field of SUBSTITUTABLE_STEP_FIELDS) {
+        const text = args.step[field];
+        if (text === undefined) {
+            continue;
+        }
+        const result = substituteTokens({
+            text,
+            values: args.values,
+            declaredKeys: args.declaredKeys,
+            reportedKeys: args.reportedKeys,
+            path: `steps[${args.step.id}].${field}`,
+            stepId: args.step.id,
+        });
+        fields[field] = result.text;
+        issues.push(...result.issues);
+    }
+    return { step: args.step, fields, issues };
+}
+/** One task node per step, in definition order. */
+function buildTask(rendered) {
+    const { fields, step } = rendered;
+    // `step.id` never carries a token, so a fallback that came from it needs no rendering.
+    const title = fields.title ?? step.id;
+    return {
+        id: step.id, // never substituted
+        dependencies: step.needs, // never substituted
+        // Falls back through the SUBSTITUTED title before the id, so a token in the title
+        // reaches the description rather than the description inheriting an unrendered one.
+        description: fields.description ?? title,
+        // `prompt` is required by `WorkflowStepSchema`, so `renderStepFields` always renders
+        // it; the fallback exists only to keep the expression total.
+        prompt: fields.prompt ?? step.prompt,
+        title,
+        // `""` is the schema-satisfying empty, and `outputFile` has no reader anywhere.
+        outputFile: fields.outputFile ?? "",
+        // Ported ballast from the bmad-workflow CLI. Verified zero readers on 25fe57635:
+        // the only occurrences of `parallelizable` in the tree are its two declarations.
+        parallelizable: true,
+        // Same: no reader. The definition has no duration vocabulary and this epic does not
+        // invent one.
+        estimatedMinutes: 0,
+        // Conditional spread so the key is ABSENT rather than present-with-`undefined`: the
+        // schema says optional, and absent is the honest encoding of "this step names no agent".
+        ...(step.agent === undefined ? {} : { agentType: step.agent }),
+        // `targetFiles` is never emitted: the definition has no vocabulary for it and this
+        // epic does not invent one.
+    };
+}
+//# sourceMappingURL=compile.js.map

package/dist/workflow/definition.d.ts

@@ -0,0 +1,134 @@
+import { z } from "zod";
+import { type LoopParamValue } from "../fleet/params.js";
+/** Step fields that accept `{{VAR}}` substitution. NEVER `id` and NEVER `needs`: a
+ *  topology that depends on runtime values could not be validated at parse time. */
+export declare const SUBSTITUTABLE_STEP_FIELDS: readonly ["prompt", "title", "description", "outputFile"];
+export type SubstitutableStepField = (typeof SUBSTITUTABLE_STEP_FIELDS)[number];
+export interface WorkflowDefinitionIssue {
+    /** `steps[<id>].<field>` | `steps[#<index>]` | `inputs[<key>]` | `agents[<name>]` | `steps` | `version` */
+    path: string;
+    message: string;
+}
+export declare class WorkflowDefinitionError extends Error {
+    readonly issues: WorkflowDefinitionIssue[];
+    constructor(issues: WorkflowDefinitionIssue[]);
+}
+/**
+ * One step. `.strict()` rather than Zod's default strip: a key this version does not
+ * support must be REJECTED by name, because a silently stripped `forEach:` reads as
+ * configured and behaves as absent.
+ */
+export declare const WorkflowStepSchema: z.ZodObject<{
+    id: z.ZodString;
+    needs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    agent: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    outputFile: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * The whole definition. `inputs` reuses the Loops parameter vocabulary rather than
+ * declaring a second one; a new input type is added in ../fleet/params.ts, never here.
+ */
+export declare const WorkflowDefinitionSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    name: z.ZodString;
+    inputs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            enum: "enum";
+            "string-list": "string-list";
+        }>;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodDefault<z.ZodBoolean>;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        default: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>>;
+    agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        provider: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        modeId: z.ZodOptional<z.ZodString>;
+        systemPrompt: z.ZodOptional<z.ZodString>;
+        thinkingOptionId: z.ZodOptional<z.ZodString>;
+        approvalPolicy: z.ZodOptional<z.ZodString>;
+        sandboxMode: z.ZodOptional<z.ZodString>;
+        networkAccess: z.ZodOptional<z.ZodBoolean>;
+        webSearch: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        needs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        agent: z.ZodOptional<z.ZodString>;
+        prompt: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        outputFile: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type WorkflowStep = z.infer<typeof WorkflowStepSchema>;
+export type WorkflowDefinition = z.infer<typeof WorkflowDefinitionSchema>;
+/** A `{{ ... }}` occurrence, matched LOOSELY on purpose: a malformed token must be
+ *  reported, not silently ignored and passed through into the rendered prompt.
+ *  Fresh instance per call so `lastIndex` is never shared. */
+export declare function createWorkflowTokenPattern(): RegExp;
+export interface WorkflowTokenMatch {
+    /** The full literal token as written, e.g. `{{ PRD }}`. */
+    raw: string;
+    /** The trimmed body, e.g. `PRD`. */
+    name: string;
+    /** True when `name` is a bare identifier, i.e. inside the closed grammar. */
+    wellFormed: boolean;
+}
+/**
+ * Every `{{ ... }}` occurrence in `text`, in source order.
+ *
+ * The grammar is closed: `{{`, optional whitespace, ONE identifier, optional
+ * whitespace, `}}`. No dotted paths, no filters, no expressions, no nesting. Anything
+ * else comes back with `wellFormed: false` so the caller can report it rather than let
+ * it survive into a rendered prompt as literal text.
+ */
+export declare function scanWorkflowTokens(text: string): WorkflowTokenMatch[];
+/**
+ * Render one input value for interpolation into a PROMPT.
+ *
+ * Deliberately NOT `loopParamsToEnv`: booleans render as "true"/"false" here and
+ * "1"/"0" there, because the consumer here is an LLM prompt and there a bash env
+ * var. The two renderers share no consumer, so the divergence is safe; the spec
+ * asserts them side by side so it stays deliberate.
+ */
+export declare function renderWorkflowInputValue(value: LoopParamValue): string;
+/**
+ * Semantic checks Zod cannot see: ids, edges, cycles, agent names and tokens.
+ *
+ * Takes an already-parsed definition, returns EVERY issue, never throws and never
+ * returns early. Each pass is separate so the issue order is stable and each rule is
+ * readable on its own.
+ */
+export declare function validateWorkflowDefinition(definition: WorkflowDefinition): WorkflowDefinitionIssue[];
+export type WorkflowDefinitionParseResult = {
+    ok: true;
+    definition: WorkflowDefinition;
+} | {
+    ok: false;
+    issues: WorkflowDefinitionIssue[];
+};
+/**
+ * Parse an untrusted object into a definition.
+ *
+ * Never throws. `WorkflowDefinitionError` exists for callers that want a throwing
+ * boundary; this function returns a discriminated result instead.
+ *
+ * `version` is checked BY HAND before the Zod parse. A file declaring a version this
+ * build does not know has a shape this build does not know, so parsing it against the
+ * v1 schema buries the one useful fact under a cascade of field errors. `z.literal(1)`
+ * stays in the schema as the structural guard for direct `.parse` callers.
+ */
+export declare function parseWorkflowDefinition(raw: unknown): WorkflowDefinitionParseResult;
+//# sourceMappingURL=definition.d.ts.map

package/dist/workflow/definition.js

@@ -0,0 +1,362 @@
+import { z } from "zod";
+import { LoopParamFieldSchema } from "../fleet/params.js";
+import { WorkflowAgentPresetSchema } from "../messages.js";
+/**
+ * A workflow DEFINITION: the authored, versioned description of a pipeline, as opposed
+ * to a `TaskGraph`, which is one pre-built run of one.
+ *
+ * The point of this module is that a definition is either provably valid or carries a
+ * list of located errors. Every check reports EVERY issue in one pass, mirroring
+ * `validateLoopParams` in ../fleet/params.ts, so an author fixes a file once instead of
+ * resubmitting to discover the next mistake.
+ *
+ * Pure by construction: no I/O, no `node:` imports, no clock, no RNG. The same input
+ * always produces the same issue list in the same order.
+ */
+// Same rule as `LoopParamFieldSchema.key` in ../fleet/params.ts. Duplicated (not
+// imported) because that module does not export the pattern and this epic's
+// compatibility requirements forbid editing it. The drift guard is a test that runs
+// one sample table through both schemas and asserts identical accept/reject.
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** The only definition version this build understands. */
+const SUPPORTED_VERSION = 1;
+/** Step fields that accept `{{VAR}}` substitution. NEVER `id` and NEVER `needs`: a
+ *  topology that depends on runtime values could not be validated at parse time. */
+export const SUBSTITUTABLE_STEP_FIELDS = ["prompt", "title", "description", "outputFile"];
+export class WorkflowDefinitionError extends Error {
+    constructor(issues) {
+        super(`Workflow definition is invalid: ${issues.map((i) => `${i.path}: ${i.message}`).join("; ")}`);
+        this.issues = issues;
+        this.name = "WorkflowDefinitionError";
+    }
+}
+/**
+ * One step. `.strict()` rather than Zod's default strip: a key this version does not
+ * support must be REJECTED by name, because a silently stripped `forEach:` reads as
+ * configured and behaves as absent.
+ */
+export const WorkflowStepSchema = z
+    .object({
+    id: z.string().trim().min(1).regex(IDENTIFIER, "step id must be a valid identifier"),
+    needs: z.array(z.string()).default([]),
+    agent: z.string().optional(),
+    prompt: z.string().min(1),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    outputFile: z.string().optional(),
+})
+    .strict();
+/**
+ * The whole definition. `inputs` reuses the Loops parameter vocabulary rather than
+ * declaring a second one; a new input type is added in ../fleet/params.ts, never here.
+ */
+export const WorkflowDefinitionSchema = z
+    .object({
+    version: z.literal(1),
+    name: z.string().trim().min(1),
+    inputs: z.array(LoopParamFieldSchema).default([]),
+    agents: z.record(z.string(), WorkflowAgentPresetSchema).default({}),
+    steps: z.array(WorkflowStepSchema).min(1),
+})
+    .strict();
+/** A `{{ ... }}` occurrence, matched LOOSELY on purpose: a malformed token must be
+ *  reported, not silently ignored and passed through into the rendered prompt.
+ *  Fresh instance per call so `lastIndex` is never shared. */
+export function createWorkflowTokenPattern() {
+    return /\{\{([^}]*)\}\}/g;
+}
+/**
+ * Every `{{ ... }}` occurrence in `text`, in source order.
+ *
+ * The grammar is closed: `{{`, optional whitespace, ONE identifier, optional
+ * whitespace, `}}`. No dotted paths, no filters, no expressions, no nesting. Anything
+ * else comes back with `wellFormed: false` so the caller can report it rather than let
+ * it survive into a rendered prompt as literal text.
+ */
+export function scanWorkflowTokens(text) {
+    const matches = [];
+    for (const match of text.matchAll(createWorkflowTokenPattern())) {
+        const name = (match[1] ?? "").trim();
+        matches.push({ raw: match[0], name, wellFormed: IDENTIFIER.test(name) });
+    }
+    return matches;
+}
+/**
+ * Render one input value for interpolation into a PROMPT.
+ *
+ * Deliberately NOT `loopParamsToEnv`: booleans render as "true"/"false" here and
+ * "1"/"0" there, because the consumer here is an LLM prompt and there a bash env
+ * var. The two renderers share no consumer, so the divergence is safe; the spec
+ * asserts them side by side so it stays deliberate.
+ */
+export function renderWorkflowInputValue(value) {
+    if (Array.isArray(value)) {
+        return value.join(",");
+    }
+    if (typeof value === "boolean") {
+        return value ? "true" : "false";
+    }
+    return String(value);
+}
+/**
+ * Semantic checks Zod cannot see: ids, edges, cycles, agent names and tokens.
+ *
+ * Takes an already-parsed definition, returns EVERY issue, never throws and never
+ * returns early. Each pass is separate so the issue order is stable and each rule is
+ * readable on its own.
+ */
+export function validateWorkflowDefinition(definition) {
+    return [
+        ...collectDuplicateStepIds(definition.steps),
+        ...collectUnknownNeeds(definition.steps),
+        ...collectCycle(definition.steps),
+        ...collectUnknownAgents(definition),
+        ...collectTokenIssues(definition),
+    ];
+}
+/** One issue per repeated id, not one per extra occurrence. */
+function collectDuplicateStepIds(steps) {
+    const seen = new Set();
+    const reported = new Set();
+    const issues = [];
+    for (const step of steps) {
+        if (!seen.has(step.id)) {
+            seen.add(step.id);
+            continue;
+        }
+        if (reported.has(step.id)) {
+            continue;
+        }
+        reported.add(step.id);
+        issues.push({ path: "steps", message: `duplicate step id: "${step.id}"` });
+    }
+    return issues;
+}
+function collectUnknownNeeds(steps) {
+    const known = new Set(steps.map((step) => step.id));
+    const issues = [];
+    for (const step of steps) {
+        for (const need of step.needs) {
+            if (known.has(need)) {
+                continue;
+            }
+            issues.push({
+                path: `steps[${step.id}].needs`,
+                message: `step "${step.id}" needs "${need}", which is not a step in this definition`,
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Kahn-style layering, mirroring `computeLayersFromDependencies`
+ * (packages/server/src/server/workflow/workflow-progress.ts:255-283) including its rule
+ * that a dependency outside the graph counts as already satisfied. Honouring that rule
+ * is what keeps an unknown `needs` target from being double-reported as a cycle.
+ *
+ * Collects an issue where the server function throws, because this pass must report
+ * every issue in one run.
+ */
+function collectCycle(steps) {
+    const byId = new Map(steps.map((step) => [step.id, step]));
+    const resolved = new Set();
+    let remaining = steps.map((step) => step.id);
+    while (remaining.length > 0) {
+        const layer = remaining.filter((id) => {
+            const node = byId.get(id);
+            if (!node) {
+                return false;
+            }
+            // A dependency outside the graph is treated as already satisfied.
+            return node.needs.every((dep) => resolved.has(dep) || !byId.has(dep));
+        });
+        if (layer.length === 0) {
+            const unresolved = [...new Set(remaining)].sort();
+            return [
+                {
+                    path: "steps",
+                    message: `steps form a dependency cycle: ${unresolved.join(", ")}`,
+                },
+            ];
+        }
+        for (const id of layer) {
+            resolved.add(id);
+        }
+        remaining = remaining.filter((id) => !resolved.has(id));
+    }
+    return [];
+}
+function collectUnknownAgents(definition) {
+    const declared = Object.keys(definition.agents).sort();
+    const known = declared.length === 0 ? "no agents are declared" : `declared agents: ${declared.join(", ")}`;
+    const issues = [];
+    for (const step of definition.steps) {
+        const agent = step.agent;
+        if (agent === undefined || Object.hasOwn(definition.agents, agent)) {
+            continue;
+        }
+        issues.push({
+            path: `steps[${step.id}].agent`,
+            message: `step "${step.id}" names agent "${agent}", which is not declared (${known})`,
+        });
+    }
+    return issues;
+}
+function collectTokenIssues(definition) {
+    const declared = new Set(definition.inputs.map((field) => field.key));
+    const issues = [];
+    for (const step of definition.steps) {
+        for (const field of SUBSTITUTABLE_STEP_FIELDS) {
+            const text = step[field];
+            if (text === undefined) {
+                continue;
+            }
+            issues.push(...collectFieldTokenIssues(step.id, field, text, declared));
+        }
+    }
+    return issues;
+}
+function collectFieldTokenIssues(stepId, field, text, declared) {
+    const path = `steps[${stepId}].${field}`;
+    const issues = [];
+    for (const token of scanWorkflowTokens(text)) {
+        if (!token.wellFormed) {
+            issues.push({
+                path,
+                message: `step "${stepId}" has a malformed token ${token.raw} in ${field}: only {{NAME}} naming a declared input is supported`,
+            });
+            continue;
+        }
+        if (declared.has(token.name)) {
+            continue;
+        }
+        issues.push({
+            path,
+            message: `step "${stepId}" references ${token.raw} in ${field}, which is not a declared input`,
+        });
+    }
+    return issues;
+}
+/**
+ * Parse an untrusted object into a definition.
+ *
+ * Never throws. `WorkflowDefinitionError` exists for callers that want a throwing
+ * boundary; this function returns a discriminated result instead.
+ *
+ * `version` is checked BY HAND before the Zod parse. A file declaring a version this
+ * build does not know has a shape this build does not know, so parsing it against the
+ * v1 schema buries the one useful fact under a cascade of field errors. `z.literal(1)`
+ * stays in the schema as the structural guard for direct `.parse` callers.
+ */
+export function parseWorkflowDefinition(raw) {
+    const versionIssue = checkVersionGate(raw);
+    if (versionIssue) {
+        return { ok: false, issues: [versionIssue] };
+    }
+    const parsed = WorkflowDefinitionSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.flatMap((issue) => {
+            const unrecognizedKeys = issue.code === "unrecognized_keys" ? issue.keys : [];
+            return locateZodIssue({ path: issue.path, message: issue.message, unrecognizedKeys }, raw);
+        });
+        return { ok: false, issues };
+    }
+    const issues = validateWorkflowDefinition(parsed.data);
+    if (issues.length > 0) {
+        return { ok: false, issues };
+    }
+    return { ok: true, definition: parsed.data };
+}
+function checkVersionGate(raw) {
+    const record = RawObjectSchema.safeParse(raw);
+    if (!record.success) {
+        return { path: "version", message: "expected a workflow definition object" };
+    }
+    if (!Object.hasOwn(record.data, "version")) {
+        return {
+            path: "version",
+            message: 'missing "version": a file without "version" is treated as a task graph, not a workflow definition',
+        };
+    }
+    const version = record.data.version;
+    if (version !== SUPPORTED_VERSION) {
+        return {
+            path: "version",
+            message: `unsupported definition version: ${String(version)} (this build supports version ${SUPPORTED_VERSION})`,
+        };
+    }
+    return null;
+}
+const RawObjectSchema = z.record(z.string(), z.unknown());
+/** Loose view of the raw input, used only to recover the ids Zod's paths do not carry. */
+const RawLocatorSchema = z.object({
+    steps: z.array(z.unknown()).optional(),
+    inputs: z.array(z.unknown()).optional(),
+});
+const RawStepIdSchema = z.object({ id: z.string().trim().min(1) });
+const RawInputKeySchema = z.object({ key: z.string().trim().min(1) });
+function locateZodIssue(issue, raw) {
+    if (issue.unrecognizedKeys.length > 0) {
+        return issue.unrecognizedKeys.map((key) => describeUnrecognizedKey(key, issue.path, raw));
+    }
+    return [{ path: locatePath(issue.path, raw), message: issue.message }];
+}
+/**
+ * One issue PER unrecognized key, not one lumped issue, and with a purpose-built
+ * message that names the version so the author knows the key is unsupported here rather
+ * than misspelled.
+ */
+function describeUnrecognizedKey(key, path, raw) {
+    const index = path[1];
+    if (path[0] !== "steps" || typeof index !== "number") {
+        return {
+            path: key,
+            message: `"${key}" is not a supported definition key in version: ${SUPPORTED_VERSION}`,
+        };
+    }
+    const stepId = readRawStepId(raw, index);
+    const located = stepId === null ? `steps[#${index}]` : `steps[${stepId}]`;
+    const owner = stepId === null ? `step #${index}` : `step "${stepId}"`;
+    return {
+        path: located,
+        message: `${owner}: "${key}" is not a supported step key in version: ${SUPPORTED_VERSION}`,
+    };
+}
+/**
+ * Zod reports `steps[2]`, which names the array index. An author reads step ids, so
+ * recover the id from the raw input and degrade to `steps[#<index>]` only when the step
+ * cannot name itself.
+ */
+function locatePath(path, raw) {
+    const [head, index, field] = path;
+    if (head === "steps" && typeof index === "number") {
+        const stepId = readRawStepId(raw, index);
+        if (stepId === null) {
+            return `steps[#${index}]`;
+        }
+        return field === undefined ? `steps[${stepId}]` : `steps[${stepId}].${String(field)}`;
+    }
+    if (head === "inputs" && typeof index === "number") {
+        const key = readRawInputKey(raw, index);
+        return key === null ? `inputs[#${index}]` : `inputs[${key}]`;
+    }
+    const joined = path.map((segment) => String(segment)).join(".");
+    return joined.length > 0 ? joined : "definition";
+}
+function readRawStepId(raw, index) {
+    const view = RawLocatorSchema.safeParse(raw);
+    if (!view.success) {
+        return null;
+    }
+    const step = RawStepIdSchema.safeParse(view.data.steps?.[index]);
+    return step.success ? step.data.id : null;
+}
+function readRawInputKey(raw, index) {
+    const view = RawLocatorSchema.safeParse(raw);
+    if (!view.success) {
+        return null;
+    }
+    const input = RawInputKeySchema.safeParse(view.data.inputs?.[index]);
+    return input.success ? input.data.key : null;
+}
+//# sourceMappingURL=definition.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperdrive.bot/paseo-protocol",
-  "version": "0.3.42",
+  "version": "0.3.44",
   "description": "Paseo shared protocol schemas and wire types",
   "files": [
     "dist",