@kirrosh/zond 0.23.0 → 0.26.0

package/src/core/diagnostics/failure-hints.ts

@@ -1,44 +1,18 @@
 /**
- * Failure classification and diagnostic hints.
- * Extracted from query-db.ts for reuse in Web UI.
+ * Failure classification → closed-enum `recommended_action`.
+ * ARV-338: prose hints (statusHint/envHint/softDeleteHint/schemaHint,
+ * env_issue clustering, auth_hint, agent_directive) removed — the agent
+ * triages by enum + raw evidence, not by heuristic guess-text.
  */
 
 import { classify } from "../classifier/recommended-action.ts";
 
-export function statusHint(status: number | null | undefined): string | null {
-  if (!status) return null;
-  if (status >= 500) return "Server-side error — inspect response_body for errorMessage/errorDetail; likely a backend bug";
-  if (status === 401 || status === 403) return "Auth failure — check auth_token/api_key in .env.yaml";
-  if (status === 404) return "Resource not found — verify the path and ID";
-  if (status === 400 || status === 422) return "Validation error — check request body fields match the schema";
-  if (status === 429) return "Rate limited — too many requests. Consider consolidating auth/login steps or adding delays between suites";
-  return null;
-}
-
 export function classifyFailure(status: string, responseStatus: number | null): "api_error" | "assertion_failed" | "network_error" {
   if (status === "error" && (responseStatus === null || responseStatus < 500)) return "network_error";
   if (responseStatus !== null && responseStatus >= 500) return "api_error";
   return "assertion_failed";
 }
 
-export function envHint(url: string | null, errorMessage: string | null, envFilePath?: string): string | null {
-  const envFile = envFilePath ? envFilePath : ".env.yaml in your API directory";
-
-  if (url && /\{\{[^}]+\}\}/.test(url)) {
-    return `URL contains unresolved variable: "${url}" — variable name may not match the key in ${envFile}`;
-  }
-  if (url && !url.startsWith("http://") && !url.startsWith("https://")) {
-    return `base_url is not set or empty — URL resolved to "${url}". Add base_url to ${envFile}`;
-  }
-  if (errorMessage?.includes("base_url is not configured")) {
-    return `base_url is missing or empty. Add base_url: https://your-api.com to ${envFile}`;
-  }
-  if (errorMessage?.includes("URL is invalid") || errorMessage?.includes("Failed to parse URL")) {
-    return `URL is malformed — likely base_url is empty or invalid. Check base_url in ${envFile}`;
-  }
-  return null;
-}
-
 export type RecommendedAction =
   | "report_backend_bug"
   | "fix_auth_config"
