@kirrosh/zond 0.21.0 → 0.23.0

package/src/core/runner/executor.ts

@@ -1,11 +1,14 @@
 import { resolve, dirname, basename } from "node:path";
-import type { TestSuite, TestStep, Environment } from "../parser/types.ts";
+import type { TestSuite, TestStep, Environment, SourceMetadata, AssertionRule } from "../parser/types.ts";
 import { substituteString, substituteStep, substituteDeep, extractVariableReferences } from "../parser/variables.ts";
-import type { TestRunResult, StepResult, HttpRequest } from "./types.ts";
+import type { TestRunResult, StepResult, HttpRequest, AssertionResult } from "./types.ts";
 import { executeRequest, type FetchOptions } from "./http-client.ts";
-import { checkAssertions, extractCaptures } from "./assertions.ts";
+import type { RateLimiter } from "./rate-limiter.ts";
+import { checkAssertions, extractCaptures, findMissedCaptures } from "./assertions.ts";
 import { evaluateExpr } from "./expr-eval.ts";
 import { applyTransform } from "./transforms.ts";
+import type { SchemaValidator } from "./schema-validator.ts";
+import { classifyFailure } from "../diagnostics/failure-class.ts";
 
 function buildUrl(baseUrl: string | undefined, path: string, query?: Record<string, string>): string {
   let url = baseUrl ? `${baseUrl.replace(/\/+$/, "")}${path}` : path;
@@ -16,8 +19,96 @@ function buildUrl(baseUrl: string | undefined, path: string, query?: Record<stri
   return url;
 }
 
-function makeSkippedResult(stepName: string, reason: string): StepResult {
+/** Shallow-merge suite-level и step-level provenance. Step перекрывает suite. */
+function mergeProvenance(
+  suiteSrc?: SourceMetadata,
+  stepSrc?: SourceMetadata,
+): SourceMetadata | null {
+  if (!suiteSrc && !stepSrc) return null;
+  return { ...(suiteSrc ?? {}), ...(stepSrc ?? {}) };
+}
+
+/** ARV-157: build the top-level `schema_validation` summary for a step that
+ *  was run with `--validate-schema`. Mirrors the shape `zond request
+ *  --validate-schema` already produces (see src/cli/commands/request.ts);
+ *  consumers can `jq '.steps[] | .schema_validation'` instead of digging
+ *  into `assertions[] | select(.kind=="schema")`.
+ *
+ *  Returns undefined when the validator wasn't attached or the response had
+ *  no parseable JSON body — same precondition as `assertions.push(...)` at
+ *  the call site, so the summary is present iff schema actually ran. */
+function buildSchemaValidationSummary(
+  validator: SchemaValidator,
+  method: string,
+  path: string,
+  status: number,
+  schemaAssertions: AssertionResult[],
+): StepResult["schema_validation"] {
+  const ins = validator.inspect(method, path, status);
+  if (!ins.matchedEndpoint) {
+    return { result: "no-endpoint", matched_endpoint: null, matched_response_status: null, error_count: 0 };
+  }
+  if (!ins.hasJsonSchema) {
+    return {
+      result: "no-schema",
+      matched_endpoint: ins.matchedEndpoint,
+      matched_response_status: ins.matchedResponseStatus,
+      error_count: 0,
+    };
+  }
+  const failed = schemaAssertions.filter((a) => !a.passed).length;
   return {
+    result: failed === 0 ? "PASS" : "FAIL",
+    matched_endpoint: ins.matchedEndpoint,
+    matched_response_status: ins.matchedResponseStatus,
+    error_count: failed,
+  };
+}
+
+/** TASK-256: turn each missed-capture (path didn't resolve in response)
+ *  into an auxiliary failed assertion. The step then fails loudly with
+ *  "capture <var>: path '<path>' not found in body" instead of producing
+ *  silent `captures: {}` that the user only notices when the next step in a
+ *  CRUD chain skips with `Depends on missing capture`. */
+function buildMissedCaptureAssertions(
+  misses: ReturnType<typeof findMissedCaptures>,
+): AssertionResult[] {
+  return misses.map((m) => ({
+    field: `capture ${m.var}`,
+    rule: m.source === "body" ? "body-path-exists" : "header-exists",
+    passed: false,
+    actual: undefined,
+    expected: `${m.source} '${m.path}' present`,
+    kind: "auxiliary",
+  }));
+}
+
+function collectChainCaptures(tests: TestStep[]): Set<string> {
+  const out = new Set<string>();
+  const visit = (rules: Record<string, AssertionRule> | undefined) => {
+    if (!rules) return;
+    for (const r of Object.values(rules)) {
+      if (r.capture) out.add(r.capture);
+      if (r.each) visit(r.each);
+      if (r.contains_item) visit(r.contains_item);
+    }
+  };
+  for (const step of tests) visit(step.expect?.body);
+  return out;
+}
+
+function emptyVarSkipReason(varName: string, chainCaptures: Set<string>): string {
+  return chainCaptures.has(varName)
+    ? `chain capture {{${varName}}} unbound (upstream step did not run or did not capture it)`
+    : `required fixture {{${varName}}} is empty`;
+}
+
+function makeSkippedResult(
+  stepName: string,
+  reason: string,
+  opts?: { cascade?: { missingCapture: string } },
+): StepResult {
+  const result: StepResult = {
     name: stepName,
     status: "skip",
     duration_ms: 0,
@@ -26,21 +117,145 @@ function makeSkippedResult(stepName: string, reason: string): StepResult {
     captures: {},
     error: reason,
   };
+  if (opts?.cascade) {
+    result.failure_class = "cascade";
+    result.failure_class_reason = `Upstream capture not produced: ${opts.cascade.missingCapture}`;
+  }
+  return result;
 }
 
-export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun = false): Promise<TestRunResult> {
+/** Interpolate {{var}} placeholders inside a test/step name. Falls back to
+ *  the raw name string if substitution returns a non-string value. */
+function interpolateName(name: string, vars: Record<string, unknown>): string {
+  try {
+    const out = substituteString(name, vars);
+    return typeof out === "string" ? out : String(out);
+  } catch {
+    return name;
+  }
+}
+
+/**
+ * Expand a `parameterize: { key: [val, ...] }` map into the cross-product of
+ * iteration variable bindings. No `parameterize` (or an empty map) yields a
+ * single empty iteration so the existing single-pass behaviour is preserved.
+ *
+ * Exported for tests.
+ */
+export function expandParameterize(params?: Record<string, unknown[]>): Record<string, unknown>[] {
+  if (!params) return [{}];
+  const keys = Object.keys(params).filter(k => Array.isArray(params[k]) && (params[k] as unknown[]).length > 0);
+  if (keys.length === 0) return [{}];
+  let combos: Record<string, unknown>[] = [{}];
+  for (const k of keys) {
+    const values = params[k] as unknown[];
+    const next: Record<string, unknown>[] = [];
+    for (const combo of combos) {
+      for (const v of values) {
+        next.push({ ...combo, [k]: v });
+      }
+    }
+    combos = next;
+  }
+  return combos;
+}
+
+export interface RunSuiteOptions {
+  rateLimiter?: RateLimiter;
+  /** Optional OpenAPI response-schema validator. When provided, every step's
+   *  parsed JSON body is validated against the matching schema; failures are
+   *  appended to the step's `assertions`. */
+  schemaValidator?: SchemaValidator;
+  /** TASK-144: per-step network-retry budget used by http-client for
+   *  ECONNRESET / EPIPE / `socket hang up` / `fetch failed` / abort cases.
+   *  Set by `zond run --retry-on-network <N>`. HTTP statuses are not retried
+   *  by this path. */
+  networkRetries?: number;
+  /** ARV-249: shared HTTP-request budget across all parallel suites. When
+   *  `used >= limit`, remaining steps short-circuit to `skip` with reason
+   *  `max-requests-cap-reached`. Each `retry_until` attempt counts as one
+   *  request; dry-run and set-only steps do not consume the budget. */
+  requestBudget?: RequestBudget;
+  /** ARV-249: invoked after every step completes (pass/fail/skip/error) so
+   *  the CLI can render a periodic progress line without each suite
+   *  knowing how many siblings are running in parallel. */
+  onStepDone?: (step: StepResult) => void;
+}
+
+/** ARV-249: shared `--max-requests` budget. Mutated in-place by every
+ *  parallel `runSuite` call — single-threaded JS makes the
+ *  check-then-increment race-free. `limit === Infinity` means "uncapped"
+ *  (the default). */
+export interface RequestBudget {
+  limit: number;
+  used: number;
+}
+
+/** Try to reserve one HTTP slot from the shared budget. Returns true if
+ *  the caller may proceed, false if the cap has been reached. */
+export function reserveRequest(budget: RequestBudget | undefined): boolean {
+  if (!budget) return true;
+  if (budget.used >= budget.limit) return false;
+  budget.used += 1;
+  return true;
+}
+
+export const MAX_REQUESTS_SKIP_REASON = "max-requests-cap-reached";
+
+export async function runSuite(
+  suite: TestSuite,
+  env: Environment = {},
+  dryRun = false,
+  options: RunSuiteOptions = {},
+): Promise<TestRunResult> {
   const startedAt = new Date().toISOString();
   const steps: StepResult[] = [];
-  const variables: Record<string, unknown> = { ...env };
-  const failedCaptures = new Set<string>();
+
+  /** Push a step result, attaching provenance + failure classification. */
+  const pushStep = (result: StepResult, currentStep?: TestStep): void => {
+    const merged = mergeProvenance(suite.source, currentStep?.source);
+    if (merged !== null) result.provenance = merged;
+    const classification = classifyFailure(result);
+    if (classification) {
+      result.failure_class = classification.failure_class;
+      result.failure_class_reason = classification.failure_class_reason;
+    }
+    steps.push(result);
+    if (options.onStepDone) options.onStepDone(result);
+  };
 
   const fetchOptions: Partial<FetchOptions> = {
     timeout: suite.config.timeout,
     retries: suite.config.retries,
     retry_delay: suite.config.retry_delay,
     follow_redirects: suite.config.follow_redirects,
+    rate_limiter: options.rateLimiter,
+    ...(options.networkRetries !== undefined ? { network_retries: options.networkRetries } : {}),
   };
 
+  // Names of every variable a step in this suite tries to capture from a
+  // response (expect.body.<field>.capture: <name>). When a later step
+  // references one of these and the value is empty — under --dry-run, or
+  // because the capturing step was skipped — the missing var is a chain
+  // capture, NOT a fixture in .env.yaml. Distinguishing them in the skip
+  // message stops users from chasing fixture seeding for vars that
+  // shouldn't live in .env.yaml at all.
+  const chainCaptures = collectChainCaptures(suite.tests);
+
+  // parameterize cross-product → N iterations of the suite body.
+  // Captures and tainted/missing sets are reset per iteration so that
+  // values from one binding never leak into the next.
+  const iterations = expandParameterize(suite.parameterize);
+
+  for (const iterVars of iterations) {
+  const variables: Record<string, unknown> = { ...env, ...iterVars };
+  // Captures whose source step's assertions partially failed, but the value
+  // itself was extracted. Cleanup/always steps may still consume them.
+  const taintedCaptures = new Set<string>();
+  // Captures that were never extracted (response missing the field). Even
+  // always-steps can't run if their referenced capture is missing.
+  const missingCaptures = new Set<string>();
+
   // Expand steps lazily (for_each needs current variables)
   let stepIndex = 0;
   const rawSteps = [...suite.tests];
@@ -85,48 +300,113 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
         const substituted = substituteDeep(rawDirective, variables);
         variables[key] = applyTransform(substituted);
       }
-      steps.push({
-        name: step.name,
+      pushStep({
+        name: interpolateName(step.name, variables),
         status: "pass",
         duration_ms: 0,
         request: { method: "", url: "", headers: {} },
         assertions: [],
         captures: {},
-      });
+      }, step);
       continue;
     }
 
-    // Skip check: if step references a failed capture variable, skip it
+    // Skip check: if step references a failed capture, skip — unless
+    // step is `always: true` AND the capture is just tainted (still extracted).
     const referencedVars = extractVariableReferences(step);
-    const missingCapture = referencedVars.find((v) => failedCaptures.has(v));
-    if (missingCapture) {
-      steps.push(makeSkippedResult(step.name, `Depends on missing capture: ${missingCapture}`));
+    const missing = referencedVars.find((v) => missingCaptures.has(v));
+    if (missing) {
+      pushStep(
+        makeSkippedResult(
+          interpolateName(step.name, variables),
+          `Depends on missing capture: ${missing}`,
+          { cascade: { missingCapture: missing } },
+        ),
+        step,
+      );
       continue;
     }
+    if (!step.always) {
+      const tainted = referencedVars.find((v) => taintedCaptures.has(v));
+      if (tainted) {
+        pushStep(
+          makeSkippedResult(
+            interpolateName(step.name, variables),
+            `Depends on tainted capture: ${tainted} (use always: true on cleanup steps)`,
+            { cascade: { missingCapture: tainted } },
+          ),
+          step,
+        );
+        continue;
+      }
+    }
 
     // skip_if evaluation
     if (step.skip_if) {
       const exprAfterSubst = String(substituteString(step.skip_if, variables));
       if (evaluateExpr(exprAfterSubst)) {
-        steps.push(makeSkippedResult(step.name, `Skipped: ${step.skip_if}`));
+        const varMatch = step.skip_if.match(/\{\{([^{}]+)\}\}/);
+        const skipMsg = varMatch
+          ? emptyVarSkipReason(varMatch[1]!.trim(), chainCaptures)
+          : step.skip_if;
+        pushStep(makeSkippedResult(interpolateName(step.name, variables), skipMsg), step);
         continue;
       }
     }
 
-    // Process set: on HTTP steps — evaluate generators once before building request
-    if (step.set) {
-      for (const [key, rawDirective] of Object.entries(step.set)) {
-        const substituted = substituteDeep(rawDirective, variables);
-        variables[key] = applyTransform(substituted);
+    // Process set: on HTTP steps — evaluate generators once before building request.
+    // Substitution can throw on unknown {{$generator}} — fail this step, not the suite.
+    let resolved: TestStep;
+    let resolvedBaseUrl: string | undefined;
+    let resolvedSuiteHeaders: Record<string, string> | undefined;
+    try {
+      if (step.set) {
+        for (const [key, rawDirective] of Object.entries(step.set)) {
+          const substituted = substituteDeep(rawDirective, variables);
+          variables[key] = applyTransform(substituted);
+        }
+      }
+      resolved = substituteStep(step, variables);
+      resolvedBaseUrl = suite.base_url ? substituteString(suite.base_url, variables) as string : undefined;
+      resolvedSuiteHeaders = suite.headers ? substituteDeep(suite.headers, variables) : undefined;
+    } catch (err) {
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      pushStep({
+        name: interpolateName(step.name, variables),
+        status: "error",
+        duration_ms: 0,
+        request: { method: step.method, url: step.path, headers: {} },
+        assertions: [],
+        captures: {},
+        error: errorMsg,
+      }, step);
+      // Substitution never produced a request → capture truly missing.
+      if (step.expect.body) {
+        for (const rule of Object.values(step.expect.body)) {
+          if (rule.capture) missingCaptures.add(rule.capture);
+        }
+      }
+      continue;
+    }
+    // Skip if any path-variable in the template resolved to empty — an empty
+    // path segment produces URLs like /repos//commits/ which always 404/500.
+    // The explicit skip_if guard only covers the first param (TASK-237);
+    // this catches all others.
+    {
+      let emptyVar: string | null = null;
+      for (const m of step.path.matchAll(/\{\{([^{}]+)\}\}/g)) {
+        const varName = m[1]!.trim();
+        const val = variables[varName];
+        if (val === "" || val === null || val === undefined) { emptyVar = varName; break; }
+      }
+      if (emptyVar) {
+        pushStep(makeSkippedResult(
+          interpolateName(step.name, variables),
+          emptyVarSkipReason(emptyVar, chainCaptures),
+        ), step);
+        continue;
       }
     }
-
-    // Substitute variables
-    const resolved = substituteStep(step, variables);
-
-    // Build request — substitute base_url and suite headers with current variables
-    const resolvedBaseUrl = suite.base_url ? substituteString(suite.base_url, variables) as string : undefined;
-    const resolvedSuiteHeaders = suite.headers ? substituteDeep(suite.headers, variables) : undefined;
     const url = buildUrl(resolvedBaseUrl, resolved.path, resolved.query);
     const headers: Record<string, string> = { ...resolvedSuiteHeaders, ...resolved.headers };
     let body: string | undefined;
@@ -162,18 +442,18 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
 
     // Validate absolute URL before attempting fetch
     if (!url.startsWith("http://") && !url.startsWith("https://")) {
-      steps.push({
-        name: step.name,
+      pushStep({
+        name: interpolateName(step.name, variables),
         status: "error",
         duration_ms: 0,
         request,
         assertions: [],
         captures: {},
         error: `base_url is not configured — URL resolved to a relative path: "${url}". Set base_url in .env.yaml`,
-      });
+      }, step);
       if (step.expect.body) {
         for (const rule of Object.values(step.expect.body)) {
-          if (rule.capture) failedCaptures.add(rule.capture);
+          if (rule.capture) missingCaptures.add(rule.capture);
         }
       }
       continue;
@@ -183,15 +463,15 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
       const bodyPreview = formData
         ? ` [multipart: ${[...formData.keys()].length} field(s)]`
         : body ? ` ${body.slice(0, 200)}` : "";
-      steps.push({
-        name: step.name,
+      pushStep({
+        name: interpolateName(step.name, variables),
         status: "pass",
         duration_ms: 0,
         request,
         assertions: [],
         captures: {},
         error: `[DRY RUN] ${resolved.method} ${url}${bodyPreview}`,
-      });
+      }, step);
       continue;
     }
 
@@ -200,20 +480,45 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
       const rt = step.retry_until;
       let lastStepResult: StepResult | undefined;
       for (let attempt = 0; attempt < rt.max_attempts; attempt++) {
+        if (!reserveRequest(options.requestBudget)) {
+          lastStepResult = makeSkippedResult(
+            interpolateName(step.name, variables),
+            MAX_REQUESTS_SKIP_REASON,
+          );
+          break;
+        }
         try {
           const response = await executeRequest(request, fetchOptions);
           const captures = extractCaptures(resolved.expect.body, response.body_parsed, resolved.expect.headers, response.headers);
+          const missedCaps = findMissedCaptures(resolved.expect.body, response.body_parsed, resolved.expect.headers, response.headers);
           const assertions = checkAssertions(resolved.expect, response);
+          assertions.push(...buildMissedCaptureAssertions(missedCaps));
+          let schemaValidationSummary: StepResult["schema_validation"] | undefined;
+          if (options.schemaValidator && response.body_parsed !== undefined) {
+            const schemaAssertions = options.schemaValidator.validate(resolved.method, resolved.path, response.status, response.body_parsed);
+            assertions.push(...schemaAssertions);
+            schemaValidationSummary = buildSchemaValidationSummary(
+              options.schemaValidator,
+              resolved.method,
+              resolved.path,
+              response.status,
+              schemaAssertions,
+            );
+          }
           const allPassed = assertions.every((a) => a.passed);
 
           lastStepResult = {
-            name: step.name,
+            name: interpolateName(step.name, variables),
             status: allPassed ? "pass" : "fail",
             duration_ms: response.duration_ms,
             request,
             response,
             assertions,
             captures,
+            ...(response.network_retry_count && response.network_retry_count > 0
+              ? { network_retry: response.network_retry_count }
+              : {}),
+            ...(schemaValidationSummary ? { schema_validation: schemaValidationSummary } : {}),
           };
 
           // Evaluate condition with response context
@@ -234,7 +539,7 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
           }
         } catch (err) {
           lastStepResult = {
-            name: step.name,
+            name: interpolateName(step.name, variables),
             status: "error",
             duration_ms: 0,
             request,
@@ -244,7 +549,15 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
           };
         }
       }
-      if (lastStepResult) steps.push(lastStepResult);
+      if (lastStepResult) pushStep(lastStepResult, step);
+      continue;
+    }
+
+    if (!reserveRequest(options.requestBudget)) {
+      pushStep(makeSkippedResult(
+        interpolateName(step.name, variables),
+        MAX_REQUESTS_SKIP_REASON,
+      ), step);
       continue;
     }
 
@@ -255,57 +568,78 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
       const captures = extractCaptures(resolved.expect.body, response.body_parsed, resolved.expect.headers, response.headers);
       Object.assign(variables, captures);
 
-      // Track expected captures that weren't obtained
+      // Track expected captures that weren't obtained — these are missing.
       if (resolved.expect.body) {
         for (const rule of Object.values(resolved.expect.body)) {
           if (rule.capture && !(rule.capture in captures)) {
-            failedCaptures.add(rule.capture);
+            missingCaptures.add(rule.capture);
           }
         }
       }
 
       // Run assertions
+      const missedCaps = findMissedCaptures(resolved.expect.body, response.body_parsed, resolved.expect.headers, response.headers);
       const assertions = checkAssertions(resolved.expect, response);
+      assertions.push(...buildMissedCaptureAssertions(missedCaps));
+      let schemaValidationSummary: StepResult["schema_validation"] | undefined;
+      if (options.schemaValidator && response.body_parsed !== undefined) {
+        const schemaAssertions = options.schemaValidator.validate(resolved.method, resolved.path, response.status, response.body_parsed);
+        assertions.push(...schemaAssertions);
+        schemaValidationSummary = buildSchemaValidationSummary(
+          options.schemaValidator,
+          resolved.method,
+          resolved.path,
+          response.status,
+          schemaAssertions,
+        );
+      }
       const allPassed = assertions.every((a) => a.passed);
 
-      steps.push({
-        name: step.name,
+      pushStep({
+        name: interpolateName(step.name, variables),
         status: allPassed ? "pass" : "fail",
         duration_ms: response.duration_ms,
         request,
         response,
         assertions,
         captures,
-      });
+        ...(response.network_retry_count && response.network_retry_count > 0
+          ? { network_retry: response.network_retry_count }
+          : {}),
+        ...(schemaValidationSummary ? { schema_validation: schemaValidationSummary } : {}),
+      }, step);
 
-      // If step failed, mark its captures as unreliable
+      // If step failed, captures that did extract are tainted (value is real
+      // but came from a step whose other assertions failed). Always-steps may
+      // still consume them; non-always steps cascade-skip.
       if (!allPassed && resolved.expect.body) {
         for (const rule of Object.values(resolved.expect.body)) {
-          if (rule.capture) {
-            failedCaptures.add(rule.capture);
+          if (rule.capture && rule.capture in captures) {
+            taintedCaptures.add(rule.capture);
           }
         }
       }
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);
-      steps.push({
-        name: step.name,
+      pushStep({
+        name: interpolateName(step.name, variables),
         status: "error",
         duration_ms: 0,
         request,
         assertions: [],
         captures: {},
         error: errorMsg,
-      });
+      }, step);
 
-      // Mark any captures from this step as failed
+      // Network/runtime error → no response → capture truly missing.
       if (step.expect.body) {
         for (const rule of Object.values(step.expect.body)) {
-          if (rule.capture) failedCaptures.add(rule.capture);
+          if (rule.capture) missingCaptures.add(rule.capture);
         }
       }
     }
   }
+  } // end of parameterize iteration loop
 
   const finishedAt = new Date().toISOString();
   return {
@@ -323,6 +657,11 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
   };
 }
 
