@kirrosh/zond 0.22.0 → 0.26.0

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

@@ -3,18 +3,46 @@ import type { OpenAPIV3 } from "openapi-types";
 /**
  * Recursively generates test data from an OpenAPI schema.
  * Uses heuristic placeholders ({{$...}} generators) where possible.
+ *
+ * `forRequest` (default true) toggles request-body filters that strip
+ * server-assigned fields the client must not send: properties marked
+ * `readOnly: true`, and the literal field name `id` at any object level
+ * (universally server-assigned in REST). Pass `forRequest: false` to
+ * preserve full schema shape for response-side fixtures.
  */
 export function generateFromSchema(
   schema: OpenAPIV3.SchemaObject,
   propertyName?: string,
-  _depth = 0,
+  opts: { _depth?: number; forRequest?: boolean } = {},
 ): unknown {
-  if (_depth > 5) return {};
+  const _depth = opts._depth ?? 0;
+  const forRequest = opts.forRequest ?? true;
+  const recurse = (s: OpenAPIV3.SchemaObject, name?: string) =>
+    generateFromSchema(s, name, { _depth: _depth + 1, forRequest });
+
+  if (_depth > 7) {
+    return depthLimitDefault(schema, propertyName);
+  }
 
   // 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;
+  // Two exceptions:
+  //   1. `null` examples are noise (often nullable: true with no real example) —
+  //      skip so we fall through to type/format defaults instead of emitting null.
+  //   2. UUID-shaped examples on FK-context fields (name ends with `_id` or
+  //      schema.format === "uuid") are usually copy-pasted from another tenant's
+  //      spec. Honoring them leaks foreign IDs and guarantees 422 on real APIs;
+  //      `{{$uuid}}` is at least an honest test placeholder.
+  //
+  // OpenAPI 3.1 / JSON Schema also allows `examples: [...]` (plural array). When
+  // both are present `example` wins; otherwise pick the first non-null entry
+  // from `examples` and apply the same FK-UUID guard. `example` (singular) is
+  // still the OpenAPI 3.0 form and remains supported.
+  const exampleValue = pickExampleValue(schema);
+  if (exampleValue !== undefined) {
+    if (!isLikelyForeignFKExample(schema, propertyName, exampleValue)) {
+      return exampleValue;
+    }
   }
 
   // allOf: merge all schemas
@@ -26,15 +54,31 @@ export function generateFromSchema(
         merged.properties = { ...merged.properties, ...s.properties };
       }
     }
-    return generateFromSchema(merged, propertyName, _depth + 1);
+    return recurse(merged, propertyName);
   }
 
-  // oneOf / anyOf: use first variant
+  // oneOf / anyOf: pick the most informative variant. Prefer objects with
+  // properties over loose primitives — APIs that accept `Array<{id}>|Array<string>`
+  // need the object variant, not a string that 422s. Falls back to first
+  // non-null entry.
+  //
+  // ARV-78 (feedback round-04 / F25): when the parent schema declares a
+  // `discriminator: { propertyName, mapping? }` (typical OpenAPI 3 polymorphism —
+  // /automations.steps with type=trigger|action), pick the variant whose
+  // discriminator property carries a const/enum-single value and stamp that
+  // value into the result. Without this, generator emits a random variant and
+  // the API 422s with "Missing <required-by-other-variant>".
   if (schema.oneOf) {
-    return generateFromSchema(schema.oneOf[0] as OpenAPIV3.SchemaObject, propertyName, _depth + 1);
+    const variants = schema.oneOf as OpenAPIV3.SchemaObject[];
+    const picked = pickBestVariant(variants, schema.discriminator);
+    const result = recurse(picked, propertyName);
+    return stampDiscriminator(result, picked, schema.discriminator);
   }
   if (schema.anyOf) {
-    return generateFromSchema(schema.anyOf[0] as OpenAPIV3.SchemaObject, propertyName, _depth + 1);
+    const variants = schema.anyOf as OpenAPIV3.SchemaObject[];
+    const picked = pickBestVariant(variants, schema.discriminator);
+    const result = recurse(picked, propertyName);
+    return stampDiscriminator(result, picked, schema.discriminator);
   }
 
   // enum: first value (always valid for the API contract)