@@ -136,181 +110,3 @@ export function isGeneratedTest(
   if (typeof suite_file === "string" && /(^|\/)apis\/[^/]+\/tests\//.test(suite_file)) return true;
   return false;
 }
-
-export function envCategory(hint: string | undefined): string | null {
-  if (!hint) return null;
-  if (hint.includes("base_url is not set") || hint.includes("base_url is missing") || hint.includes("base_url is not configured")) return "base_url_missing";
-  if (hint.includes("unresolved variable")) return "unresolved_variable";
-  if (hint.includes("URL is malformed")) return "url_malformed";
-  return null;
-}
-
-export function schemaHint(
-  failureType: string,
-  responseStatus: number | null | undefined,
-): string | null {
-  if (failureType === "assertion_failed" || responseStatus === 400 || responseStatus === 422) {
-    return "Use describe_endpoint(specPath, method, path) to verify expected request/response schema";
-  }
-  return null;
-}
-
-export function softDeleteHint(
-  actualStatus: number | null | undefined,
-  requestMethod: string | null | undefined,
-  responseBody: unknown,
-): string | null {
-  if (actualStatus !== 200 || requestMethod?.toUpperCase() !== "GET") return null;
-  if (responseBody && typeof responseBody === "object") {
-    const hasStatusField =
-      "status" in (responseBody as object) ||
-      "state" in (responseBody as object) ||
-      "deleted" in (responseBody as object) ||
-      "is_deleted" in (responseBody as object);
-    if (hasStatusField) {
-      return 'GET returned 200 with a status/state field after DELETE — likely soft delete. Update the test: remove the "Verify deleted → 404" step and instead assert the status field value (e.g. status: "cancelled")';
-    }
-  }
-  return null;
-}
-
-export function computeSharedEnvIssue(
-  failures: Array<{ hint?: string }>,
-  envFilePath?: string,
-): string | null {
-  const categories = new Set(failures.map(f => envCategory(f.hint)).filter(Boolean));
-  if (categories.size !== 1) return null;
-
-  const envFile = envFilePath ?? ".env.yaml";
-  if (categories.has("base_url_missing")) {
-    return `All failures: base_url is not set — add base_url to ${envFile}`;
-  }
-  if (categories.has("unresolved_variable")) {
-    return `All failures: some variables are not substituted — check variable names in ${envFile}`;
-  }
-  // url_malformed
-  return [...failures.map(f => f.hint).filter(Boolean)][0] ?? null;
-}
-
-// ── TASK-98: per-suite env clustering ──────────────────────────────────────
-//
-// Round-3 review showed that the all-or-nothing run-level detector misses
-// real env_issue scenarios: a single suite needs `{{stripe_key}}`, a webhook
-// host is unreachable for one suite only, an auth token expires part-way
-// through. Cluster classification — group by suite, flag a suite when ≥80%
-// of its non-5xx failures share an env-symptom — closes that gap without
-// laundering 5xx (real backend bugs) into env_issue.
-export type EnvSymptom = "missing_var" | "base_url" | "url_malformed" | "auth_expired";
-
-function envSymptomOf(failure: {
-  hint?: string;
-  failure_type: string;
-  response_status: number | null;
-}): EnvSymptom | null {
-  if (failure.failure_type === "api_error") return null; // 5xx never counted
-  const cat = envCategory(failure.hint);
-  if (cat === "unresolved_variable") return "missing_var";
-  if (cat === "base_url_missing") return "base_url";
-  if (cat === "url_malformed") return "url_malformed";
-  if (failure.response_status === 401 || failure.response_status === 403) return "auth_expired";
-  return null;
-}
-
-export interface EnvIssue {
-  /** Human-readable summary; used by reporters and shown to the user. */
-  message: string;
-  /** "run" when the issue spans most/all suites; "suite:<name>" when localized. */
-  scope: "run" | `suite:${string}`;
-  /** Suites the env_issue covers — one entry for suite scope, ≥2 for run scope. */
-  affected_suites: string[];
-  /** Histogram of root-cause symptoms across affected failures. */
-  symptoms: Partial<Record<EnvSymptom, number>>;
-}
-
-/**
- * Cluster non-5xx failures by suite and return per-suite env clusters that
- * meet the env-symptom threshold (default ≥80% AND ≥2 failures). 5xx are
- * excluded so backend bugs cannot be reclassified as env issues.
- */
-export function clusterEnvIssues(
-  failures: Array<{
-    suite_name: string;
-    hint?: string;
-    failure_type: string;
-    response_status: number | null;
-  }>,
-  threshold = 0.8,
-): Array<{ suite: string; symptoms: Partial<Record<EnvSymptom, number>>; total: number }> {
-  const bySuite = new Map<string, typeof failures>();
-  for (const f of failures) {
-    if (f.failure_type === "api_error") continue;
-    const list = bySuite.get(f.suite_name) ?? [];
-    list.push(f);
-    bySuite.set(f.suite_name, list);
-  }
-  const clusters: Array<{ suite: string; symptoms: Partial<Record<EnvSymptom, number>>; total: number }> = [];
-  for (const [suite, items] of bySuite) {
-    if (items.length === 0) continue;
-    const symptoms: Partial<Record<EnvSymptom, number>> = {};
-    let envCount = 0;
-    for (const f of items) {
-      const s = envSymptomOf(f);
-      if (s) {
-        symptoms[s] = (symptoms[s] ?? 0) + 1;
-        envCount++;
-      }
-    }
-    if (envCount / items.length >= threshold && envCount >= 1) {
-      clusters.push({ suite, symptoms, total: items.length });
-    }
-  }
-  return clusters;
-}
-
-function formatSymptoms(symptoms: Partial<Record<EnvSymptom, number>>): string {
-  const parts: string[] = [];
-  for (const k of ["missing_var", "base_url", "url_malformed", "auth_expired"] as EnvSymptom[]) {
-    const n = symptoms[k];
-    if (n) parts.push(`${k}=${n}`);
-  }
-  return parts.join(", ");
-}
-
-/**
- * Build an EnvIssue envelope from clustered failures. Returns null when no
- * cluster exceeded the threshold. When exactly one suite is affected, scope
- * is `suite:<name>`; ≥2 suites collapse into a `run` scope aggregator.
- */
-export function buildEnvIssue(
-  clusters: Array<{ suite: string; symptoms: Partial<Record<EnvSymptom, number>>; total: number }>,
-  envFilePath?: string,
-): EnvIssue | null {
-  if (clusters.length === 0) return null;
-  const envFile = envFilePath ?? ".env.yaml";
-
-  const merged: Partial<Record<EnvSymptom, number>> = {};
-  for (const c of clusters) {
-    for (const [k, v] of Object.entries(c.symptoms)) {
-      merged[k as EnvSymptom] = (merged[k as EnvSymptom] ?? 0) + (v ?? 0);
-    }
-  }
-  const affected_suites = clusters.map(c => c.suite).sort();
-
-  if (clusters.length === 1) {
-    const c = clusters[0]!;
-    const breakdown = formatSymptoms(c.symptoms);
-    return {
-      message: `Suite "${c.suite}" looks env-broken (${breakdown}) — check ${envFile}`,
-      scope: `suite:${c.suite}`,
-      affected_suites,
-      symptoms: merged,
-    };
-  }
-  const breakdown = formatSymptoms(merged);
-  return {
-    message: `${clusters.length} suites look env-broken (${breakdown}) — check ${envFile}`,
-    scope: "run",
-    affected_suites,
-    symptoms: merged,
-  };
-}

package/src/core/diagnostics/suggested-fixes.ts

@@ -2,9 +2,8 @@
  * TASK-29: actionable "Suggested fixes" surfaces for `zond db diagnose`.
  *
  * The base diagnose envelope already classifies failures and wires
- * agent_directive / recommended_action / env_issue. This layer adds two
- * concrete, fixable signals that the LLM agent can act on without a second
- * round-trip:
+ * recommended_action. This layer adds two concrete, fixable signals that
+ * the LLM agent can act on without a second round-trip:
  *
  *   1. Placeholder path-params on 404s — when a 404 hits a URL that still
  *      contains literal example/placeholder values (`example`, all-zeros

package/src/core/generator/chunker.ts

@@ -16,14 +16,7 @@ export interface ChunkPlan {
  * usable first segment (e.g. `/`) keep the legacy `untagged` key.
  */
 export function groupEndpointsByTag(endpoints: EndpointInfo[]): Map<string, EndpointInfo[]> {
-  const groups = new Map<string, EndpointInfo[]>();
-  for (const ep of endpoints) {
-    const key = ep.tags[0] ?? resourceKeyFromPath(ep.path);
-    const list = groups.get(key);
-    if (list) list.push(ep);
-    else groups.set(key, [ep]);
-  }
-  return groups;
+  return Map.groupBy(endpoints, (ep) => ep.tags[0] ?? resourceKeyFromPath(ep.path));
 }
 
 /** Extract the first non-templated path segment for tagless fallback. */

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

@@ -70,17 +70,15 @@ export function generateFromSchema(
   // the API 422s with "Missing <required-by-other-variant>".
   if (schema.oneOf) {
     const variants = schema.oneOf as OpenAPIV3.SchemaObject[];
-    const picked = pickDiscriminatorVariant(variants, schema.discriminator?.propertyName)
-      ?? pickPreferredVariant(variants);
+    const picked = pickBestVariant(variants, schema.discriminator);
     const result = recurse(picked, propertyName);
-    return stampDiscriminator(result, picked, schema.discriminator?.propertyName);
+    return stampDiscriminator(result, picked, schema.discriminator);
   }
   if (schema.anyOf) {
     const variants = schema.anyOf as OpenAPIV3.SchemaObject[];
-    const picked = pickDiscriminatorVariant(variants, schema.discriminator?.propertyName)
-      ?? pickPreferredVariant(variants);
+    const picked = pickBestVariant(variants, schema.discriminator);
     const result = recurse(picked, propertyName);
-    return stampDiscriminator(result, picked, schema.discriminator?.propertyName);
+    return stampDiscriminator(result, picked, schema.discriminator);
   }
 
   // enum: first value (always valid for the API contract)
@@ -174,13 +172,29 @@ export function generateFromSchema(
 /** Fields the client must not send in a request body: explicit `readOnly: true`,
  *  or the literal name `id`. The latter is a heuristic for under-specified specs
  *  (common in in-house APIs) that don't mark the server-assigned id readOnly
- *  but still 4xx on it being present. */
+ *  but still 4xx on it being present.
+ *
+ *  Also strips Stripe-style `expand` meta-param when it's declared as a string
+ *  array — Stripe doesn't mark it `readOnly` but rejects synthetic random
+ *  values with 400 "This property cannot be expanded (<random>)", which kills
+ *  50+ baseline POSTs in mass-assignment / stateful checks on Stripe specs.
+ *  The shape check (array of strings on a request body) keeps false-positives
+ *  low: APIs using `expand` for real payload fields would normally use an
+ *  object/enum, not a free-string array. */
 function shouldSkipForRequest(name: string, schema: OpenAPIV3.SchemaObject): boolean {
   if (schema.readOnly === true) return true;
   if (name === "id") return true;
+  if (name === "expand" && isStringArray(schema)) return true;
   return false;
 }
 
+function isStringArray(schema: OpenAPIV3.SchemaObject): boolean {
+  if (schema.type !== "array") return false;
+  const items = schema.items as OpenAPIV3.SchemaObject | undefined;
+  if (!items) return false;
+  return items.type === "string";
+}
+
 /** When recursion hits the depth cap, return a type-appropriate placeholder
  *  rather than `{}` — `{}` for `array<string>` produces `[{}]` which 422s on
  *  every realistic API. */
@@ -199,67 +213,113 @@ function depthLimitDefault(schema: OpenAPIV3.SchemaObject, name?: string): unkno
   }
 }
 
-/** ARV-78 (F25): when a parent oneOf/anyOf carries `discriminator.propertyName`,
- *  pick the variant whose discriminator property has a single-value enum or
- *  const so its identity is unambiguous. Returns undefined when nothing
- *  qualifies — caller falls back to pickPreferredVariant. */
-function pickDiscriminatorVariant(
+/** ARV-135 (m-21): score-based oneOf/anyOf variant selection.
+ *
+ * Picks the variant most likely to produce a body the server accepts:
+ *
+ *   1. Drop `type: "null"` shorthands unless they're the only choice
+ *      (OpenAPI 3.1 nullable spelling).
+ *   2. Prefer the variant with the fewest UNRESOLVABLE required fields
+ *      — i.e. required keys that have no entry in `properties`, which
+ *      the generator can't synthesise. The historical bug was picking
+ *      the FIRST variant matching the discriminator filter even when a
+ *      sibling variant was demonstrably more complete; this leaves
+ *      `required: [config, event_name]` partially-filled and the API
+ *      422s with "Missing config, event_name" (F24/Resend automations).
+ *   3. Among ties, prefer object-typed variants over primitives
+ *      (TASK-222: `Array<{id}>|Array<string>` should pick the object).
+ *   4. Prefer the variant with more declared properties (richer surface
+ *      is closer to what real callers send).
+ *   5. When a `discriminator.propertyName` is present, treat variants
+ *      that carry a single-value enum/const for that property as more
+ *      authoritative — they tie-break ahead of variants without one.
+ *
+ * The discriminator's `mapping` is used to derive the stamped value
+ * even when the picked variant lacks an inline enum/const: typical
+ * specs (Stripe, Linear) declare mapping centrally and omit the value
+ * on each variant.
+ */
+function pickBestVariant(
   variants: OpenAPIV3.SchemaObject[],
-  propertyName: string | undefined,
-): OpenAPIV3.SchemaObject | undefined {
-  if (!propertyName) return undefined;
-  for (const v of variants) {
-    const prop = v.properties?.[propertyName] as OpenAPIV3.SchemaObject | undefined;
-    if (!prop) continue;
+  discriminator: OpenAPIV3.DiscriminatorObject | undefined,
+): OpenAPIV3.SchemaObject {
+  const isNull = (s: OpenAPIV3.SchemaObject) => (s as { type?: unknown }).type === "null";
+  const nonNull = variants.filter(v => !isNull(v));
+  const pool = nonNull.length > 0 ? nonNull : variants;
+
+  const discriminatorKey = discriminator?.propertyName;
+  const hasDiscriminatorEnum = (v: OpenAPIV3.SchemaObject): boolean => {
+    if (!discriminatorKey) return false;
+    const prop = v.properties?.[discriminatorKey] as OpenAPIV3.SchemaObject | undefined;
+    if (!prop) return false;
     const en = (prop as { enum?: unknown[] }).enum;
     const cn = (prop as { const?: unknown }).const;
-    if (Array.isArray(en) && en.length === 1) return v;
-    if (cn !== undefined && cn !== null) return v;
-  }
-  return undefined;
+    return (Array.isArray(en) && en.length === 1) || (cn !== undefined && cn !== null);
+  };
+
+  const score = (v: OpenAPIV3.SchemaObject) => {
+    const req = (v.required ?? []) as string[];
+    const props = v.properties ?? {};
+    const unresolvable = req.filter(r => !(r in props)).length;
+    const propCount = Object.keys(props).length;
+    const isObjectWithProps = v.type === "object" && propCount > 0;
+    return {
+      unresolvable,
+      hasDiscriminator: hasDiscriminatorEnum(v) ? 1 : 0,
+      isObjectWithProps: isObjectWithProps ? 1 : 0,
+      propCount,
+    };
+  };
+
+  // Sort: fewer unresolvable → has discriminator → object-with-props → more props.
+  // Sort is stable, so original spec order breaks remaining ties.
+  const ranked = [...pool].sort((a, b) => {
+    const sa = score(a);
+    const sb = score(b);
+    if (sa.unresolvable !== sb.unresolvable) return sa.unresolvable - sb.unresolvable;
+    if (sa.hasDiscriminator !== sb.hasDiscriminator) return sb.hasDiscriminator - sa.hasDiscriminator;
+    if (sa.isObjectWithProps !== sb.isObjectWithProps) return sb.isObjectWithProps - sa.isObjectWithProps;
+    return sb.propCount - sa.propCount;
+  });
+
+  return ranked[0]!;
 }
 
 /** Stamp the discriminator key onto a generated object. Without this the
  *  variant choice is "anonymous" from the body's point of view — APIs that
  *  switch on `type` reject the request even when every other field is
- *  perfect. No-op when the propertyName is missing or the variant lacks an
- *  enum/const for that property. */
+ *  perfect.
+ *
+ *  ARV-135: now also honours `discriminator.mapping` — when the picked
+ *  variant has no inline enum/const for the discriminator property, fall
+ *  back to the first mapping key. Specs that declare polymorphism via
+ *  central mapping (rather than inline `enum: ["x"]` on each variant)
+ *  previously left the body un-stamped. */
 function stampDiscriminator(
   result: unknown,
   variant: OpenAPIV3.SchemaObject,
-  propertyName: string | undefined,
+  discriminator: OpenAPIV3.DiscriminatorObject | undefined,
 ): unknown {
+  const propertyName = discriminator?.propertyName;
   if (!propertyName) return result;
   if (!result || typeof result !== "object" || Array.isArray(result)) return result;
-  const prop = variant.properties?.[propertyName] as OpenAPIV3.SchemaObject | undefined;
-  if (!prop) return result;
-  const en = (prop as { enum?: unknown[] }).enum;
-  const cn = (prop as { const?: unknown }).const;
   let stamp: unknown;
-  if (Array.isArray(en) && en.length === 1) stamp = en[0];
-  else if (cn !== undefined && cn !== null) stamp = cn;
-  else return result;
+  const prop = variant.properties?.[propertyName] as OpenAPIV3.SchemaObject | undefined;
+  if (prop) {
+    const en = (prop as { enum?: unknown[] }).enum;
+    const cn = (prop as { const?: unknown }).const;
+    if (Array.isArray(en) && en.length === 1) stamp = en[0];
+    else if (cn !== undefined && cn !== null) stamp = cn;
+  }
+  if (stamp === undefined && discriminator?.mapping) {
+    const keys = Object.keys(discriminator.mapping);
+    if (keys.length > 0) stamp = keys[0];
+  }
+  if (stamp === undefined) return result;
   (result as Record<string, unknown>)[propertyName] = stamp;
   return result;
 }
 
-/** Prefer the most data-shape-informative variant from a oneOf/anyOf list:
- *  object-with-properties > non-null > first. Skips `type: "null"` entries
- *  introduced by 3.1 nullable shorthand. */
-function pickPreferredVariant(variants: OpenAPIV3.SchemaObject[]): OpenAPIV3.SchemaObject {
-  const isNull = (s: OpenAPIV3.SchemaObject) =>
-    (s as { type?: unknown }).type === "null";
-  const nonNull = variants.filter(v => !isNull(v));
-  const pool = nonNull.length > 0 ? nonNull : variants;
-
-  const objectWithProps = pool.find(
-    v => v.type === "object" && v.properties && Object.keys(v.properties).length > 0,
-  );
-  if (objectWithProps) return objectWithProps;
-
-  return pool[0]!;
-}
-
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 /** Names that strongly imply an email field. Kept in sync with the email
@@ -269,7 +329,9 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
  *  email mapping. */
 function isEmailContextName(name?: string): boolean {
   if (!name) return false;
-  const lower = name.toLowerCase();
+  // Canonical snake_case so camelCase (`replyTo`, `userEmail`) matches the
+  // same rules as `reply_to` / `user_email`.
+  const lower = canonicalVarName(name);
   return (
     lower === "email" ||
     lower === "from" ||
@@ -279,9 +341,7 @@ function isEmailContextName(name?: string): boolean {
     lower === "sender" ||
     lower === "recipient" ||
     lower === "reply_to" ||
-    lower === "replyto" ||
     lower.endsWith("_email") ||
-    lower.endsWith("Email") ||
     lower.endsWith("_reply_to") ||
     lower.endsWith("_from") ||
     lower.endsWith("_to") ||
@@ -398,7 +458,7 @@ export function classifyFieldSource(
       return "heuristic:domain-from-description";
     }
     if (propertyName) {
-      const lower = propertyName.toLowerCase();
+      const lower = canonicalVarName(propertyName);
       if (lower === "slug" || lower.endsWith("_slug")) return "heuristic:slug";
       if (lower === "domain" || lower === "hostname" || lower === "fqdn" || lower.endsWith("_domain")) return "heuristic:domain";
       if (lower === "platform") return "heuristic:platform";
@@ -412,13 +472,13 @@ export function classifyFieldSource(
       if (
         lower === "email" || lower === "from" || lower === "to" || lower === "cc" ||
         lower === "bcc" || lower === "sender" || lower === "recipient" ||
-        lower === "reply_to" || lower === "replyto" ||
-        lower.endsWith("_email") || lower.endsWith("Email") ||
+        lower === "reply_to" ||
+        lower.endsWith("_email") ||
         lower.endsWith("_reply_to") || lower.endsWith("_from") ||
         lower.endsWith("_to") || lower.endsWith("_cc") || lower.endsWith("_bcc")
       ) return "heuristic:email";
       if (lower === "id" || lower === "uuid" || lower.endsWith("_id") || lower.endsWith("id")) return "heuristic:id";
-      if (lower === "name" || lower.endsWith("_name") || lower.endsWith("Name")) return "heuristic:name";
+      if (lower === "name" || lower.endsWith("_name")) return "heuristic:name";
       if (lower === "url" || lower.endsWith("_url") || lower === "uri" || lower === "href" || lower === "website") return "heuristic:url";
       if (lower === "password" || lower.endsWith("_password")) return "heuristic:password";
       if (lower === "phone" || lower === "telephone" || lower.endsWith("_phone")) return "heuristic:phone";
@@ -436,6 +496,83 @@ export function classifyFieldSource(
   return "default";
 }
 
+/**
+ * ARV-138: canonicalise a body field name to a manifest/fixture var name.
+ * Converts camelCase → snake_case + lowercase so spec body fields
+ * (`issueId`, `sequenceTypeCode`) collapse onto the same var as the
+ * path-param spelling. Idempotent on already-snake_case input. The HTTP
+ * request still sends the raw field name — only the {{var}} namespace is
+ * normalised. Lives here (leaf module) so both fixtures-builder and
+ * suite-generator can share it without an import cycle.
+ */
+export function canonicalVarName(name: string): string {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[^a-zA-Z0-9]+/g, "_")
+    .toLowerCase();
+}
+
+const FK_ID_SUFFIX = /(?:_id|Id|_uuid)$/;
+const CODE_REF_SUFFIX = /(?:_code|Code)$/;
+
+/**
+ * ARV-45: a required request-body field that is a foreign-key / closed-
+ * vocabulary reference the generator can't synthesise a valid value for —
+ * so the generated test should reference a `{{fixture}}` the user fills in
+ * `.env.yaml`, not random junk that 400s and kills the CRUD chain at step 1.
+ *
+ *  - `*_id` / `*Id` / `*_uuid`: always an FK. `generateFromSchema` emits
+ *    `{{$uuid}}` here — a random id that 404/422s on a live API.
+ *  - `*_code` / `*Code`: a reference code ONLY when no heuristic resolves
+ *    it. `countryCode`/`currencyCode`/`mcc`… already map to real literals
+ *    via `guessStringPlaceholder`, so they're excluded; the domain codes
+ *    that motivated this (`sequenceTypeCode`, `templateGroupCode`) fall
+ *    through to `{{$randomString}}` → 400.
+ *
+ * Enum/format/example-backed fields are never FK fixtures — the spec
+ * already told us a valid value.
+ */
+export function isFkFixtureField(name: string, schema: OpenAPIV3.SchemaObject): boolean {
+  if (schema.enum && schema.enum.length > 0) return false;
+  if (pickExampleValue(schema) !== undefined) return false;
+  if (FK_ID_SUFFIX.test(name)) return true;
+  if (CODE_REF_SUFFIX.test(name)) {
+    return generateFromSchema(schema, name) === "{{$randomString}}";
+  }
+  return false;
+}
+
+/**
+ * Flatten a request-body schema to its effective `{properties, required}`,
+ * merging `allOf` branches. .NET / Swagger-gen specs wrap almost every model
+ * in `allOf: [{...}]` (inheritance), so a direct `schema.properties` read sees
+ * nothing — `generateFromSchema` already merges allOf when producing the body,
+ * and FK wiring / the manifest must resolve the same shape or they silently
+ * miss every FK field on these specs. Recurses through nested allOf; ignores
+ * oneOf/anyOf (the generator picks one variant there, out of scope for FK
+ * wiring until a real spec needs it).
+ */
+export function effectiveObjectShape(
+  schema: OpenAPIV3.SchemaObject,
+): { properties: Record<string, OpenAPIV3.SchemaObject>; required: Set<string> } {
+  const properties: Record<string, OpenAPIV3.SchemaObject> = {};
+  const required = new Set<string>();
+  const visit = (s: OpenAPIV3.SchemaObject | undefined) => {
+    if (!s || typeof s !== "object") return;
+    if (Array.isArray(s.allOf)) {
+      for (const sub of s.allOf) visit(sub as OpenAPIV3.SchemaObject);
+    }
+    if (s.properties) {
+      for (const [k, v] of Object.entries(s.properties)) {
+        properties[k] = v as OpenAPIV3.SchemaObject;
+      }
+    }
+    if (Array.isArray(s.required)) for (const r of s.required) required.add(r);
+  };
+  visit(schema);
+  return { properties, required };
+}
+
 /**
  * Map an OpenAPI `format` value to a zond generator placeholder. Returns
  * undefined when the format is unknown or absent so callers can fall back
@@ -533,9 +670,12 @@ function guessStringPlaceholder(schema: OpenAPIV3.SchemaObject, name?: string):
     return "{{$randomDomain}}";
   }
 
-  // Name-based heuristics
+  // Name-based heuristics. Match on the canonical snake_case form so
+  // camelCase fields (`countryCode`, `firstName`, `userEmail`) hit the same
+  // rules as their snake_case spelling — otherwise they fall through to
+  // {{$randomString}} and 400 on closed-vocab/format-strict APIs.
   if (name) {
-    const lower = name.toLowerCase();
+    const lower = canonicalVarName(name);
     if (lower === "slug" || lower.endsWith("_slug")) {
       return "{{$randomSlug}}";
     }
@@ -575,9 +715,7 @@ function guessStringPlaceholder(schema: OpenAPIV3.SchemaObject, name?: string):
       lower === "sender" ||
       lower === "recipient" ||
       lower === "reply_to" ||
-      lower === "replyto" ||
       lower.endsWith("_email") ||
-      lower.endsWith("Email") ||
       lower.endsWith("_reply_to") ||
       lower.endsWith("_from") ||
       lower.endsWith("_to") ||
@@ -589,7 +727,7 @@ function guessStringPlaceholder(schema: OpenAPIV3.SchemaObject, name?: string):
     if (lower === "id" || lower === "uuid" || lower.endsWith("_id") || lower.endsWith("id")) {
       return "{{$uuid}}";
     }
-    if (lower === "name" || lower.endsWith("_name") || lower.endsWith("Name")) {
+    if (lower === "name" || lower.endsWith("_name")) {
       return "{{$randomName}}";
     }
     if (lower === "url" || lower.endsWith("_url") || lower === "uri" || lower === "href" || lower === "website") {