-export async function runSuites(suites: TestSuite[], env: Environment = {}, dryRun = false): Promise<TestRunResult[]> {
-  return Promise.all(suites.map((suite) => runSuite(suite, env, dryRun)));
+export async function runSuites(
+  suites: TestSuite[],
+  env: Environment = {},
+  dryRun = false,
+  options: RunSuiteOptions = {},
+): Promise<TestRunResult[]> {
+  return Promise.all(suites.map((suite) => runSuite(suite, env, dryRun, options)));
 }

package/src/core/runner/form-encode.ts

@@ -0,0 +1,51 @@
+/**
+ * ARV-149 / ARV-150: encode a nested JS object as
+ * `application/x-www-form-urlencoded` using bracket notation — the
+ * canonical Stripe / Rails / PHP convention for nested fields:
+ *
+ *   { address: { line1: "x", line2: "y" }, items: [{ id: 1 }, { id: 2 }] }
+ *   →  address[line1]=x&address[line2]=y&items[0][id]=1&items[1][id]=2
+ *
+ * Shared between `zond request --form`, the YAML runner's `form:` step,
+ * and the mass-assignment probe's form-bodied endpoints. The probe-side
+ * adoption (ARV-150) is what restores 265 SKIPPED Stripe endpoints.
+ */
+function appendFormParam(params: URLSearchParams, key: string, value: unknown): void {
+  if (value === null || value === undefined) return;
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) appendFormParam(params, `${key}[${i}]`, value[i]);
+  } else if (typeof value === "object") {
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      appendFormParam(params, `${key}[${k}]`, v);
+    }
+  } else {
+    params.append(key, String(value));
+  }
+}
+
+export function encodeFormBody(body: Record<string, unknown>): string {
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(body)) appendFormParam(params, k, v);
+  return params.toString();
+}
+
+/** Flatten a nested JS object to a `Record<string, string>` using bracket
+ *  notation, suitable for the YAML runner's `form:` step (which is typed
+ *  as `Record<string, string>` and serialised via `URLSearchParams`). */
+export function flattenToFormFields(body: unknown): Record<string, string> {
+  const out: Record<string, string> = {};
+  const walk = (value: unknown, key: string): void => {
+    if (value === null || value === undefined) return;
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) walk(value[i], key ? `${key}[${i}]` : String(i));
+    } else if (typeof value === "object") {
+      for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+        walk(v, key ? `${key}[${k}]` : k);
+      }
+    } else if (key) {
+      out[key] = String(value);
+    }
+  };
+  if (body && typeof body === "object") walk(body, "");
+  return out;
+}