@kirrosh/zond 0.22.0 → 0.23.0

package/src/core/runner/run-kind.ts

@@ -0,0 +1,39 @@
+/**
+ * ARV-55: single source of truth for classifying a run by *what kind of
+ * suites it executed*. Before this module the answer was inferred from
+ * `suite_file` paths in three places (coverage's `isProbeOnlyRun`,
+ * `db diagnose` recommendation branching, and a handful of skill prompts).
+ *
+ * We resolve the kind once at INSERT-time and persist it in `runs.run_kind`;
+ * downstream filters become a column compare instead of a per-result regex.
+ *
+ * Encoding:
+ *   - `probe`   — every suite path lives under `apis/<api>/probes/` (or a
+ *                 bare `probes/` segment for ad-hoc setups). Coverage hides
+ *                 these by default — probe runs deliberately exercise a
+ *                 subset of endpoints and would otherwise read as a
+ *                 regression vs the prior smoke/CRUD run.
+ *   - `check`   — every suite path lives under `apis/<api>/checks/`. Mirrors
+ *                 the same logic: conformance checks don't reflect endpoint
+ *                 coverage breadth.
+ *   - `regular` — anything else, including mixed runs (probe + smoke). A
+ *                 mixed run is treated as regular because at least one
+ *                 suite contributed real coverage signal.
+ */
+
+export type RunKind = "regular" | "probe" | "check";
+
+const PROBE_SEGMENT_RE = /(^|\/)probes(\/|$)/;
+const CHECK_SEGMENT_RE = /(^|\/)checks(\/|$)/;
+
+export function detectRunKind(suiteFiles: ReadonlyArray<string | null | undefined>): RunKind {
+  // Empty / all-empty arrays default to 'regular' — the DB CHECK constraint
+  // refuses NULL so callers always receive a concrete kind.
+  const paths = suiteFiles
+    .filter((p): p is string => typeof p === "string" && p.length > 0);
+  if (paths.length === 0) return "regular";
+
+  if (paths.every((p) => PROBE_SEGMENT_RE.test(p))) return "probe";
+  if (paths.every((p) => CHECK_SEGMENT_RE.test(p))) return "check";
+  return "regular";
+}

package/src/core/runner/schema-validator.ts