@@ -52,10 +96,23 @@ export function generateFromSchema(
 
   // 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)
+  let effectiveType = Array.isArray(schema.type)
     ? (schema.type as string[]).find(t => t !== "null") as OpenAPIV3.SchemaObject["type"] | undefined
     : schema.type;
 
+  // ARV-67 (feedback round-01 / F7): schemas in the wild routinely omit
+  // `type` on nested-object fields and rely on `properties` / `required`
+  // / `items` to convey shape. Without the salvage below, the default
+  // branch returns "{{$randomString}}" for a missing-type field — which
+  // is what made `prepare-fixtures --seed` send a string for nested
+  // objects like `automations.config` / `automations.steps` and earn
+  // "Expected object, received string" 422s. Infer the type
+  // from structural hints when nothing else gives one.
+  if (effectiveType === undefined) {
+    if ((schema as { items?: unknown }).items !== undefined) effectiveType = "array";
+    else if (schema.properties || Array.isArray(schema.required)) effectiveType = "object";
+  }
+
   switch (effectiveType) {
     case "string":
       return guessStringPlaceholder(schema, propertyName);
@@ -72,7 +129,7 @@ export function generateFromSchema(
     case "array": {
       const arr = schema as OpenAPIV3.ArraySchemaObject;
       if (arr.items) {
-        const item = generateFromSchema(arr.items as OpenAPIV3.SchemaObject, undefined, _depth + 1);
+        const item = recurse(arr.items as OpenAPIV3.SchemaObject, undefined);
         return [item];
       }
       return [];
@@ -84,17 +141,24 @@ export function generateFromSchema(
       if (schema.properties) {
         const obj: Record<string, unknown> = {};
         for (const [key, propSchema] of Object.entries(schema.properties)) {
-          obj[key] = generateFromSchema(propSchema as OpenAPIV3.SchemaObject, key, _depth + 1);
+          const ps = propSchema as OpenAPIV3.SchemaObject;
+          if (forRequest && shouldSkipForRequest(key, ps)) continue;
+          obj[key] = recurse(ps, key);
         }
         return obj;
       }
-      // Record type: additionalProperties defines value schema
-      if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
-        const valSchema = schema.additionalProperties as OpenAPIV3.SchemaObject;
-        return { key1: generateFromSchema(valSchema, "key1", _depth + 1), key2: generateFromSchema(valSchema, "key2", _depth + 1) };
-      }
-      if (schema.additionalProperties === true) {
-        return { key1: "value1", key2: "value2" };
+      // Record type (additionalProperties only). The historical behavior was
+      // to materialize fake `key1`/`key2` entries to make the shape visible.
+      // Real APIs reject those — the keys are always domain-specific
+      // (filter names, label keys). Emit an empty `{}` instead: it preserves
+      // the object type (so type-validators pass) without injecting payloads
+      // the server didn't ask for. Callers who need realistic record content
+      // should override via fixture-pack/.env.yaml.
+      if (
+        (schema.additionalProperties && typeof schema.additionalProperties === "object") ||
+        schema.additionalProperties === true
+      ) {
+        return {};
       }
       // Bare object with no properties
       if (effectiveType === "object") {
@@ -105,6 +169,410 @@ 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.
+ *
+ *  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. */
+function depthLimitDefault(schema: OpenAPIV3.SchemaObject, name?: string): unknown {
+  const t = Array.isArray(schema.type)
+    ? (schema.type as string[]).find(x => x !== "null")
+    : schema.type;
+  switch (t) {
+    case "string": return formatToPlaceholder(schema.format) ?? guessStringPlaceholder(schema, name);
+    case "integer": return 1;
+    case "number": return 1;
+    case "boolean": return true;
+    case "array": return [];
+    case "object":
+    default: return {};
+  }
+}
+
+/** 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[],
+  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;
+    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.
+ *
+ *  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,
+  discriminator: OpenAPIV3.DiscriminatorObject | undefined,
+): unknown {
+  const propertyName = discriminator?.propertyName;
+  if (!propertyName) return result;
+  if (!result || typeof result !== "object" || Array.isArray(result)) return result;
+  let stamp: unknown;
+  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;
+}
+
+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
+ *  branch of `guessStringPlaceholder`/`classifyFieldSource`. Used to gate the
+ *  description-based domain heuristic so phrases like "verified sending
+ *  domain" in the description of a `from`/`to` field don't override the
+ *  email mapping. */
+function isEmailContextName(name?: string): boolean {
+  if (!name) return false;
+  // 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" ||
+    lower === "to" ||
+    lower === "cc" ||
+    lower === "bcc" ||
+    lower === "sender" ||
+    lower === "recipient" ||
+    lower === "reply_to" ||
+    lower.endsWith("_email") ||
+    lower.endsWith("_reply_to") ||
+    lower.endsWith("_from") ||
+    lower.endsWith("_to") ||
+    lower.endsWith("_cc") ||
+    lower.endsWith("_bcc")
+  );
+}
+
+/** A schema `pattern` that explicitly allows lowercase but not uppercase
+ *  letters (typical slug regex like `^[a-z0-9_\-]+$`). Used to switch from
+ *  mixed-case `{{$randomString}}` to a slug-shaped generator. */
+function isLowercaseOnlyPattern(pattern: string | undefined): boolean {
+  if (!pattern) return false;
+  return pattern.includes("a-z") && !pattern.includes("A-Z");
+}
+
+/** A string example shaped like a UUID, on a field that looks like a foreign
+ *  key (name ends with `_id` or schema declares `format: uuid`), is almost
+ *  always a tenant-specific value the spec author left in `example:`. Sending
+ *  it verbatim guarantees 422 on a fresh account and leaks foreign IDs. */
+function isLikelyForeignFKExample(
+  schema: OpenAPIV3.SchemaObject,
+  name?: string,
+  value?: unknown,
+): boolean {
+  const ex = value !== undefined ? value : schema.example;
+  if (typeof ex !== "string") return false;
+  if (!UUID_RE.test(ex)) return false;
+  const fkByName = !!name && name.toLowerCase().endsWith("_id");
+  const fkByFormat = schema.format === "uuid";
+  return fkByName || fkByFormat;
+}
+
+/** Resolve the effective example value from a schema, supporting both
+ *  OpenAPI 3.0 `example` (singular) and OpenAPI 3.1 / JSON Schema `examples`
+ *  (plural array). `example` wins when both are set — it's the more
+ *  intentional, single-source signal. `null` is treated as "no example"
+ *  (see TASK-221). For `examples`, we pick the first non-null entry. */
+function pickExampleValue(schema: OpenAPIV3.SchemaObject): unknown {
+  if (schema.example !== undefined && schema.example !== null) {
+    return schema.example;
+  }
+  const examples = (schema as { examples?: unknown }).examples;
+  if (Array.isArray(examples)) {
+    for (const ex of examples) {
+      if (ex !== null && ex !== undefined) return ex;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * TASK-269 — per-field provenance for `zond generate --explain`.
+ *
+ * Returns a label describing *why* `generateFromSchema` would emit the
+ * value it does for a given (schema, propertyName). Mirrors the dispatch
+ * priority in `generateFromSchema` without producing the value, so
+ * `--explain` can show "name → {{$randomName}} [heuristic:name]" without
+ * re-executing generation.
+ *
+ * Kept as a parallel function instead of refactoring `generateFromSchema`
+ * to record sources — the recursion path-tracking complexity would
+ * outweigh the value for what is currently a debug-only surface. The
+ * heuristic order here MUST stay in lockstep with the function above; a
+ * unit test (data-factory.test.ts) pins the labels for each branch.
+ */
+export type FieldSource =
+  | "example"
+  | "examples"
+  | "enum"
+  | "format"
+  | "pattern"
+  | "min"
+  | "max"
+  | "random"
+  | "default"
+  | `heuristic:${string}`;
+
+export function classifyFieldSource(
+  schema: OpenAPIV3.SchemaObject,
+  propertyName?: string,
+): FieldSource {
+  // example > examples (3.1) — same FK-UUID guard as generateFromSchema.
+  if (schema.example !== undefined && schema.example !== null) {
+    if (!isLikelyForeignFKExample(schema, propertyName, schema.example)) {
+      return "example";
+    }
+  }
+  const examples = (schema as { examples?: unknown }).examples;
+  if (Array.isArray(examples)) {
+    for (const ex of examples) {
+      if (ex === null || ex === undefined) continue;
+      if (!isLikelyForeignFKExample(schema, propertyName, ex)) return "examples";
+      break;
+    }
+  }
+  if (schema.enum && schema.enum.length > 0) return "enum";
+  if (formatToPlaceholder(schema.format) !== undefined) return "format";
+
+  const t = Array.isArray(schema.type)
+    ? (schema.type as string[]).find(x => x !== "null")
+    : schema.type;
+
+  if (t === "string") {
+    // ARV-38: keep --explain in sync with guessStringPlaceholder — when a
+    // default is consumed, label the source as "default", not "random".
+    if (typeof schema.default === "string" && schema.default.length > 0) return "default";
+    if (isLowercaseOnlyPattern(schema.pattern)) return "pattern";
+    if (
+      schema.description &&
+      /\b(domain|hostname|fqdn)\b/i.test(schema.description) &&
+      !isEmailContextName(propertyName)
+    ) {
+      return "heuristic:domain-from-description";
+    }
+    if (propertyName) {
+      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";
+      if (lower === "language" || lower === "lang" || lower === "locale") return "heuristic:locale";
+      if (lower === "country" || lower === "country_code" || lower.endsWith("_country") || lower.endsWith("_country_code")) return "heuristic:country";
+      if (lower === "timezone" || lower === "time_zone" || lower === "tz") return "heuristic:timezone";
+      if (lower === "currency" || lower === "currency_code" || lower.endsWith("_currency") || lower.endsWith("_currency_code")) return "heuristic:currency";
+      if (lower === "mcc" || lower.endsWith("_mcc") || lower === "merchant_category_code") return "heuristic:mcc";
+      if (lower === "color" || lower.endsWith("_color") || lower === "background_color" || lower === "hex" || lower.endsWith("_hex_color")) return "heuristic:color";
+      if (lower === "ip" || lower === "ip_address" || lower.endsWith("_ip") || lower.endsWith("_ip_address")) return "heuristic:ip";
+      if (
+        lower === "email" || lower === "from" || lower === "to" || lower === "cc" ||
+        lower === "bcc" || lower === "sender" || lower === "recipient" ||
+        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")) 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";
+    }
+    return "random";
+  }
+
+  if (t === "integer") {
+    if (schema.maximum !== undefined) return "max";
+    if (schema.minimum !== undefined && schema.minimum > 0) return "min";
+    return "random";
+  }
+
+  if (t === "number" || t === "boolean") return "default";
+  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
@@ -122,6 +590,20 @@ export function formatToPlaceholder(format: string | undefined): string | undefi
     case "ipv4": return "{{$randomIpv4}}";
     case "ipv6": return "::1";
     case "password": return "TestPass123!";
+    // ARV-165: format-aware helpers. None of these are standard OpenAPI 3.x
+    // formats, but Stripe/GitHub/Shopify/Twilio specs frequently carry them
+    // as ad-hoc `format:` tags. Falling through to {{$randomString}} guarantees
+    // 400 from format-validated APIs (R09 finding: 199 hit-but-fail Stripe steps).
+    case "iso-country-code":
+    case "country-code":
+    case "country": return "{{$randomCountryCode}}";
+    case "iso-currency-code":
+    case "currency-code":
+    case "currency": return "{{$randomCurrencyCode}}";
+    case "mcc": return "{{$randomMCC}}";
+    case "color":
+    case "hex-color":
+    case "rgb-hex": return "{{$randomColorHex}}";
     default: return undefined;
   }
 }
@@ -139,6 +621,7 @@ export function generateMultipartFromSchema(
 
   for (const [key, propSchema] of Object.entries(schema.properties)) {
     const s = propSchema as OpenAPIV3.SchemaObject;
+    if (shouldSkipForRequest(key, s)) continue;
     if (s.format === "binary" || s.format === "byte") {
       result[key] = { file: `./fixtures/${key}.bin`, content_type: "application/octet-stream" };
     } else {
@@ -154,16 +637,97 @@ function guessStringPlaceholder(schema: OpenAPIV3.SchemaObject, name?: string):
   // Format-based dispatch already happened earlier in generateFromSchema;
   // this branch only sees strings whose format is empty or unrecognised.
 
-  // Name-based heuristics
+  // ARV-38: when the spec declares a JSON-Schema `default` for a string-typed
+  // field with no enum, prefer it over heuristics. PATCH endpoints in
+  // particular rely on this — e.g. a `PATCH /domains/{id}` with
+  // `tls: { type: string, default: "opportunistic" }` would otherwise get
+  // a random fallback and a guaranteed 422 every run.
+  if (typeof schema.default === "string" && schema.default.length > 0) {
+    return schema.default;
+  }
+
+  // Pattern-aware: many specs constrain slugs via regex like
+  // `^(?![0-9]+$)[a-z0-9_\-]+$` without setting `format`. Default
+  // `{{$randomString}}` mixes upper+lower → 400 from the validator.
+  // Heuristic: pattern allows `a-z` but forbids `A-Z` → emit a slug.
+  if (isLowercaseOnlyPattern(schema.pattern)) {
+    return "{{$randomSlug}}";
+  }
+
+  // Description-aware: when the schema describes a domain/hostname (e.g.
+  // a `POST /domains/`-style endpoint or DNS-zone create route) but the
+  // field is generically named `name`, the default `{{$randomName}}`
+  // returns "Bob Wilson" and the server rejects it. TASK-224.
+  // Skip when the field name is clearly in email vocabulary — email-API
+  // specs often describe `from`/`to`/etc. with phrases like "verified
+  // sending domain" or "Name <user@domain>", which trips the regex but
+  // the field is an email, not a domain. Email vocab > domain-from-description.
+  if (
+    schema.description &&
+    /\b(domain|hostname|fqdn)\b/i.test(schema.description) &&
+    !isEmailContextName(name)
+  ) {
+    return "{{$randomDomain}}";
+  }
+
+  // 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();
-    if (lower === "email" || lower.endsWith("_email") || lower.endsWith("Email")) {
+    const lower = canonicalVarName(name);
+    if (lower === "slug" || lower.endsWith("_slug")) {
+      return "{{$randomSlug}}";
+    }
+    if (lower === "domain" || lower === "hostname" || lower === "fqdn" || lower.endsWith("_domain")) {
+      return "{{$randomDomain}}";
+    }
+    // Closed-vocabulary fields where servers validate against an internal
+    // dictionary even when the spec lacks `enum:`. Random strings → 400.
+    // Pick the most universally-accepted value per dictionary.
+    if (lower === "platform") return "python";
+    if (lower === "language" || lower === "lang" || lower === "locale") return "en";
+    // ARV-165: country/currency literals (US/USD) were universally accepted
+    // but offered zero variety — added endsWith() patterns so nested fields
+    // like `bank_account.country`, `payout.currency_code`, `from_country`
+    // also resolve. Still emit a literal — picking from the random helper
+    // would weaken the "always-valid" property for downstream assertions
+    // that pin on the first value.
+    if (lower === "country" || lower === "country_code" || lower.endsWith("_country") || lower.endsWith("_country_code")) return "US";
+    if (lower === "timezone" || lower === "time_zone" || lower === "tz") return "UTC";
+    if (lower === "currency" || lower === "currency_code" || lower.endsWith("_currency") || lower.endsWith("_currency_code")) return "USD";
+    // ARV-165: MCC (merchant category code) — Stripe/Square/issuing APIs.
+    // Random {{$randomString}} → 400 because it's not a 4-digit code.
+    if (lower === "mcc" || lower.endsWith("_mcc") || lower === "merchant_category_code") return "{{$randomMCC}}";
+    // ARV-165: hex color — Stripe brand settings, Slack themes, GitHub labels.
+    if (lower === "color" || lower.endsWith("_color") || lower === "background_color" || lower === "hex" || lower.endsWith("_hex_color")) return "{{$randomColorHex}}";
+    // ARV-165: IP addresses — Stripe tos_acceptance.ip, audit logs, fraud APIs.
+    if (lower === "ip" || lower === "ip_address" || lower.endsWith("_ip") || lower.endsWith("_ip_address")) return "{{$randomIpv4}}";
+    // Email-context fields. Email-API specs often
+    // omit `format: email` on `from`/`to`/`reply_to`/`cc`/`bcc` — the field
+    // name is the only clue, and `{{$randomString}}` guarantees a 422.
+    if (
+      lower === "email" ||
+      lower === "from" ||
+      lower === "to" ||
+      lower === "cc" ||
+      lower === "bcc" ||
+      lower === "sender" ||
+      lower === "recipient" ||
+      lower === "reply_to" ||
+      lower.endsWith("_email") ||
+      lower.endsWith("_reply_to") ||
+      lower.endsWith("_from") ||
+      lower.endsWith("_to") ||
+      lower.endsWith("_cc") ||
+      lower.endsWith("_bcc")
+    ) {
       return "{{$randomEmail}}";
     }
     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") {