@kirrosh/zond 0.21.0 → 0.22.0

package/src/core/diagnostics/db-analysis.ts

@@ -335,16 +335,25 @@ export function groupFailures<T extends FailureItem>(failures: T[], maxExamples
     const pattern = group.response_status
       ? `${group.response_status} ${group.failure_type}`
       : group.failure_type;
+    // 5xx (api_error) are critical backend bugs — never collapse them.
+    // Diagnose must surface every 5xx, otherwise users miss real
+    // regressions hidden behind a single sample.
+    const isApiError = group.failure_type === "api_error";
+    const showAll = isApiError || maxExamples === 0;
     grouped_failures.push({
       pattern,
       count: group.items.length,
       failure_type: group.failure_type,
       recommended_action: group.items[0]!.recommended_action,
       hint: group.hint,
-      examples: (maxExamples === 0 ? group.items : group.items.slice(0, maxExamples)).map(f => `${f.suite_name}/${f.test_name}`),
+      examples: (showAll ? group.items : group.items.slice(0, maxExamples)).map(f => `${f.suite_name}/${f.test_name}`),
       response_status: group.response_status,
     });
-    compactFailures.push(group.items[0]!);
+    if (isApiError) {
+      compactFailures.push(...group.items);
+    } else {
+      compactFailures.push(group.items[0]!);
+    }
   }
 
   return { grouped_failures, compactFailures };

package/src/core/diagnostics/render-md.ts

@@ -0,0 +1,112 @@
+import type { DiagnoseResult } from "./db-analysis.ts";
+
+/**
+ * Render a DiagnoseResult into a human-readable markdown digest.
+ * Output is the canonical body of the `zond://run/{id}/diagnosis` MCP resource.
+ */
+export function renderDiagnosisMarkdown(result: DiagnoseResult): string {
+  const { run, summary, agent_directive, env_issue, auth_hint, cascade_skips, failures, grouped_failures } = result;
+  const out: string[] = [];
+
+  const passed = summary.passed;
+  const total = summary.total;
+  const env = run.environment ?? "no env";
+  const duration = run.duration_ms !== null ? `${run.duration_ms}ms` : "unknown duration";
+
+  out.push(`# Run ${run.id} — ${passed}/${total} passed`);
+  out.push(`${run.started_at} · ${env} · ${duration}`);
+  out.push("");
+  out.push("## Summary");
+  out.push(`- total: ${summary.total}`);
+  out.push(`- passed: ${summary.passed}`);
+  out.push(`- failed: ${summary.failed} (api_errors: ${summary.api_errors}, assertion_failures: ${summary.assertion_failures}, network_errors: ${summary.network_errors})`);
+
+  if (agent_directive) {
+    out.push("");
+    out.push("## Agent directive");
+    out.push(agent_directive);
+  }
+
+  if (env_issue) {
+    out.push("");
+    out.push("## Env issue");
+    out.push(env_issue);
+  }
+
+  if (auth_hint) {
+    out.push("");
+    out.push("## Auth hint");
+    out.push(auth_hint);
+  }
+
+  if (cascade_skips && cascade_skips.length > 0) {
+    out.push("");
+    out.push("## Cascade skips");
+    for (const group of cascade_skips) {
+      out.push(`- **${group.capture_var}** — ${group.count} test${group.count === 1 ? "" : "s"} skipped`);
+      for (const example of group.examples) {
+        out.push(`  - ${example}`);
+      }
+    }
+  }
+
+  if (grouped_failures && grouped_failures.length > 0) {
+    out.push("");
+    out.push("## Failure groups");
+    for (const group of grouped_failures) {
+      out.push("");
+      out.push(`### ${group.pattern} — ${group.count} occurrence${group.count === 1 ? "" : "s"}`);
+      out.push(`recommended_action: \`${group.recommended_action}\``);
+      if (group.hint) out.push(`hint: ${group.hint}`);
+      if (group.examples.length > 0) {
+        out.push("examples:");
+        for (const example of group.examples) {
+          out.push(`- ${example}`);
+        }
+      }
+    }
+  }
+
+  if (failures.length > 0) {
+    out.push("");
+    out.push(grouped_failures && grouped_failures.length > 0 ? "## Representative failures" : "## Failures");
+    for (const f of failures) {
+      out.push("");
+      out.push(`### ${f.suite_name} > ${f.test_name}`);
+      const meta: string[] = [`failure_type: \`${f.failure_type}\``, `recommended_action: \`${f.recommended_action}\``];
+      if (f.suite_file) meta.push(`file: \`${f.suite_file}\``);
+      out.push(meta.join(" · "));
+      const requestLine = `${f.request_method ?? "?"} ${f.request_url ?? "?"}`;
+      const statusLine = f.response_status !== null ? ` → ${f.response_status}` : "";
+      out.push(`- request: ${requestLine}${statusLine}`);
+      if (f.error_message) out.push(`- error: ${f.error_message}`);
+      if (f.hint) out.push(`- hint: ${f.hint}`);
+      if (f.schema_hint) out.push(`- schema: ${f.schema_hint}`);
+      if (f.response_headers) {
+        const headerStr = Object.entries(f.response_headers).map(([k, v]) => `${k}: ${v}`).join(", ");
+        out.push(`- headers: ${headerStr}`);
+      }
+      if (f.response_body !== undefined) {
+        const bodyStr = typeof f.response_body === "string"
+          ? f.response_body
+          : JSON.stringify(f.response_body, null, 2);
+        const fenced = bodyStr.includes("\n") || bodyStr.length > 80;
+        if (fenced) {
+          out.push("- response_body:");
+          out.push("  ```");
+          for (const line of bodyStr.split("\n")) out.push(`  ${line}`);
+          out.push("  ```");
+        } else {
+          out.push(`- response_body: \`${bodyStr}\``);
+        }
+      }
+    }
+  }
+
+  if (failures.length === 0 && (!grouped_failures || grouped_failures.length === 0)) {
+    out.push("");
+    out.push("_No failures._");
+  }
+
+  return out.join("\n");
+}