@@ -0,0 +1,312 @@
+import Ajv2020 from "ajv/dist/2020.js";
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+import type { ErrorObject, ValidateFunction, AnySchema } from "ajv";
+import type { OpenAPIV3 } from "openapi-types";
+import { specPathToRegex } from "../generator/coverage-scanner.ts";
+import type { AssertionResult } from "./types.ts";
+
+export interface SchemaValidator {
+  validate(method: string, path: string, status: number, body: unknown): AssertionResult[];
+  /** TASK-142: surface whether an endpoint and a response branch matched.
+   *  Lets ad-hoc callers (`zond request --validate-schema`) distinguish
+   *  "no spec entry for this URL" from "spec entry exists, body is valid". */
+  inspect(method: string, path: string, status: number): {
+    matchedEndpoint: { method: string; path: string } | null;
+    matchedResponseStatus: string | null;
+    hasJsonSchema: boolean;
+  };
+}
+
+interface EndpointEntry {
+  method: string;
+  path: string;
+  regex: RegExp;
+  responses: OpenAPIV3.ResponsesObject;
+}
+
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"] as const;
+
+export function createSchemaValidator(doc: OpenAPIV3.Document): SchemaValidator {
+  const isV31 = typeof doc.openapi === "string" && doc.openapi.startsWith("3.1");
+  // OpenAPI 3.1 → JSON Schema Draft 2020-12; 3.0 → Draft 4/7-ish.
+  // verbose:true exposes parentSchema on each error so humanize() can render
+  // the full required-set alongside the missing field name (TASK-277).
+  const ajv = isV31
+    ? new (Ajv2020 as unknown as typeof Ajv)({ strict: false, allErrors: true, verbose: true })
+    : new Ajv({ strict: false, allErrors: true, verbose: true });
+  addFormats(ajv);
+  applyStrictFormats(ajv);
+
+  const endpoints: EndpointEntry[] = [];
+  if (doc.paths) {
+    for (const [pathTpl, pathItem] of Object.entries(doc.paths)) {
+      if (!pathItem) continue;
+      const regex = specPathToRegex(pathTpl);
+      for (const m of HTTP_METHODS) {
+        const op = (pathItem as Record<string, unknown>)[m] as OpenAPIV3.OperationObject | undefined;
+        if (!op || !op.responses) continue;
+        endpoints.push({ method: m.toUpperCase(), path: pathTpl, regex, responses: op.responses });
+      }
+    }
+    // Sort by specificity so concrete paths (e.g. /users/me) win over templated
+    // ones (/users/{id}) regardless of spec declaration order. Tie-breaker is
+    // stable insertion order (Array.sort is stable in modern engines).
+    endpoints.sort((a, b) => paramCount(a.path) - paramCount(b.path));
+  }
+
+  // ARV-214: per-schema compile is the dominant cost of --validate-schema
+  // on big dereferenced specs (github 14 MiB → minutes per response).
+  // The cache below is keyed by schema *object reference*, so endpoints
+  // that share a $ref source after dereference hit it on the second
+  // access. The slow_compile budget warns the user the first time a
+  // schema crosses 1s — the same compile only happens once per schema
+  // anyway thanks to the cache, so the warning is per-source, not
+  // per-call.
+  const SLOW_COMPILE_MS = Number(process.env.ZOND_VALIDATE_SCHEMA_SLOW_COMPILE_MS ?? "1000");
+  // Hard byte cap stops the run from hanging minutes on a pathological
+  // single response schema (post-deref github Repository / kubernetes
+  // pod-spec). Returning a no-op validator + a single warning is much
+  // friendlier than blocking on `ajv.compile` for an unbounded time.
+  // Default chosen from the bench in /tmp/bench-convert.ts: a 572 KiB
+  // schema compiles in ~800 ms; 1 MiB ≈ 1.4 s; beyond that we'd rather
+  // skip and tell the user.
+  const MAX_SCHEMA_BYTES = Number(process.env.ZOND_VALIDATE_SCHEMA_MAX_BYTES ?? String(1_048_576));
+  const compiled = new Map<unknown, ValidateFunction | null>();
+  const warnedSlow = new WeakSet<object>();
+  const warnedTooLarge = new WeakSet<object>();
+
+  function tooLargeSentinel(): null {
+    return null;
+  }
+
+  function compile(schema: AnySchema): ValidateFunction | null {
+    if (compiled.has(schema)) return compiled.get(schema) ?? null;
+    // Cheap pre-check: a schema whose JSON serialisation exceeds
+    // MAX_SCHEMA_BYTES is almost certainly going to take seconds-to-
+    // minutes to compile and produce noisy mid-body errors that aren't
+    // worth the wait. Skip it with a warning. JSON.stringify itself is
+    // O(n) but at MiB-scale completes in tens of ms — orders of
+    // magnitude cheaper than ajv.compile on the same payload.
+    if (MAX_SCHEMA_BYTES > 0) {
+      try {
+        const sz = JSON.stringify(schema)?.length ?? 0;
+        if (sz > MAX_SCHEMA_BYTES) {
+          if (typeof schema === "object" && schema && !warnedTooLarge.has(schema as object)) {
+            warnedTooLarge.add(schema as object);
+            const kib = Math.round(sz / 1024);
+            process.stderr.write(
+              `[zond] schema too large for --validate-schema (${kib} KiB > ${Math.round(MAX_SCHEMA_BYTES / 1024)} KiB) — skipping; raise via ZOND_VALIDATE_SCHEMA_MAX_BYTES.\n`,
+            );
+          }
+          compiled.set(schema, tooLargeSentinel());
+          return null;
+        }
+      } catch { /* circular or non-serialisable — let ajv try */ }
+    }
+    const prepared = isV31 ? schema : convertOpenApi30(schema);
+    const t0 = performance.now();
+    const fn = ajv.compile(prepared as AnySchema);
+    const elapsed = performance.now() - t0;
+    if (elapsed >= SLOW_COMPILE_MS && typeof schema === "object" && schema && !warnedSlow.has(schema as object)) {
+      warnedSlow.add(schema as object);
+      process.stderr.write(
+        `[zond] schema validator compile took ${elapsed.toFixed(0)} ms (warn ≥ ${SLOW_COMPILE_MS} ms) — see ZOND_VALIDATE_SCHEMA_MAX_BYTES if --validate-schema runs feel slow.\n`,
+      );
+    }
+    compiled.set(schema, fn);
+    return fn;
+  }
+
+  function findResponseSchema(method: string, path: string, status: number): OpenAPIV3.SchemaObject | undefined {
+    const upper = method.toUpperCase();
+    // Endpoints are pre-sorted by specificity (concrete paths first), so the
+    // first regex match is the most specific — /users/me beats /users/{id}.
+    const match = endpoints.find(e => e.method === upper && e.regex.test(path));
+    if (!match) return undefined;
+    const responses = match.responses;
+    const exact = responses[String(status)] as OpenAPIV3.ResponseObject | undefined;
+    const wildcard = responses[`${Math.floor(status / 100)}XX`] as OpenAPIV3.ResponseObject | undefined;
+    const fallback = responses.default as OpenAPIV3.ResponseObject | undefined;
+    const response = exact ?? wildcard ?? fallback;
+    if (!response || !response.content) return undefined;
+    const json = response.content["application/json"];
+    return (json?.schema as OpenAPIV3.SchemaObject | undefined) ?? undefined;
+  }
+
+  function inspectMatch(method: string, path: string, status: number) {
+    const upper = method.toUpperCase();
+    const ep = endpoints.find(e => e.method === upper && e.regex.test(path));
+    if (!ep) {
+      return { matchedEndpoint: null, matchedResponseStatus: null, hasJsonSchema: false };
+    }
+    const exact = ep.responses[String(status)] as OpenAPIV3.ResponseObject | undefined;
+    const wildcard = ep.responses[`${Math.floor(status / 100)}XX`] as OpenAPIV3.ResponseObject | undefined;
+    const fallback = ep.responses.default as OpenAPIV3.ResponseObject | undefined;
+    const matchedKey = exact ? String(status) : wildcard ? `${Math.floor(status / 100)}XX` : fallback ? "default" : null;
+    const response = exact ?? wildcard ?? fallback;
+    const hasJsonSchema = !!(response?.content?.["application/json"]?.schema);
+    return {
+      matchedEndpoint: { method: ep.method, path: ep.path },
+      matchedResponseStatus: matchedKey,
+      hasJsonSchema,
+    };
+  }
+
+  return {
+    validate(method, path, status, body) {
+      const schema = findResponseSchema(method, path, status);
+      if (!schema) return [];
+      let validator: ValidateFunction | null;
+      try {
+        validator = compile(schema);
+      } catch (err) {
+        return [{
+          field: "body",
+          rule: "schema.compile_error",
+          passed: false,
+          actual: undefined,
+          expected: err instanceof Error ? err.message : String(err),
+        }];
+      }
+      // ARV-214: schema crossed ZOND_VALIDATE_SCHEMA_MAX_BYTES — surface
+      // the skip as a passing assertion so the run stays green and the
+      // user knows validation was bypassed for this body.
+      if (validator === null) {
+        return [{
+          field: "body",
+          rule: "schema.skipped_too_large",
+          passed: true,
+          actual: undefined,
+          expected: "schema exceeded ZOND_VALIDATE_SCHEMA_MAX_BYTES — see stderr warning",
+          kind: "schema",
+        }];
+      }
+      const ok = validator(body);
+      if (ok) return [];
+      const errors = validator.errors ?? [];
+      return errors.map(e => ajvErrorToAssertion(e, body));
+    },
+    inspect: inspectMatch,
+  };
+}
+
+function paramCount(path: string): number {
+  let n = 0;
+  for (const seg of path.split("/")) if (/^\{[^}]+\}$/.test(seg)) n++;
+  return n;
+}
+
+function ajvErrorToAssertion(err: ErrorObject, body: unknown): AssertionResult {
+  const ptr = err.instancePath || "";
+  // Field key like "body" or "body.user.email" for parity with checkAssertions.
+  const field = ptr ? `body${ptr.replace(/\//g, ".")}` : "body";
+  const actual = ptr ? getByJsonPointer(body, ptr) : body;
+  return {
+    field,
+    rule: `schema.${err.keyword}`,
+    passed: false,
+    actual,
+    expected: humanize(err),
+    kind: "schema",
+  };
+}
+
+function humanize(err: ErrorObject): string {
+  switch (err.keyword) {
+    case "required": {
+      const missing = (err.params as { missingProperty: string }).missingProperty;
+      // verbose:true gives us the parent schema; surface the full required-set
+      // so the user can see drift at a glance instead of decoding the message
+      // one missing-field-error at a time (TASK-277).
+      const parent = (err as ErrorObject & { parentSchema?: unknown }).parentSchema;
+      const required =
+        parent && typeof parent === "object" && Array.isArray((parent as { required?: unknown }).required)
+          ? ((parent as { required: string[] }).required)
+          : undefined;
+      const tail = required ? `; expected required: [${required.join(", ")}]` : "";
+      return `missing required field "${missing}"${tail}`;
+    }
+    case "type":
+      return `type ${(err.params as { type: string | string[] }).type}`;
+    case "enum":
+      return `one of ${JSON.stringify((err.params as { allowedValues: unknown[] }).allowedValues)}`;
+    case "format":
+      return `format "${(err.params as { format: string }).format}"`;
+    case "additionalProperties":
+      return `no additional property "${(err.params as { additionalProperty: string }).additionalProperty}"`;
+    case "const":
+      return `const ${JSON.stringify((err.params as { allowedValue: unknown }).allowedValue)}`;
+    case "minLength":
+    case "maxLength":
+    case "minimum":
+    case "maximum":
+    case "exclusiveMinimum":
+    case "exclusiveMaximum":
+    case "multipleOf":
+    case "pattern":
+      return `${err.keyword} ${JSON.stringify((err.params as Record<string, unknown>)[err.keyword] ?? "")}`.trim();
+    default:
+      return err.message ?? err.keyword;
+  }
+}
+
+function getByJsonPointer(obj: unknown, pointer: string): unknown {
+  if (!pointer) return obj;
+  const segments = pointer.split("/").slice(1).map(s => s.replace(/~1/g, "/").replace(/~0/g, "~"));
+  let cur: unknown = obj;
+  for (const seg of segments) {
+    if (cur && typeof cur === "object") {
+      cur = (cur as Record<string, unknown>)[seg];
+    } else {
+      return undefined;
+    }
+  }
+  return cur;
+}
+
+// RFC3339 §5.6: date-time = full-date "T" full-time. T (or t) is required as
+// separator; offset is "Z" or "[+-]HH:MM" with explicit colon. ajv-formats
+// accepts " " as separator and "+HH" without colon, which lets PostgreSQL-style
+// timestamps ("2026-04-29 07:10:44.674675+00") slip through.
+export const STRICT_RFC3339_DATE_TIME =
+  /^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])[Tt](?:[01]\d|2[0-3]):[0-5]\d:(?:[0-5]\d|60)(?:\.\d+)?(?:[Zz]|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/;
+
+function applyStrictFormats(ajv: Ajv): void {
+  // Override ajv-formats' lax date-time with strict RFC3339.
+  ajv.addFormat("date-time", { type: "string", validate: STRICT_RFC3339_DATE_TIME });
+}
+
+/**
+ * Convert OpenAPI 3.0 schema to JSON Schema Draft 7-compatible:
+ * - `nullable: true` → add "null" to `type`.
+ * - Drop unsupported `example`, `xml`, `discriminator` keywords (ajv tolerates with strict:false).
+ */
+function convertOpenApi30(schema: AnySchema): AnySchema {
+  if (!schema || typeof schema !== "object") return schema;
+  if (Array.isArray(schema)) {
+    return schema.map(s => convertOpenApi30(s as AnySchema)) as unknown as AnySchema;
+  }
+  const src = schema as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(src)) {
+    if (k === "nullable") continue;
+    if (k === "type" && src.nullable === true) {
+      if (Array.isArray(v)) {
+        out.type = [...v as unknown[], "null"];
+      } else if (typeof v === "string") {
+        out.type = [v, "null"];
+      } else {
+        out.type = v;
+      }
+      continue;
+    }
+    if (v && typeof v === "object") {
+      out[k] = convertOpenApi30(v as AnySchema);
+    } else {
+      out[k] = v;
+    }
+  }
+  // Standalone nullable: true with no explicit type → leave as-is (ajv accepts any).
+  return out as AnySchema;
+}