package/src/core/generator/chunker.ts

@@ -39,9 +39,21 @@ export function planChunks(endpoints: EndpointInfo[]): ChunkPlan {
 
 /** Filter endpoints that have the given tag (case-insensitive) */
 export function filterByTag(endpoints: EndpointInfo[], tag: string): EndpointInfo[] {
-  const lower = tag.toLowerCase();
+  const lower = tag.trim().toLowerCase();
   if (lower === "untagged") {
     return endpoints.filter(ep => ep.tags.length === 0);
   }
-  return endpoints.filter(ep => ep.tags.some(t => t.toLowerCase() === lower));
+  return endpoints.filter(ep => ep.tags.some(t => t.trim().toLowerCase() === lower));
+}
+
+/** Collect the unique set of tags across all endpoints (sorted, original casing). */
+export function collectTags(endpoints: EndpointInfo[]): string[] {
+  const seen = new Map<string, string>();
+  for (const ep of endpoints) {
+    for (const t of ep.tags) {
+      const key = t.trim().toLowerCase();
+      if (!seen.has(key)) seen.set(key, t.trim());
+    }
+  }
+  return Array.from(seen.values()).sort((a, b) => a.localeCompare(b));
 }

package/src/core/generator/data-factory.ts

@@ -11,6 +11,12 @@ export function generateFromSchema(
 ): unknown {
   if (_depth > 5) return {};
 
+  // Highest-priority signal: explicit example from spec.
+  // Beats enum, format, heuristics — the spec author told us what to send.
+  if (schema.example !== undefined) {
+    return schema.example;
+  }
+
   // allOf: merge all schemas
   if (schema.allOf) {
     const merged: OpenAPIV3.SchemaObject = { type: "object", properties: {} };
@@ -31,15 +37,26 @@ export function generateFromSchema(
     return generateFromSchema(schema.anyOf[0] as OpenAPIV3.SchemaObject, propertyName, _depth + 1);
   }
 
-  // enum: first value
+  // enum: first value (always valid for the API contract)
   if (schema.enum && schema.enum.length > 0) {
     return schema.enum[0];
   }
 
-  // uuid format overrides type (e.g. integer fields with format: uuid)
-  if (schema.format === "uuid") return "{{$uuid}}";
-
-  switch (schema.type) {
+  // Format-based placeholders override type resolution. Schemas in the wild
+  // commonly carry `format` without an explicit `type` (loosely-defined specs)
+  // or with `type: ["string", "null"]` (OpenAPI 3.1 nullable). Falling through
+  // to the type switch in those cases dropped us into the default branch and
+  // produced `{{$randomString}}` for `format: email` — TASK-86 regression.
+  const formatPlaceholder = formatToPlaceholder(schema.format);
+  if (formatPlaceholder !== undefined) return formatPlaceholder;
+
+  // OpenAPI 3.1: type can be `["string", "null"]`. Collapse to the first
+  // non-null entry so the switch below routes correctly.
+  const effectiveType = Array.isArray(schema.type)
+    ? (schema.type as string[]).find(t => t !== "null") as OpenAPIV3.SchemaObject["type"] | undefined
+    : schema.type;
+
+  switch (effectiveType) {
     case "string":
       return guessStringPlaceholder(schema, propertyName);
 
@@ -53,8 +70,9 @@ export function generateFromSchema(
       return true;
 
     case "array": {
-      if (schema.items) {
-        const item = generateFromSchema(schema.items as OpenAPIV3.SchemaObject, undefined, _depth + 1);
+      const arr = schema as OpenAPIV3.ArraySchemaObject;
+      if (arr.items) {
+        const item = generateFromSchema(arr.items as OpenAPIV3.SchemaObject, undefined, _depth + 1);
         return [item];
       }
       return [];
@@ -79,7 +97,7 @@ export function generateFromSchema(
         return { key1: "value1", key2: "value2" };
       }
       // Bare object with no properties
-      if (schema.type === "object") {
+      if (effectiveType === "object") {
         return {};
       }
       return "{{$randomString}}";
@@ -87,6 +105,27 @@ export function generateFromSchema(
   }
 }
 
+/**
+ * Map an OpenAPI `format` value to a zond generator placeholder. Returns
+ * undefined when the format is unknown or absent so callers can fall back
+ * to type / property-name heuristics. Exported for tests.
+ */
+export function formatToPlaceholder(format: string | undefined): string | undefined {
+  switch (format) {
+    case "email": return "{{$randomEmail}}";
+    case "uuid": return "{{$uuid}}";
+    case "date-time": return "{{$randomIsoDate}}";
+    case "date": return "{{$randomDate}}";
+    case "uri":
+    case "url": return "{{$randomUrl}}";
+    case "hostname": return "{{$randomFqdn}}";
+    case "ipv4": return "{{$randomIpv4}}";
+    case "ipv6": return "::1";
+    case "password": return "TestPass123!";
+    default: return undefined;
+  }
+}
+
 /**
  * Generate a multipart body object from an OpenAPI multipart/form-data schema.
  * Binary fields (format: binary/byte) become file upload objects; all others become strings.
@@ -112,16 +151,8 @@ export function generateMultipartFromSchema(
 }
 
 function guessStringPlaceholder(schema: OpenAPIV3.SchemaObject, name?: string): string {
-  // Format-based
-  if (schema.format === "email") return "{{$randomEmail}}";
-  if (schema.format === "uuid") return "{{$uuid}}";
-  if (schema.format === "date-time") return "2025-01-01T00:00:00Z";
-  if (schema.format === "date") return "2025-01-01";
-  if (schema.format === "uri" || schema.format === "url") return "https://example.com/test";
-  if (schema.format === "hostname") return "example.com";
-  if (schema.format === "ipv4") return "192.168.1.1";
-  if (schema.format === "ipv6") return "::1";
-  if (schema.format === "password") return "TestPass123!";
+  // Format-based dispatch already happened earlier in generateFromSchema;
+  // this branch only sees strings whose format is empty or unrecognised.
 
   // Name-based heuristics
   if (name) {
@@ -136,7 +167,7 @@ function guessStringPlaceholder(schema: OpenAPIV3.SchemaObject, name?: string):
       return "{{$randomName}}";
     }
     if (lower === "url" || lower.endsWith("_url") || lower === "uri" || lower === "href" || lower === "website") {
-      return "https://example.com/test";
+      return "{{$randomUrl}}";
     }
     if (lower === "password" || lower.endsWith("_password")) {
       return "TestPass123!";

package/src/core/generator/guide-builder.ts

@@ -120,7 +120,7 @@ Use \`json:\` for JSON request bodies. Do NOT use \`body:\` — it is not a vali
 For form-encoded: use \`form:\` instead of \`json:\`.
 
 ### Built-in generators
-\`{{$uuid}}\`, \`{{$randomInt}}\`, \`{{$timestamp}}\`, \`{{$isoTimestamp}}\`, \`{{$randomName}}\`, \`{{$randomEmail}}\`, \`{{$randomString}}\`
+\`{{$uuid}}\`, \`{{$randomInt}}\`, \`{{$timestamp}}\`, \`{{$isoTimestamp}}\`, \`{{$randomName}}\`, \`{{$randomEmail}}\`, \`{{$randomString}}\`, \`{{$randomUrl}}\` (uri/url), \`{{$randomFqdn}}\` (hostname), \`{{$randomIpv4}}\` (ipv4), \`{{$randomDate}}\` (date), \`{{$randomIsoDate}}\` (date-time)
 
 ### Variable capture & interpolation
 \`\`\`yaml

package/src/core/generator/openapi-reader.ts

@@ -93,6 +93,24 @@ export function extractEndpoints(doc: OpenAPIV3.Document): EndpointInfo[] {
           const chosen = rb.content[requestBodyContentType!];
           if (chosen?.schema) {
             requestBodySchema = chosen.schema as OpenAPIV3.SchemaObject;
+            // OpenAPI allows examples at the media-type level (sibling to schema).
+            // Lift them onto the schema so the generator sees a single signal.
+            if (requestBodySchema.example === undefined) {
+              if ((chosen as OpenAPIV3.MediaTypeObject).example !== undefined) {
+                requestBodySchema = {
+                  ...requestBodySchema,
+                  example: (chosen as OpenAPIV3.MediaTypeObject).example,
+                };
+              } else if (chosen.examples) {
+                const firstNamed = Object.values(chosen.examples)[0];
+                if (firstNamed && typeof firstNamed === "object" && "value" in firstNamed) {
+                  requestBodySchema = {
+                    ...requestBodySchema,
+                    example: (firstNamed as OpenAPIV3.ExampleObject).value,
+                  };
+                }
+              }
+            }
           }
         }
       }

package/src/core/generator/serializer.ts

@@ -27,7 +27,7 @@ export interface RawStep {
   name: string;
   [methodKey: string]: unknown;
   expect: {
-    status?: number;
+    status?: number | number[];
     body?: Record<string, Record<string, string>>;
     headers?: Record<string, unknown>;
   };
@@ -103,6 +103,11 @@ export function serializeSuite(suite: RawSuite): string {
       lines.push(`    skip_if: ${yamlScalar(String(test.skip_if))}`);
     }
 
+    // always (cleanup steps that survive cascade-skip on tainted captures)
+    if (test.always === true) {
+      lines.push("    always: true");
+    }
+
     // retry_until
     if (test.retry_until && typeof test.retry_until === "object") {
       const rt = test.retry_until as Record<string, unknown>;
@@ -131,7 +136,11 @@ export function serializeSuite(suite: RawSuite): string {
     if (hasExpect) {
       lines.push("    expect:");
       if (test.expect.status !== undefined) {
-        lines.push(`      status: ${test.expect.status}`);
+        if (Array.isArray(test.expect.status)) {
+          lines.push(`      status: [${test.expect.status.join(", ")}]`);
+        } else {
+          lines.push(`      status: ${test.expect.status}`);
+        }
       }
       if (test.expect.body) {
         lines.push("      body:");

package/src/core/generator/suite-generator.ts

@@ -28,6 +28,30 @@ function convertPathWithSeeds(path: string, ep: EndpointInfo): string {
   });
 }
 
+/**
+ * For negative-smoke suites: replace path params with guaranteed-non-existent values.
+ * Picks a value that's syntactically valid for the param's type/format but very
+ * unlikely to match a real resource (zero-UUID, very large int, sentinel string).
+ */
+function getNonexistentSeed(schema: OpenAPIV3.SchemaObject | undefined): string {
+  if (!schema) return "nonexistent_id_zzzzzz";
+  if (schema.format === "uuid") return "00000000-0000-0000-0000-000000000000";
+  if (schema.type === "integer" || schema.type === "number") return "999999999";
+  return "nonexistent_id_zzzzzz";
+}
+
+function convertPathWithBadIds(path: string, ep: EndpointInfo): string {
+  return path.replace(/\{([^}]+)\}/g, (_, name: string) => {
+    const param = ep.parameters.find(p => p.name === name && p.in === "path");
+    const schema = param?.schema as OpenAPIV3.SchemaObject | undefined;
+    return getNonexistentSeed(schema);
+  });
+}
+
+function endpointHasPathParams(ep: EndpointInfo): boolean {
+  return ep.parameters.some(p => p.in === "path");
+}
+
 function slugify(s: string): string {
   return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
 }
@@ -360,9 +384,11 @@ export function generateCrudSuite(
       });
     }
 
+    // T44: cleanup must run even if earlier assertions failed (tainted captures)
     const step: RawStep = {
       name: group.delete.operationId ?? `Delete ${group.resource.replace(/s$/, "")}`,
       DELETE: itemPath,
+      always: true,
       expect: {
         status: getExpectedStatus(group.delete),
       },
@@ -372,11 +398,12 @@ export function generateCrudSuite(
     }
     tests.push(step);
 
-    // 5. Verify deleted
+    // 5. Verify deleted — also always, so we confirm cleanup happened
     if (group.read) {
       tests.push({
         name: `Verify ${group.resource.replace(/s$/, "")} deleted`,
         GET: convertPath(group.itemPath).replace(`{{${group.idParam}}}`, `{{${captureVar}}}`),
+        always: true,
         expect: {
           status: 404,
         },
@@ -384,9 +411,13 @@ export function generateCrudSuite(
     }
   }
 
+  // T28: classify by cleanup behavior. A suite that owns a DELETE leaves the API
+  // in its starting state (ephemeral); without DELETE it leaves residual data.
+  const cleanupTag = group.delete ? "ephemeral" : "persistent-write";
+
   const suite: RawSuite = {
     name: `${group.resource}-crud`,
-    tags: ["crud"],
+    tags: ["crud", cleanupTag],
     fileStem: `crud-${slugify(group.resource)}`,
     base_url: "{{base_url}}",
     tests,
@@ -634,17 +665,20 @@ export function generateSuites(opts: {
   for (const [tag, tagEndpoints] of byTag) {
     const tagSlug = slugify(tag) || "api";
 
-    // GET endpoints → smoke suite (use seed values for path params — no capture context)
+    // GET endpoints → split into paramless (regular smoke) and path-param (negative+positive smoke)
     const getEndpoints = tagEndpoints.filter(ep => ep.method.toUpperCase() === "GET");
-    if (getEndpoints.length > 0) {
-      const tests = getEndpoints.map(ep => {
+    const paramlessGets = getEndpoints.filter(ep => !endpointHasPathParams(ep));
+    const pathParamGets = getEndpoints.filter(ep => endpointHasPathParams(ep));
+
+    // Regular smoke: paramless GETs (e.g. list endpoints, health checks)
+    if (paramlessGets.length > 0) {
+      const tests = paramlessGets.map(ep => {
         const step = generateStep(ep, securitySchemes);
-        // Replace path param placeholders with seed values so the suite runs out of the box
         const seededPath = convertPathWithSeeds(ep.path, ep);
         (step as any)[ep.method.toUpperCase()] = seededPath;
         return step;
       });
-      const headers = getSuiteHeaders(getEndpoints, securitySchemes);
+      const headers = getSuiteHeaders(paramlessGets, securitySchemes);
 
       const suite: RawSuite = {
         name: `${tagSlug}-smoke`,
@@ -666,6 +700,71 @@ export function generateSuites(opts: {
       suites.push(suite);
     }
 
+    // Negative smoke: path-param GETs with guaranteed-bad IDs, expect 400/404/422
+    if (pathParamGets.length > 0) {
+      const tests = pathParamGets.map(ep => {
+        const step = generateStep(ep, securitySchemes);
+        (step as any)[ep.method.toUpperCase()] = convertPathWithBadIds(ep.path, ep);
+        // Negative path: resource doesn't exist. Drop body assertions (response shape varies).
+        step.expect = { status: [400, 404, 422] };
+        return step;
+      });
+      const headers = getSuiteHeaders(pathParamGets, securitySchemes);
+
+      const suite: RawSuite = {
+        name: `${tagSlug}-smoke-negative`,
+        tags: ["smoke", "negative"],
+        fileStem: `smoke-${tagSlug}-negative`,
+        base_url: "{{base_url}}",
+        tests,
+      };
+
+      if (headers) {
+        suite.headers = headers;
+        for (const t of tests) {
+          if (t.headers && JSON.stringify(t.headers) === JSON.stringify(headers)) {
+            delete (t as any).headers;
+          }
+        }
+      }
+
+      suites.push(suite);
+    }
+
+    // Positive smoke: path-param GETs with {{var}} placeholders + skip_if for unset env
+    if (pathParamGets.length > 0) {
+      const tests = pathParamGets.map(ep => {
+        const step = generateStep(ep, securitySchemes);
+        // Path stays as {{param}} so user-provided env values flow in
+        // Pick the first path param for skip_if guard (the resource ID)
+        const firstPathParam = ep.parameters.find(p => p.in === "path");
+        if (firstPathParam) {
+          step.skip_if = `{{${firstPathParam.name}}} ==`;
+        }
+        return step;
+      });
+      const headers = getSuiteHeaders(pathParamGets, securitySchemes);
+
+      const suite: RawSuite = {
+        name: `${tagSlug}-smoke-positive`,
+        tags: ["smoke", "positive", "needs-id"],
+        fileStem: `smoke-${tagSlug}-positive`,
+        base_url: "{{base_url}}",
+        tests,
+      };
+
+      if (headers) {
+        suite.headers = headers;
+        for (const t of tests) {
+          if (t.headers && JSON.stringify(t.headers) === JSON.stringify(headers)) {
+            delete (t as any).headers;
+          }
+        }
+      }
+
+      suites.push(suite);
+    }
+
     // Non-GET endpoints: split reset/system endpoints out of smoke-unsafe
     const nonGetEndpoints = tagEndpoints.filter(ep => ep.method.toUpperCase() !== "GET");
     const resetEndpoints = nonGetEndpoints.filter(ep => RESET_PATH_RE.test(ep.path));

package/src/core/meta/types.ts

@@ -12,8 +12,6 @@ export interface ZondMeta {
   zondVersion: string;
   /** ISO timestamp of last sync/generate */
   lastSyncedAt: string;
-  /** Spec URL or file path used for last generation */
-  specUrl: string;
   /** SHA-256 hex of spec content at time of last generation */
   specHash: string;
   /** Per-file metadata, keyed by filename (e.g. "smoke-users.yaml") */

package/src/core/parser/schema.ts

@@ -92,7 +92,7 @@ const AssertionRuleSchemaInner: z.ZodType<AssertionRule> = z.preprocess(
   },
   z.object({
     capture: z.string().optional(),
-    type: z.enum(["string", "integer", "number", "boolean", "array", "object"]).optional(),
+    type: z.enum(["string", "integer", "number", "boolean", "array", "object", "null"]).optional(),
     equals: z.unknown().optional(),
     not_equals: z.unknown().optional(),
     contains: z.string().optional(),
@@ -184,6 +184,7 @@ const TestStepSchema: z.ZodType<TestStep> = z.preprocess(
     retry_until: RetryUntilSchema.optional(),
     for_each: ForEachSchema.optional(),
     set: z.record(z.string(), z.unknown()).optional(),
+    always: z.boolean().optional(),
   }),
 ) as z.ZodType<TestStep>;
 
@@ -220,6 +221,7 @@ const TestSuiteSchema = z.preprocess(
     tags: z.array(z.string()).optional(),
     base_url: z.string().optional(),
     headers: z.record(z.string(), z.string()).optional(),
+    parameterize: z.record(z.string(), z.array(z.unknown()).min(1)).optional(),
     config: SuiteConfigSchema,
     tests: z.array(TestStepSchema).min(1),
   }),

package/src/core/parser/types.ts

@@ -2,7 +2,7 @@ export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 
 export interface AssertionRule {
   capture?: string;
-  type?: "string" | "integer" | "number" | "boolean" | "array" | "object";
+  type?: "string" | "integer" | "number" | "boolean" | "array" | "object" | "null";
   equals?: unknown;
   not_equals?: unknown;
   contains?: string;
@@ -63,6 +63,12 @@ export interface TestStep {
   retry_until?: RetryUntil;
   for_each?: ForEach;
   set?: Record<string, unknown>;
+  /**
+   * Run this step even when prior steps in the suite have failed assertions
+   * (so their captures are "tainted"). Designed for cleanup steps. Still
+   * skips if a referenced capture is genuinely missing from a response.
+   */
+  always?: boolean;
 }
 
 export interface SuiteConfig {
@@ -81,6 +87,9 @@ export interface TestSuite {
   tags?: string[];
   base_url?: string;
   headers?: Record<string, string>;
+  /** Cross-product parameterisation: each key contributes one variable
+   *  binding per array entry. Suite body runs once per combination. */
+  parameterize?: Record<string, unknown[]>;
   config: SuiteConfig;
   tests: TestStep[];
   /** Absolute path to the source file, set by yaml-parser */