package/src/core/runner/send-request.ts

@@ -2,23 +2,61 @@ import { executeRequest } from "./http-client.ts";
 import { loadEnvironment, substituteString, substituteDeep } from "../parser/variables.ts";
 import { getDb } from "../../db/schema.ts";
 import { findCollectionByNameOrId } from "../../db/queries.ts";
+import { encodeFormBody } from "./form-encode.ts";
 
-function extractByPath(obj: unknown, path: string): unknown {
-  const segments = path.replace(/\[(\d+)\]/g, '.$1').split('.').filter(Boolean);
+function hasHeaderCI(headers: Record<string, string>, name: string): boolean {
+  const lower = name.toLowerCase();
+  return Object.keys(headers).some((k) => k.toLowerCase() === lower);
+}
+
+export function extractByPath(obj: unknown, path: string): unknown {
+  return extractByPathWithDiagnostic(obj, path).value;
+}
+
+/** ARV-70 (feedback round-01 / F11): same extractor as above but also
+ *  reports *why* the path failed. The CLI surfaces this on stderr when
+ *  `--json-path` returns undefined so users don't lose minutes debugging
+ *  "empty stdout despite data[0].id is right there in the JSON" — the
+ *  hint pinpoints the segment that didn't resolve (e.g. "body is a string
+ *  — content-type was not application/json"). */
+export function extractByPathWithDiagnostic(
+  obj: unknown,
+  path: string,
+): { value: unknown; resolved: string[]; failedAt?: string; reason?: string } {
+  const segments = path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+  const resolved: string[] = [];
   let current: unknown = obj;
   for (const seg of segments) {
-    if (current === null || current === undefined) return undefined;
+    if (current === null || current === undefined) {
+      return { value: undefined, resolved, failedAt: seg, reason: "previous segment resolved to null/undefined" };
+    }
     if (Array.isArray(current)) {
       const idx = parseInt(seg, 10);
-      if (isNaN(idx)) return undefined;
+      if (isNaN(idx)) {
+        return { value: undefined, resolved, failedAt: seg, reason: `expected an array index, got non-numeric segment "${seg}"` };
+      }
+      if (idx < 0 || idx >= current.length) {
+        return { value: undefined, resolved, failedAt: seg, reason: `array index ${idx} out of bounds (length ${current.length})` };
+      }
       current = current[idx];
-    } else if (typeof current === 'object') {
-      current = (current as Record<string, unknown>)[seg];
+    } else if (typeof current === "object") {
+      const obj = current as Record<string, unknown>;
+      if (!(seg in obj)) {
+        const keys = Object.keys(obj).slice(0, 8).join(", ");
+        return { value: undefined, resolved, failedAt: seg, reason: `key "${seg}" not in object (keys: ${keys || "<empty>"})` };
+      }
+      current = obj[seg];
     } else {
-      return undefined;
+      return {
+        value: undefined,
+        resolved,
+        failedAt: seg,
+        reason: `cannot traverse "${seg}" — body is a ${typeof current === "string" ? "string (content-type may not be application/json)" : typeof current}`,
+      };
     }
+    resolved.push(seg);
   }
-  return current;
+  return { value: current, resolved };
 }
 
 export interface SendAdHocRequestOptions {
@@ -33,6 +71,15 @@ export interface SendAdHocRequestOptions {
   maxResponseChars?: number;
   dbPath?: string;
   searchDir?: string;
+  /** Extra vars merged on top of env (e.g. captured values from a stored run). */
+  extraVars?: Record<string, unknown>;
+  /** When true, resolve interpolation but do not actually send the request. */
+  dryRun?: boolean;
+  /** ARV-149: when true, send the body as `application/x-www-form-urlencoded`.
+   *  Parses `body` as JSON to lift fields, then re-encodes with bracket notation
+   *  (Stripe-style nested keys). If `body` isn't JSON-parseable it's passed
+   *  through verbatim, and only the Content-Type header is set. */
+  form?: boolean;
 }
 
 export interface SendAdHocRequestResult {
@@ -40,25 +87,75 @@ export interface SendAdHocRequestResult {
   headers: Record<string, string>;
   body: unknown;
   duration_ms: number;
+  /** ARV-70: when --json-path failed to resolve, this carries which
+   *  segment broke and why so the CLI can surface a hint on stderr. */
+  jsonPathDiagnostic?: { resolved: string[]; failedAt?: string; reason?: string };
 }
 
-export async function sendAdHocRequest(options: SendAdHocRequestOptions): Promise<SendAdHocRequestResult> {
+export interface ResolvedRequest {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body?: string;
+}
+
+export async function resolveAdHocRequest(options: SendAdHocRequestOptions): Promise<ResolvedRequest> {
   let searchDir = options.searchDir ?? process.cwd();
   if (options.collectionName) {
     getDb(options.dbPath);
     const col = findCollectionByNameOrId(options.collectionName);
-    if (col?.base_dir) searchDir = col.base_dir;
+    if (!col) {
+      throw new Error(`API '${options.collectionName}' is not registered. Run \`zond add api <name> --base-url <url>\` first, or check the name with \`zond db collections\`.`);
+    }
+    if (col.base_dir) searchDir = col.base_dir;
+  }
+  const envVars = await loadEnvironment(options.envName, searchDir);
+  const vars = options.extraVars ? { ...envVars, ...options.extraVars } : envVars;
+
+  // Auto-prefix base_url for relative paths when --api is in play.
+  // Mirror the YAML-runner ergonomics: `zond request --api jp GET /users/1`
+  // should work the same as `... GET '{{base_url}}/users/1'`. We touch the URL
+  // only when it's clearly relative (leading "/") and has no scheme/template
+  // already, so absolute URLs and explicit {{var}} templates pass through.
+  let urlToResolve = options.url;
+  if (
+    options.collectionName
+    && typeof vars.base_url === "string"
+    && vars.base_url.length > 0
+    && urlToResolve.startsWith("/")
+    && !urlToResolve.startsWith("//")
+  ) {
+    const base = vars.base_url.replace(/\/+$/, "");
+    urlToResolve = `${base}${urlToResolve}`;
   }
-  const vars = await loadEnvironment(options.envName, searchDir);
 
-  const resolvedUrl = substituteString(options.url, vars) as string;
+  const resolvedUrl = substituteString(urlToResolve, vars) as string;
   const parsedHeaders = options.headers ?? {};
   const resolvedHeaders = Object.keys(parsedHeaders).length > 0 ? substituteDeep(parsedHeaders, vars) : {};
-  const resolvedBody = options.body ? substituteString(options.body, vars) as string : undefined;
+  let resolvedBody = options.body ? substituteString(options.body, vars) as string : undefined;
 
-  // Auto-detect Content-Type for body if not explicitly set
   const finalHeaders: Record<string, string> = { ...resolvedHeaders };
-  if (resolvedBody && !finalHeaders["Content-Type"] && !finalHeaders["content-type"]) {
+  const hasContentType =
+    finalHeaders["Content-Type"] !== undefined || finalHeaders["content-type"] !== undefined;
+
+  // ARV-149: `--form` (or auto-detection from spec content type) re-encodes
+  // the JSON body as `application/x-www-form-urlencoded` with bracket
+  // notation. Stripe v1 and other Rails/PHP-style APIs declare ONLY form
+  // bodies on their mutating endpoints — sending JSON yields a 400
+  // "check that your POST content type is application/x-www-form-urlencoded".
+  if (resolvedBody && options.form) {
+    try {
+      const parsed = JSON.parse(resolvedBody);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        resolvedBody = encodeFormBody(parsed as Record<string, unknown>);
+      }
+    } catch {
+      // Body isn't JSON — assume it's already urlencoded; pass through verbatim.
+    }
+    if (!hasContentType) {
+      finalHeaders["Content-Type"] = "application/x-www-form-urlencoded";
+    }
+  } else if (resolvedBody && !hasContentType) {
     try {
       JSON.parse(resolvedBody);
       finalHeaders["Content-Type"] = "application/json";
@@ -67,20 +164,55 @@ export async function sendAdHocRequest(options: SendAdHocRequestOptions): Promis
     }
   }
 
+  // TASK-231: when --api resolved an env with `auth_token`, auto-inject the
+  // standard `Authorization: Bearer …` header. This mirrors the YAML runner's
+  // behaviour (probes/suites template the same header from the security
+  // scheme) so `zond request --api X GET /…` doesn't 401 just because the
+  // user didn't repeat `--header "Authorization: Bearer {{auth_token}}"`.
+  // User-supplied Authorization always wins.
+  if (
+    options.collectionName
+    && typeof vars.auth_token === "string"
+    && vars.auth_token.length > 0
+    && !hasHeaderCI(finalHeaders, "Authorization")
+  ) {
+    finalHeaders["Authorization"] = `Bearer ${vars.auth_token}`;
+  }
+
+  return {
+    method: options.method,
+    url: resolvedUrl,
+    headers: finalHeaders,
+    ...(resolvedBody !== undefined ? { body: resolvedBody } : {}),
+  };
+}
+
+// Note: `options.form` is consumed inside `resolveAdHocRequest` itself —
+// the encoded `body` string and Content-Type are baked into `finalHeaders`.
+// `sendAdHocRequest` doesn't need to forward the flag separately.
+
+export async function sendAdHocRequest(options: SendAdHocRequestOptions): Promise<SendAdHocRequestResult> {
+  const resolved = await resolveAdHocRequest(options);
+
   const response = await executeRequest(
     {
-      method: options.method,
-      url: resolvedUrl,
-      headers: finalHeaders,
-      body: resolvedBody,
+      method: resolved.method,
+      url: resolved.url,
+      headers: resolved.headers,
+      body: resolved.body,
     },
     options.timeout ? { timeout: options.timeout } : undefined,
   );
 
   let responseBody: unknown = response.body_parsed ?? response.body;
+  let jsonPathDiagnostic: SendAdHocRequestResult["jsonPathDiagnostic"];
 
   if (options.jsonPath && responseBody !== undefined) {
-    responseBody = extractByPath(responseBody, options.jsonPath);
+    const diag = extractByPathWithDiagnostic(responseBody, options.jsonPath);
+    responseBody = diag.value;
+    if (diag.value === undefined && diag.failedAt) {
+      jsonPathDiagnostic = { resolved: diag.resolved, failedAt: diag.failedAt, reason: diag.reason };
+    }
   }
 
   const result: SendAdHocRequestResult = {
@@ -88,6 +220,7 @@ export async function sendAdHocRequest(options: SendAdHocRequestOptions): Promis
     headers: response.headers,
     body: responseBody,
     duration_ms: response.duration_ms,
+    ...(jsonPathDiagnostic ? { jsonPathDiagnostic } : {}),
   };
 
   return result;

package/src/core/runner/types.ts

@@ -14,14 +14,26 @@ export interface HttpResponse {
   body: string;
   body_parsed?: unknown;
   duration_ms: number;
+  /** TASK-144: number of network-level retries that preceded this response.
+   *  0 when the request succeeded on the first attempt. */
+  network_retry_count?: number;
 }
 
+/**
+ * `kind` lets the UI surface the assertion that matches the test's stated
+ * intent (primary) ahead of OpenAPI schema noise (schema) and housekeeping
+ * checks like duration/header asserts (auxiliary). Optional for backwards
+ * compatibility — older runs render as `primary` by default.
+ */
+export type AssertionKind = "primary" | "schema" | "auxiliary";
+
 export interface AssertionResult {
   field: string;
   rule: string;
   passed: boolean;
   actual: unknown;
   expected: unknown;
+  kind?: AssertionKind;
 }
 
 export interface StepResult {
@@ -33,6 +45,32 @@ export interface StepResult {
   assertions: AssertionResult[];
   captures: Record<string, unknown>;
   error?: string;
+  provenance?: import("../parser/types.ts").SourceMetadata | null;
+  /** TASK-101: classification of why this failure happened — definitely_bug,
+   *  likely_bug, quirk, env_issue. `null` for passed/skipped/unclassifiable. */
+  failure_class?: import("../diagnostics/failure-class.ts").FailureClass | null;
+  failure_class_reason?: string | null;
+  /** TASK-102: JSON Pointer into the OpenAPI doc + frozen excerpt of the
+   *  schema at that pointer. Captured at run time so later spec edits don't
+   *  rewrite history. `null` for manual YAML or when spec isn't available. */
+  spec_pointer?: string | null;
+  spec_excerpt?: string | null;
+  /** TASK-144: how many network-level retries the http-client performed
+   *  before this step settled. Omitted (or 0) when no retry was needed.
+   *  Surfaced in the JSON report so flaky-network steps are visible. */
+  network_retry?: number;
+  /** ARV-157: summary of `--validate-schema` outcome for this step. Present
+   *  only when the runner had a schema validator attached AND a JSON body
+   *  was returned (so consumers can distinguish "no drift" from "never
+   *  validated"). Granular failures still live in `assertions[]` with
+   *  `kind: "schema"`; this block is the at-a-glance shape skill docs
+   *  describe and JSON-report consumers grep for. */
+  schema_validation?: {
+    result: "PASS" | "FAIL" | "no-endpoint" | "no-schema";
+    matched_endpoint: { method: string; path: string } | null;
+    matched_response_status: string | null;
+    error_count: number;
+  };
 }
 
 export interface TestRunResult {