@sungen/driver-api 3.2.4 → 3.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-api",
-  "version": "3.2.4",
+  "version": "3.2.6",
   "description": "Sungen API capability — the @api annotation, API catalog, OpenAPI import + `sungen api import`, and the specs/api.ts runtime template. Plugs into @sun-asterisk/sungen via the capability SPI.",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -13,7 +13,7 @@
   "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "dependencies": {
-    "@sun-asterisk/sungen": "3.2.4",
+    "@sun-asterisk/sungen": "3.2.6",
     "commander": "^14.0.2",
     "yaml": "^2.8.2"
   },

package/src/api-catalog.ts

@@ -17,6 +17,11 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { parse as parseYaml } from 'yaml';
+import { parseFileSpec, parseFiles, type FileFieldSpec } from './api-file-fields';
+import { parseFields, type FieldSpec } from './api-field-spec';
+
+export type { FileFieldSpec } from './api-file-fields';
+export type { FieldSpec } from './api-field-spec';
 
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
 const METHODS = new Set<string>(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
@@ -28,8 +33,14 @@ export interface ApiEntry {
   path: string;
   body?: unknown;
   encoding?: 'json' | 'form' | 'multipart'; // request-body wire format (default json); form = application/x-www-form-urlencoded
+  files?: Record<string, FileFieldSpec>; // multipart/form-data file fields (file as a form part) — presence forces multipart
+  bodyFile?: FileFieldSpec; // raw-binary body: the request body IS the file's bytes (Content-Type = mimeType, default application/octet-stream)
   headers?: Record<string, string>; // per-endpoint header templates; `:param` tokens bind at runtime (flow auth, e.g. authorization: "Bearer :token")
   params: string[];
+  timeout_ms?: number; // per-endpoint request timeout override (else the datasource timeout, default 15s)
+  fields?: Record<string, FieldSpec>; // optional field metadata (required/type/enum/range) — drives error+boundary matrices + the viewpoint gate
+  responseSchema?: unknown; // inline 2xx response body schema (JSON Schema) — for `matches schema` assertions
+  schemaRef?: string;       // named schema (schemas.yaml key) for the 2xx response body
   expect?: { status?: number | string };
   description?: string;
   scope: 'screen' | 'shared';
@@ -70,12 +81,14 @@ function refsIn(text: string): string[] {
   return (text.match(/:([A-Za-z_][A-Za-z0-9_]*)/g) || []).map((s) => s.slice(1));
 }
 
-/** All `:param` refs an entry binds — path + JSON body + header templates. */
+/** All `:param` refs an entry binds — path + JSON body + header templates + file specs. */
 function entryRefs(entry: ApiEntry): string[] {
   const fromPath = refsIn(entry.path);
   const fromBody = entry.body != null ? refsIn(JSON.stringify(entry.body)) : [];
   const fromHeaders = entry.headers ? refsIn(JSON.stringify(entry.headers)) : [];
-  return [...new Set([...fromPath, ...fromBody, ...fromHeaders])];
+  const fromFiles = entry.files ? refsIn(JSON.stringify(entry.files)) : [];
+  const fromBodyFile = entry.bodyFile ? refsIn(JSON.stringify(entry.bodyFile)) : [];
+  return [...new Set([...fromPath, ...fromBody, ...fromHeaders, ...fromFiles, ...fromBodyFile])];
 }
 
 function parseEntries(file: string, scope: 'screen' | 'shared'): Map<string, ApiEntry> {
@@ -91,8 +104,14 @@ function parseEntries(file: string, scope: 'screen' | 'shared'): Map<string, Api
       path: v.path,
       body: v.body,
       encoding: v.encoding === 'form' || v.encoding === 'multipart' ? v.encoding : undefined, // default (undefined) = json
+      files: parseFiles(v.files),
+      bodyFile: parseFileSpec(v.bodyFile),
       headers: v.headers && typeof v.headers === 'object' ? Object.fromEntries(Object.entries(v.headers).map(([k, hv]) => [k, String(hv)])) : undefined,
       params: Array.isArray(v.params) ? v.params.map((p: any) => String(p)) : [],
+      timeout_ms: typeof v.timeout_ms === 'number' && v.timeout_ms > 0 ? v.timeout_ms : undefined,
+      fields: parseFields(v.fields),
+      responseSchema: v.responseSchema,
+      schemaRef: typeof v.schemaRef === 'string' ? v.schemaRef : undefined,
       expect: v.expect && typeof v.expect === 'object' ? { status: v.expect.status } : undefined,
       description: typeof v.description === 'string' ? v.description : undefined,
       scope,
@@ -150,6 +169,14 @@ export function validateApiEntry(entry: ApiEntry, datasourceNames: string[] | nu
   const declared = new Set(entry.params);
   for (const r of refs) if (!declared.has(r)) errs.push(`api "${entry.name}": uses :${r} but it is not in params:.`);
   for (const d of declared) if (!refs.has(d)) errs.push(`api "${entry.name}": param "${d}" is declared but never used in path/body.`);
+  if (entry.files) {
+    for (const [field, spec] of Object.entries(entry.files)) if (!spec.path) errs.push(`api "${entry.name}": file field "${field}" has no path.`);
+    // files are always sent as multipart; an explicit json/form encoding contradicts that.
+    if (entry.encoding && entry.encoding !== 'multipart') errs.push(`api "${entry.name}": has files: but encoding: ${entry.encoding} — a file upload must be multipart (omit encoding).`);
+  }
+  if (entry.bodyFile && !entry.bodyFile.path) errs.push(`api "${entry.name}": bodyFile has no path.`);
+  if (entry.bodyFile && entry.files) errs.push(`api "${entry.name}": use either files: (multipart form parts) or bodyFile: (raw binary body), not both.`);
+  if (entry.bodyFile && entry.body !== undefined) errs.push(`api "${entry.name}": bodyFile: (raw binary body) cannot combine with a body:.`);
   if (datasourceNames && entry.datasource && !datasourceNames.includes(entry.datasource)) {
     errs.push(`api "${entry.name}": datasource "${entry.datasource}" is not defined in datasources.yaml.`);
   }

package/src/api-context.ts

@@ -11,8 +11,13 @@ import type { Context, DiscoveryProvider, ContextMapper, GenerationUnit } from '
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { lintApiCatalog } from './api-catalog';
+import type { FieldSpec } from './api-field-spec';
 
-interface EndpointFact { name: string; method: string; path: string; datasource?: string; expectStatus?: number | string }
+interface EndpointFact {
+  name: string; method: string; path: string; datasource?: string; expectStatus?: number | string;
+  fields?: Record<string, FieldSpec>; // field metadata → the coverage model enumerates required/boundary/format matrices from it
+  schemaRef?: string;                  // response-schema name → the contract case can assert `matches schema`
+}
 
 const MUTATING = /^(POST|PUT|PATCH|DELETE)$/;
 
@@ -25,6 +30,7 @@ export const apiDiscovery: DiscoveryProvider = {
     try {
       endpoints = lintApiCatalog(unitId, null, cwd).entries.map((e) => ({
         name: e.name, method: e.method, path: e.path, datasource: e.datasource, expectStatus: e.expect?.status,
+        ...(e.fields ? { fields: e.fields } : {}), ...(e.schemaRef ? { schemaRef: e.schemaRef } : {}),
       }));
     } catch { /* no catalog → the verification gate reports it */ }
 

package/src/api-field-coverage.ts

@@ -0,0 +1,115 @@
+/**
+ * Field-driven matrix coverage — the deterministic backstop for the `fields:` block.
+ *
+ * The coverage model (skill) makes the generator enumerate the required / boundary / format matrix
+ * mechanically from `fields:`; this module is the AUDIT backstop that flags when it didn't. For each
+ * endpoint that declares `fields:`, it checks the `@cases` rows of the scenarios referencing it and
+ * reports any constrained field with no matching negative case:
+ *   - REQUIRED  — a `required` field with no row that omits/empties it asserting a 4xx
+ *   - BOUNDARY  — a `min/max/minLength/maxLength` field with no row whose value is out of range (4xx)
+ *   - FORMAT    — an enum field with no row whose value is outside its `values` (4xx)
+ *
+ * Advisory only (warn). It NEVER fires on a catalog without `fields:` (no false demands). When an
+ * endpoint's `@cases` rows can't be resolved from test-data (or there are none), that IS the honest
+ * "no negative case" signal → it flags. It never THROWS on a missing/unparseable file (fail-safe):
+ * an unreadable dataset degrades to "no rows", not a crash. (The sensor additionally suppresses the
+ * finding when the endpoint tests errors via an inline 4xx instead of `@cases` — see index.ts.)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import type { FieldSpec } from './api-field-spec';
+
+export interface FieldCoverageGap {
+  endpoint: string;
+  kind: 'required' | 'boundary' | 'format';
+  fields: string[]; // the uncovered field names
+}
+
+interface CaseRow { [col: string]: unknown }
+
+/** Locate + read the test-data file for a unit, mirroring the api-catalog path rules. Undefined on miss. */
+function readUnitTestData(screenName: string, cwd: string): Record<string, unknown> | undefined {
+  if (!screenName) return undefined;
+  const unitDir = screenName.startsWith('flows/') || screenName.startsWith('api/')
+    ? path.join(cwd, 'qa', screenName)
+    : path.join(cwd, 'qa', 'screens', screenName);
+  const base = path.basename(screenName);
+  const file = path.join(unitDir, 'test-data', `${base}.yaml`);
+  try {
+    if (!fs.existsSync(file)) return undefined;
+    const doc = parseYaml(fs.readFileSync(file, 'utf8'));
+    return doc && typeof doc === 'object' ? (doc as Record<string, unknown>) : undefined;
+  } catch { return undefined; }
+}
+
+/** Resolve a `@cases:<name>` dataset (a list of row objects) from the unit's test-data. */
+function resolveDataset(testData: Record<string, unknown> | undefined, name: string): CaseRow[] | undefined {
+  if (!testData) return undefined;
+  const v = testData[name];
+  if (!Array.isArray(v)) return undefined;
+  return v.filter((r): r is CaseRow => !!r && typeof r === 'object' && !Array.isArray(r));
+}
+
+const is4xx = (row: CaseRow): boolean => /^4\d\d$/.test(String(row.expect_status ?? row.status ?? '').trim());
+const missing = (row: CaseRow, col: string): boolean => !(col in row) || String(row[col] ?? '').trim() === '';
+const numOf = (v: unknown): number | undefined => { const n = Number(String(v).trim()); return Number.isFinite(n) ? n : undefined; };
+
+/** A row proves field `col` is out of its numeric/length range (→ expects 4xx). */
+function violatesBoundary(row: CaseRow, col: string, spec: FieldSpec): boolean {
+  if (!(col in row) || String(row[col] ?? '').trim() === '') return false;
+  const raw = String(row[col]).trim();
+  if (spec.min != null || spec.max != null) {
+    const n = numOf(raw);
+    if (n != null && ((spec.min != null && n < spec.min) || (spec.max != null && n > spec.max))) return true;
+  }
+  if (spec.minLength != null || spec.maxLength != null) {
+    const len = raw.length;
+    if ((spec.minLength != null && len < spec.minLength) || (spec.maxLength != null && len > spec.maxLength)) return true;
+  }
+  return false;
+}
+
+/** A row proves field `col` is outside its enum values (→ expects 4xx). */
+function violatesEnum(row: CaseRow, col: string, spec: FieldSpec): boolean {
+  if (!spec.values || !(col in row)) return false;
+  const raw = String(row[col] ?? '').trim();
+  if (raw === '') return false;
+  return !spec.values.map((x) => String(x)).includes(raw);
+}
+
+/**
+ * Compute the field-coverage gaps for one endpoint given its `fields:` and the `@cases` datasets of
+ * the scenarios that reference it. Returns [] when there's nothing to say (fail-quiet on unresolved
+ * datasets: an endpoint with `fields:` but no resolvable rows yields the REQUIRED/BOUNDARY/FORMAT
+ * gaps for "no negative case at all", which is the honest signal).
+ */
+export function fieldCoverageGaps(
+  endpoint: string,
+  fields: Record<string, FieldSpec>,
+  datasetNames: string[],
+  testData: Record<string, unknown> | undefined,
+): FieldCoverageGap[] {
+  const rows: CaseRow[] = [];
+  for (const name of datasetNames) { const ds = resolveDataset(testData, name); if (ds) rows.push(...ds); }
+  const errorRows = rows.filter(is4xx);
+
+  const requiredUncovered: string[] = [];
+  const boundaryUncovered: string[] = [];
+  const formatUncovered: string[] = [];
+
+  for (const [name, spec] of Object.entries(fields)) {
+    if (spec.required && !errorRows.some((r) => missing(r, name))) requiredUncovered.push(name);
+    const hasRange = spec.min != null || spec.max != null || spec.minLength != null || spec.maxLength != null;
+    if (hasRange && !errorRows.some((r) => violatesBoundary(r, name, spec))) boundaryUncovered.push(name);
+    if (spec.values && spec.values.length && !errorRows.some((r) => violatesEnum(r, name, spec))) formatUncovered.push(name);
+  }
+
+  const gaps: FieldCoverageGap[] = [];
+  if (requiredUncovered.length) gaps.push({ endpoint, kind: 'required', fields: requiredUncovered });
+  if (boundaryUncovered.length) gaps.push({ endpoint, kind: 'boundary', fields: boundaryUncovered });
+  if (formatUncovered.length) gaps.push({ endpoint, kind: 'format', fields: formatUncovered });
+  return gaps;
+}
+
+export { readUnitTestData };

package/src/api-field-spec.ts

@@ -0,0 +1,136 @@
+/**
+ * Field metadata for the API catalog — the optional `fields:` block on an `apis.yaml` entry.
+ *
+ * The flat `params:` list says WHICH inputs an endpoint takes; `fields:` says WHAT each one is —
+ * required?, type/format, range/length, enum, pattern, uniqueness, and where it lives (body / query /
+ * header). This is the metadata the coverage model + the viewpoint gate need to enumerate the
+ * required / boundary / format matrices mechanically instead of the AI guessing them.
+ *
+ * Additive + optional: an entry with no `fields:` behaves exactly as before. Derivable from OpenAPI
+ * (`sungen api import` populates it from the request schema + declared parameters), so imported
+ * catalogs need no hand-authoring for standard specs.
+ */
+
+export type FieldType = 'string' | 'integer' | 'number' | 'boolean' | 'enum' | 'array' | 'object';
+export type FieldIn = 'body' | 'query' | 'header' | 'path';
+
+export interface FieldSpec {
+  in?: FieldIn;            // where the value travels (default body); drives how a negative case is built
+  required?: boolean;
+  type?: FieldType;
+  format?: string;         // email | uuid | url | date | datetime | … (OpenAPI `format`)
+  minLength?: number;
+  maxLength?: number;
+  min?: number;            // OpenAPI `minimum`
+  max?: number;            // OpenAPI `maximum`
+  pattern?: string;        // regex source
+  values?: Array<string | number | boolean>; // enum
+  unique?: boolean;
+}
+
+const NUM = (v: unknown): number | undefined => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
+const STR = (v: unknown): string | undefined => (typeof v === 'string' && v ? v : undefined);
+
+/** A `:param` snake token for a query/header name (names may carry `-`, `.`, spaces). Shared with the
+ *  importer so a field's key matches the `params`/path token it maps to (e.g. `X-Trace` → `x_trace`). */
+export function paramToken(name: string): string {
+  return name.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '').toLowerCase() || name.toLowerCase();
+}
+
+/** Normalize an OpenAPI property/parameter schema type into a FieldType (enum wins when `enum` present). */
+function fieldTypeOf(schema: any): FieldType | undefined {
+  if (schema && Array.isArray(schema.enum) && schema.enum.length) return 'enum';
+  const t = STR(schema?.type);
+  if (t === 'string' || t === 'integer' || t === 'number' || t === 'boolean' || t === 'array' || t === 'object') return t;
+  return undefined;
+}
+
+/** Map a single OpenAPI schema (a property schema or a parameter's `.schema`) → FieldSpec. */
+export function fieldFromSchema(schema: any, opts: { in?: FieldIn; required?: boolean } = {}): FieldSpec {
+  const s = schema && typeof schema === 'object' ? schema : {};
+  const spec: FieldSpec = {};
+  if (opts.in && opts.in !== 'body') spec.in = opts.in; // body is the default → omit for terseness
+  if (opts.required) spec.required = true;
+  const type = fieldTypeOf(s);
+  if (type) spec.type = type;
+  const format = STR(s.format);
+  if (format) spec.format = format;
+  const minLength = NUM(s.minLength); if (minLength != null) spec.minLength = minLength;
+  const maxLength = NUM(s.maxLength); if (maxLength != null) spec.maxLength = maxLength;
+  const min = NUM(s.minimum); if (min != null) spec.min = min;
+  const max = NUM(s.maximum); if (max != null) spec.max = max;
+  const pattern = STR(s.pattern); if (pattern) spec.pattern = pattern;
+  if (Array.isArray(s.enum) && s.enum.length) spec.values = s.enum.filter((v: unknown) => ['string', 'number', 'boolean'].includes(typeof v));
+  if (s.uniqueItems === true || s['x-unique'] === true) spec.unique = true;
+  return spec;
+}
+
+/** Empty FieldSpec (no attributes) — used to decide whether carrying it adds any signal. */
+function isEmpty(spec: FieldSpec): boolean {
+  return Object.keys(spec).length === 0 || (Object.keys(spec).length === 1 && spec.in != null);
+}
+
+/**
+ * Derive `fields:` from an OpenAPI request-body schema (its `properties` + `required[]`).
+ * `location` marks where these live (body by default). Skips fields that carry no useful metadata.
+ */
+export function fieldsFromSchema(schema: any, location: FieldIn = 'body'): Record<string, FieldSpec> {
+  const out: Record<string, FieldSpec> = {};
+  const props = schema && typeof schema === 'object' && schema.properties && typeof schema.properties === 'object' ? schema.properties : null;
+  if (!props) return out;
+  const required = new Set<string>(Array.isArray(schema.required) ? schema.required.filter((r: unknown) => typeof r === 'string') : []);
+  for (const [name, propSchema] of Object.entries(props)) {
+    const spec = fieldFromSchema(propSchema, { in: location, required: required.has(name) });
+    if (!isEmpty(spec)) out[name] = spec;
+  }
+  return out;
+}
+
+/**
+ * Derive `fields:` from an OpenAPI operation `parameters[]` (query + header; path is an identifier,
+ * carried as a param but not a validatable field). Each parameter carries `required` + a `.schema`.
+ */
+export function fieldsFromParameters(parameters: any[]): Record<string, FieldSpec> {
+  const out: Record<string, FieldSpec> = {};
+  if (!Array.isArray(parameters)) return out;
+  for (const p of parameters) {
+    if (!p || typeof p !== 'object' || typeof p.name !== 'string') continue;
+    const loc = p.in === 'query' ? 'query' : p.in === 'header' ? 'header' : null;
+    if (!loc) continue; // skip path (identifier) + cookie
+    const spec = fieldFromSchema(p.schema ?? {}, { in: loc, required: p.required === true });
+    // A required query/header param carries signal even with no constraints (missing-field case).
+    // Key by the param TOKEN (not the raw name) so it matches the `params`/path token downstream.
+    if (!isEmpty(spec) || spec.required) out[paramToken(p.name)] = spec.required ? spec : { ...spec, in: loc };
+  }
+  return out;
+}
+
+/** Merge field maps (later wins); drops nothing. */
+export function mergeFields(...maps: Array<Record<string, FieldSpec> | undefined>): Record<string, FieldSpec> | undefined {
+  const out: Record<string, FieldSpec> = {};
+  for (const m of maps) if (m) for (const [k, v] of Object.entries(m)) out[k] = v;
+  return Object.keys(out).length ? out : undefined;
+}
+
+/** Parse + validate the `fields:` block from a loaded catalog entry. Undefined when absent/empty. */
+export function parseFields(raw: any): Record<string, FieldSpec> | undefined {
+  if (!raw || typeof raw !== 'object') return undefined;
+  const out: Record<string, FieldSpec> = {};
+  for (const [name, v] of Object.entries(raw as Record<string, any>)) {
+    if (!v || typeof v !== 'object') continue;
+    const spec: FieldSpec = {};
+    if (v.in === 'query' || v.in === 'header' || v.in === 'path') spec.in = v.in;
+    if (v.required === true) spec.required = true;
+    if (typeof v.type === 'string') spec.type = v.type as FieldType;
+    if (typeof v.format === 'string') spec.format = v.format;
+    if (typeof v.minLength === 'number') spec.minLength = v.minLength;
+    if (typeof v.maxLength === 'number') spec.maxLength = v.maxLength;
+    if (typeof v.min === 'number') spec.min = v.min;
+    if (typeof v.max === 'number') spec.max = v.max;
+    if (typeof v.pattern === 'string') spec.pattern = v.pattern;
+    if (Array.isArray(v.values)) spec.values = v.values;
+    if (v.unique === true) spec.unique = true;
+    out[name] = spec;
+  }
+  return Object.keys(out).length ? out : undefined;
+}

package/src/api-file-fields.ts

@@ -0,0 +1,43 @@
+/**
+ * File-field normalization for the API catalog — the `files:` (multipart form parts) and `bodyFile:`
+ * (raw binary body) keys of an `apis.yaml` entry. Kept separate from api-catalog.ts (endpoint
+ * resolution) since file-upload declaration is a distinct concern with its own shorthand rules.
+ */
+
+/**
+ * A file to upload. `path` is a fixture location (a literal or a `:param` bound at runtime); the
+ * runtime reads it into bytes. `mimeType`/`filename` are optional overrides (else inferred from the
+ * extension / basename); `name` overrides the multipart part name (defaults to the field key —
+ * unused by `bodyFile`, which has no part name).
+ */
+export interface FileFieldSpec {
+  path: string;
+  mimeType?: string;
+  filename?: string;
+  name?: string;
+}
+
+/** Normalize a single file spec — a string value is shorthand for `{ path }`. Undefined if invalid. */
+export function parseFileSpec(v: any): FileFieldSpec | undefined {
+  if (typeof v === 'string') return { path: v };
+  if (v && typeof v === 'object' && typeof v.path === 'string') {
+    return {
+      path: v.path,
+      mimeType: typeof v.mimeType === 'string' ? v.mimeType : undefined,
+      filename: typeof v.filename === 'string' ? v.filename : undefined,
+      name: typeof v.name === 'string' ? v.name : undefined,
+    };
+  }
+  return undefined;
+}
+
+/** Normalize the `files:` block — each value via parseFileSpec. Undefined when no valid fields. */
+export function parseFiles(raw: any): Record<string, FileFieldSpec> | undefined {
+  if (!raw || typeof raw !== 'object') return undefined;
+  const out: Record<string, FileFieldSpec> = {};
+  for (const [field, v] of Object.entries(raw as Record<string, any>)) {
+    const spec = parseFileSpec(v);
+    if (spec) out[field] = spec;
+  }
+  return Object.keys(out).length ? out : undefined;
+}

package/src/api-repair.ts

@@ -23,6 +23,12 @@ export const apiRepair: RepairProvider = {
       fix: 'An `@api:<name>` does not resolve in the catalog — fix the name, or add/import the endpoint into `api/apis.yaml` (`sungen api import`).' },
     { id: 'api-manual-automatable', match: /VIEWPOINT-API-MANUAL-AUTOMATABLE/i,
       fix: 'A @manual scenario is automatable (its endpoint resolves) — drop @manual and use @api (+ @cases for error rows / @concurrent for idempotency). Reserve @manual for genuine judgment cases.' },
+    { id: 'api-required-matrix', match: /VIEWPOINT-API-REQUIRED-MATRIX/i,
+      fix: 'A `required` field (from the catalog `fields:`) has no missing-field case — add a `@cases` row that omits the field and asserts a 4xx (`expect_status: 400`).' },
+    { id: 'api-boundary', match: /VIEWPOINT-API-BOUNDARY/i,
+      fix: 'A `min/max/minLength/maxLength` field has no boundary case — add `@cases` rows at the edges (`min-1` / `min` / `max` / `max+1`), the out-of-range ones asserting a 4xx.' },
+    { id: 'api-format', match: /VIEWPOINT-API-FORMAT/i,
+      fix: 'An enum/format field has no invalid-value case — add a `@cases` row with a value outside the allowed set (`values:`) asserting a 4xx.' },
 
     // ── Runtime failures (from the Playwright test-result) ────────────────────────────────────
     { id: 'api-auth', match: /\b40[13]\b|unauthor|forbidden/i,
@@ -32,7 +38,7 @@ export const apiRepair: RepairProvider = {
     { id: 'api-status-mismatch', match: /expected.*status|status.*expected|toBe.*\b[45]\d\d\b|received.*\b[45]\d\d\b/i,
       fix: 'Asserted status ≠ actual — reconcile the expectation against `apis.yaml`/spec (the catalog is the oracle). Never hand-edit the generated spec; fix the feature/test-data and re-`generate --api`.' },
     { id: 'api-timeout', match: /timeout|timed out|exceeded/i,
-      fix: 'Request timed out — raise the datasource `timeout_ms`, or check the endpoint/path; for flows ensure prior steps bound the values the call needs.' },
+      fix: 'Request timed out — raise the timeout (`timeout_ms` on the catalog entry for just this endpoint, or on the datasource for all of them), or check the endpoint/path; for flows ensure prior steps bound the values the call needs.' },
     { id: 'api-flaky', match: /flak|intermitt|conflict|already exists|duplicate key/i,
       fix: 'Likely state bleed — make the flow self-cleaning (delete what it created / `@cleanup`), isolate `@cases` rows, and cap `@concurrent`.' },
   ],

package/src/cli-import.ts

@@ -31,6 +31,22 @@ function writeCatalog(file: string, entries: Record<string, ImportedApiEntry>, m
   fs.writeFileSync(file, CATALOG_HEADER + stringifyYaml(out));
 }
 
+const SCHEMAS_HEADER =
+  '# Response-body schema registry (API Driver) — generated by `sungen api import` from OpenAPI\n' +
+  '# `components.schemas`. Reference from a catalog entry via `schemaRef: <Name>`, then assert the\n' +
+  '# response shape with `expect {{<name>.body}} matches schema [<Name>]`.\n';
+
+function writeSchemas(file: string, schemas: Record<string, unknown>, merge: boolean): void {
+  let out = schemas;
+  if (fs.existsSync(file)) {
+    if (!merge) return; // never clobber a reviewed schemas.yaml without --merge
+    const existing = parseYaml(fs.readFileSync(file, 'utf8')) || {};
+    out = { ...existing, ...schemas };
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, SCHEMAS_HEADER + stringifyYaml(out));
+}
+
 /** Read a source path or http(s) URL (a published Google-Sheet CSV) → text. */
 async function readSource(source: string): Promise<string> {
   if (/^https?:\/\//.test(source)) {
@@ -144,10 +160,16 @@ export function registerApiCommand(program: Command): void {
       try {
         const text = await readSource(source);
         const { result, kind } = importAny(source, text, opts.datasource);
-        const { entries, count, skipped } = result;
+        const { entries, count, skipped, schemas, report } = result;
         if (count === 0) throw new Error(`No endpoints imported (${skipped.join('; ') || 'empty source'}).`);
 
         const written: string[] = [];
+        // Shared response-schema registry (feeds `expect {{name.body}} matches schema [Ref]`).
+        if (schemas && Object.keys(schemas).length) {
+          const schemaFile = path.join(process.cwd(), 'qa', 'api', 'schemas.yaml');
+          writeSchemas(schemaFile, schemas, !!opts.merge);
+          written.push(`${rel(schemaFile)} (${Object.keys(schemas).length} schema(s))`);
+        }
         if (opts.screen) {
           const f = path.join(process.cwd(), 'qa', 'screens', opts.screen, 'api', 'apis.yaml');
           writeCatalog(f, entries, !!opts.merge);
@@ -177,6 +199,14 @@ export function registerApiCommand(program: Command): void {
 
         console.log(`\n✓ Imported ${count} endpoint(s) from ${kind} source:`);
         for (const w of written) console.log(`   → ${w}`);
+        if (report) {
+          const bits: string[] = [];
+          if (report.fieldsPopulated) bits.push(`${report.fieldsPopulated} endpoint(s) with field metadata`);
+          if (report.queryParamsAdded) bits.push(`${report.queryParamsAdded} query/header param(s) recovered`);
+          if (report.authInferred) bits.push(`${report.authInferred} auth header(s) inferred`);
+          if (report.responseSchemas) bits.push(`${report.responseSchemas} response schema(s)`);
+          if (bits.length) console.log(`\n✓ Extracted: ${bits.join(', ')}.`);
+        }
         if (skipped.length) console.log(`\n⚠ Skipped: ${skipped.slice(0, 10).join('; ')}${skipped.length > 10 ? ` … (+${skipped.length - 10})` : ''}`);
         console.log('\nNext: wire the `datasource` base_url + auth in datasources.yaml, refine the scenarios,');
         console.log('then `sungen generate --api <area>` → `npx playwright test`.\n');

package/src/csv-import.ts

@@ -7,12 +7,14 @@
  * module only parses text).
  *
  * Columns (header row, case-insensitive; aliases accepted):
- *   name | area|tag | method | path | params | body | datasource|auth | expect_status | description
+ *   name | area|tag | method | path | params | body | fields | datasource|auth | expect_status | description
  *   - params: separated by `;` or `|` (commas live inside quoted JSON, so don't use `,` here)
  *   - body:   a JSON object string, values may be `:param` refs, e.g. {"item_id":":item_id"}
+ *   - fields: a JSON object of field metadata, e.g. {"email":{"required":true,"format":"email"}}
  *   - expect_status: a number (e.g. 201)
  */
 import type { ImportedApiEntry, ImportResult } from './openapi-import';
+import { parseFields } from './api-field-spec';
 
 /** RFC-4180-ish parser: handles quoted fields, embedded commas/newlines, and "" escapes. */
 export function parseCsv(text: string): string[][] {
@@ -55,7 +57,8 @@ export function importCsv(text: string, datasource = 'app_api'): ImportResult {
   const rows = parseCsv(text);
   const entries: Record<string, ImportedApiEntry> = {};
   const skipped: string[] = [];
-  if (rows.length < 2) return { entries, count: 0, skipped: ['CSV has no data rows (need a header + ≥1 row)'] };
+  const emptyReport = { queryParamsAdded: 0, authInferred: 0, fieldsPopulated: 0, responseSchemas: 0 };
+  if (rows.length < 2) return { entries, count: 0, skipped: ['CSV has no data rows (need a header + ≥1 row)'], schemas: {}, report: emptyReport };
 
   const header = rows[0].map(norm);
   const col = (r: string[], name: string): string => {
@@ -82,6 +85,11 @@ export function importCsv(text: string, datasource = 'app_api'): ImportResult {
     if (bodyCell) {
       try { body = JSON.parse(bodyCell); } catch { skipped.push(`row ${n + 1} (body is not valid JSON — kept no body)`); }
     }
+    let fields;
+    const fieldsCell = col(r, 'fields');
+    if (fieldsCell) {
+      try { fields = parseFields(JSON.parse(fieldsCell)); } catch { skipped.push(`row ${n + 1} (fields is not valid JSON — kept no fields)`); }
+    }
     const statusCell = col(r, 'expect_status');
     const status = /^\d+$/.test(statusCell) ? Number(statusCell) : undefined;
     const description = col(r, 'description') || undefined;
@@ -94,8 +102,10 @@ export function importCsv(text: string, datasource = 'app_api'): ImportResult {
       path,
       ...(params.length ? { params } : {}),
       ...(body ? { body } : {}),
+      ...(fields ? { fields } : {}),
       ...(status != null ? { expect: { status } } : {}),
     };
+    if (fields) emptyReport.fieldsPopulated++;
   }
-  return { entries, count: Object.keys(entries).length, skipped };
+  return { entries, count: Object.keys(entries).length, skipped, schemas: {}, report: emptyReport };
 }

package/src/index.ts

@@ -18,6 +18,8 @@
 // "not resolvable" install errors). Keeping core type-only makes the driver load with no core on disk.
 import type { CapabilityRegistry, Sensor, GateInput } from '@sun-asterisk/sungen';
 import { resolveApi, apiParamNames, lintApiCatalog } from './api-catalog';
+import { fieldCoverageGaps, readUnitTestData } from './api-field-coverage';
+import type { FieldSpec } from './api-field-spec';
 import { registerApiCommand } from './cli-import';
 import { apiViewpoints, apiGateProvider } from './api-harness';
 import { apiDiscovery, apiContextMapper } from './api-context';
@@ -47,8 +49,11 @@ function parseQueryOverrides(raw?: string): Record<string, string> {
 }
 
 export { importOpenApi } from './openapi-import';
-export type { ImportedApiEntry, ImportResult } from './openapi-import';
+export type { ImportedApiEntry, ImportResult, ImportReport } from './openapi-import';
 export { importCsv, parseCsv } from './csv-import';
+export type { FieldSpec, FieldType, FieldIn } from './api-field-spec';
+export { fieldCoverageGaps, readUnitTestData } from './api-field-coverage';
+export type { FieldCoverageGap } from './api-field-coverage';
 
 /**
  * API precondition codegen: `@api:<name>[(p={{v}},…)]` → run the catalog request and bind the
@@ -87,7 +92,14 @@ function apiPreconditionCodegen(input: { tags: string[]; screenName: string; cwd
     const hdr = entry.headers && Object.keys(entry.headers).length ? `, headers: ${JSON.stringify(entry.headers)}` : '';
     // request-body wire format (default json); `form` → x-www-form-urlencoded, `multipart` → form-data (#345).
     const enc = entry.encoding ? `, encoding: ${JSON.stringify(entry.encoding)}` : '';
-    const req = `{ method: ${JSON.stringify(entry.method)}, path: ${JSON.stringify(entry.path)}${entry.body !== undefined ? `, body: ${JSON.stringify(entry.body)}` : ''}${enc}${hdr}, datasource: ${ds} }`;
+    // multipart file fields; the runtime reads each fixture and builds a Playwright file payload. Its
+    // `:param` paths bind at runtime from the same params. Presence forces multipart in the runtime.
+    const files = entry.files && Object.keys(entry.files).length ? `, files: ${JSON.stringify(entry.files)}` : '';
+    // raw-binary body upload: the request body IS the fixture's bytes (e.g. application/octet-stream).
+    const bodyFile = entry.bodyFile ? `, bodyFile: ${JSON.stringify(entry.bodyFile)}` : '';
+    // per-endpoint timeout override (else the datasource timeout applies at runtime).
+    const timeout = entry.timeout_ms ? `, timeout: ${JSON.stringify(entry.timeout_ms)}` : '';
+    const req = `{ method: ${JSON.stringify(entry.method)}, path: ${JSON.stringify(entry.path)}${entry.body !== undefined ? `, body: ${JSON.stringify(entry.body)}` : ''}${enc}${files}${bodyFile}${hdr}${timeout}, datasource: ${ds} }`;
     // @concurrent:N → callN (N parallel calls, aggregate result); else a single call. @hybrid adds
     // the storageState opts so the request reuses the UI auth session.
     const callExpr = concurrent
@@ -169,6 +181,26 @@ const apiViewpointSensor: Sensor<GateInput> = {
       }
     }
 
+    // Field-driven matrix coverage (REQUIRED/BOUNDARY/FORMAT) — applies to read + mutating endpoints
+    // that declare `fields:`. Advisory; fail-quiet when a `@cases` dataset can't be resolved.
+    const testData = readUnitTestData(screenName, cwd);
+    for (const name of refs) {
+      let fields: Record<string, FieldSpec> | undefined;
+      try { fields = resolveApi(name, screenName, cwd).fields; } catch { continue; }
+      if (!fields || !Object.keys(fields).length) continue;
+      const referencing = apiScenarios.filter((s) => (s.apiRefs ?? []).includes(name));
+      const datasetNames = [...new Set(referencing.filter((s) => s.casesDataset).map((s) => s.casesDataset as string))];
+      // Per-field coverage is measured from `@cases` rows (the matrix mechanism). If the endpoint has
+      // no `@cases` but DOES assert an inline 4xx, the author is testing errors another way — mirror
+      // api-error's "either @cases or an inline 4xx" acceptance and don't raise a false matrix finding.
+      if (!datasetNames.length && referencing.some((s) => /\b4\d\d\b/.test(s.stepsText ?? ''))) continue;
+      for (const gap of fieldCoverageGaps(name, fields, datasetNames, testData)) {
+        if (gap.kind === 'required') add('warn', `VIEWPOINT-API-REQUIRED-MATRIX: @api:${name} — required field(s) ${gap.fields.join(', ')} have no missing-field case — add a @cases row omitting each, asserting 4xx.`);
+        else if (gap.kind === 'boundary') add('warn', `VIEWPOINT-API-BOUNDARY: @api:${name} — field(s) ${gap.fields.join(', ')} have a min/max/length constraint but no boundary case — add @cases rows with out-of-range values → 4xx.`);
+        else add('warn', `VIEWPOINT-API-FORMAT: @api:${name} — enum field(s) ${gap.fields.join(', ')} have no invalid-value case — add a @cases row with a value outside the allowed set → 4xx.`);
+      }
+    }
+
     // Method-aware: error + idempotency only apply when a referenced endpoint MUTATES.
     const mutating: string[] = [];
     for (const name of refs) {

package/src/openapi-import.ts

@@ -3,9 +3,13 @@
  *
  * Deterministically turns an OpenAPI/Swagger document into named-endpoint catalog entries, so QA
  * doesn't hand-author the `api/apis.yaml`. Pure transform (no network): paths × methods → entries
- * with method, `:param` path, declared params (path + JSON body props), expected status, and a
- * placeholder datasource. The Dev/lead reviews + wires the datasource; QA references by `@api:<name>`.
+ * with method, `:param` path, declared params (path + query + JSON body props), field metadata
+ * (required/type/enum/range → the `fields:` block), inferred auth headers (from securitySchemes), the
+ * expected 2xx status + its response schema, and a placeholder datasource. The Dev/lead reviews +
+ * wires the datasource; QA references by `@api:<name>`.
  */
+import { fieldsFromSchema, fieldsFromParameters, mergeFields, paramToken, type FieldSpec } from './api-field-spec';
+
 export interface ImportedApiEntry {
   datasource: string;
   area: string;            // resource/tag group (OpenAPI tag, else first path segment)
@@ -14,7 +18,13 @@ export interface ImportedApiEntry {
   path: string;
   params?: string[];
   body?: Record<string, string>;
+  files?: Record<string, { path: string; mimeType?: string; filename?: string; name?: string }>; // multipart/form-data binary props → file form fields
+  bodyFile?: { path: string; mimeType?: string; filename?: string; name?: string }; // raw-binary request body (application/octet-stream) → the body IS the file
   encoding?: 'form' | 'multipart'; // set when the requestBody is form/multipart (json omitted = default)
+  headers?: Record<string, string>; // per-endpoint header templates (inferred auth, e.g. authorization: "Bearer :token")
+  fields?: Record<string, FieldSpec>; // field metadata (required/type/enum/range) for the error+boundary matrices
+  responseSchema?: unknown; // inline 2xx response body schema (when not a $ref)
+  schemaRef?: string;       // component name of the 2xx response schema (when a $ref) → schemas registry
   expect?: { status: number };
 }
 
@@ -53,30 +63,170 @@ function expectedStatus(responses: Record<string, unknown> | undefined): number
   return success ?? codes[0];
 }
 
-/** Body property names → a `{ prop: ":prop" }` template, + the wire encoding (json | form | multipart),
- *  best-effort from the requestBody content-type (#345). JSON is the default (encoding omitted). */
-function bodyTemplate(op: any): { body?: Record<string, string>; props: string[]; encoding?: 'form' | 'multipart' } {
+/** True for a schema property that carries raw file bytes — `format: binary` (a file), or an array of them. */
+function isBinaryProp(schema: any): boolean {
+  if (!schema || typeof schema !== 'object') return false;
+  if (schema.format === 'binary') return true;
+  return schema.type === 'array' && schema.items && typeof schema.items === 'object' && schema.items.format === 'binary';
+}
+
+/** Combine pathItem-level + operation-level `parameters` (op overrides by name+in). */
+function collectParameters(pathItem: any, op: any): any[] {
+  const byKey = new Map<string, any>();
+  for (const src of [pathItem?.parameters, op?.parameters]) {
+    if (!Array.isArray(src)) continue;
+    for (const p of src) if (p && typeof p === 'object' && typeof p.name === 'string') byKey.set(`${p.in}:${p.name}`, p);
+  }
+  return [...byKey.values()];
+}
+
+/** Resolve a request-body schema to its concrete `properties`+`required` — following a top-level
+ *  `$ref` (`#/components/schemas/User`) and merging `allOf` members. Many real specs (Petstore, most
+ *  generated ones) reference the body schema rather than inlining it; without this, `properties` is
+ *  empty → no body template + no `fields:` matrix. Cycle-guarded; best-effort (unknown ref → {}). */
+function resolveBodySchema(schema: any, components: Record<string, any>, seen: Set<string> = new Set()): any {
+  if (!schema || typeof schema !== 'object') return schema;
+  const refName = refComponentName(schema.$ref);
+  if (refName) {
+    if (seen.has(refName)) return {}; // circular → stop
+    seen.add(refName);
+    return resolveBodySchema(components[refName], components, seen);
+  }
+  if (Array.isArray(schema.allOf)) {
+    const merged: any = { type: 'object', properties: { ...(schema.properties || {}) }, required: [...(Array.isArray(schema.required) ? schema.required : [])] };
+    for (const sub of schema.allOf) {
+      const r = resolveBodySchema(sub, components, seen);
+      if (r && typeof r === 'object') {
+        Object.assign(merged.properties, r.properties || {});
+        if (Array.isArray(r.required)) merged.required.push(...r.required);
+      }
+    }
+    merged.required = [...new Set(merged.required)];
+    return merged;
+  }
+  return schema;
+}
+
+/** Body property names → a `{ prop: ":prop" }` template, + the wire encoding (json | form | multipart)
+ *  and any `files` (multipart binary props), best-effort from the requestBody content-type (#345).
+ *  JSON is the default (encoding omitted). Also returns the picked request schema (for field metadata),
+ *  resolving a `$ref`/`allOf` body against the doc's component schemas. */
+function bodyTemplate(op: any, components: Record<string, any> = {}): { body?: Record<string, string>; files?: Record<string, { path: string }>; bodyFile?: { path: string; mimeType?: string }; props: string[]; encoding?: 'form' | 'multipart'; schema?: any } {
   const content = op?.requestBody?.content ?? {};
+  // A raw binary body → the request body IS the file's bytes, NOT a multipart part (multipart would
+  // be rejected 415). This is `application/octet-stream` (Petstore `uploadImage`) OR a concrete media
+  // type carrying a binary schema (e.g. `image/png`, `application/pdf`). Only when there's no
+  // structured (json/form/multipart) body to prefer.
+  const structured = content['application/json'] || content['application/x-www-form-urlencoded'] || content['multipart/form-data'];
+  if (!structured) {
+    const rawCt = Object.keys(content).find((ct) => ct === 'application/octet-stream' || content[ct]?.schema?.format === 'binary');
+    if (rawCt) {
+      // octet-stream → runtime default Content-Type; a concrete media type → carry it as the mimeType.
+      return { bodyFile: rawCt === 'application/octet-stream' ? { path: ':file' } : { path: ':file', mimeType: rawCt }, props: ['file'] };
+    }
+  }
   // Prefer JSON; else fall back to form-urlencoded / multipart (those set encoding).
   const pick = content['application/json'] ? { ct: 'application/json' as const, encoding: undefined }
     : content['application/x-www-form-urlencoded'] ? { ct: 'application/x-www-form-urlencoded' as const, encoding: 'form' as const }
       : content['multipart/form-data'] ? { ct: 'multipart/form-data' as const, encoding: 'multipart' as const }
         : undefined;
   if (!pick) return { props: [] };
-  const schema = content[pick.ct]?.schema;
-  const props = schema && typeof schema === 'object' && schema.properties && typeof schema.properties === 'object'
-    ? Object.keys(schema.properties)
-    : [];
-  if (!props.length) return { props: [], encoding: pick.encoding };
+  const schema = resolveBodySchema(content[pick.ct]?.schema, components);
+  const properties = schema && typeof schema === 'object' && schema.properties && typeof schema.properties === 'object' ? schema.properties : {};
+  const propNames = Object.keys(properties);
+  if (!propNames.length) return { props: [], encoding: pick.encoding, schema };
+  // multipart: split binary (file) props into `files`, the rest stay text `body`.
   const body: Record<string, string> = {};
-  for (const p of props) body[p] = `:${p}`;
-  return { body, props, encoding: pick.encoding };
+  const files: Record<string, { path: string }> = {};
+  for (const p of propNames) {
+    if (pick.encoding === 'multipart' && isBinaryProp(properties[p])) files[p] = { path: `:${p}` };
+    else body[p] = `:${p}`;
+  }
+  return {
+    ...(Object.keys(body).length ? { body } : {}),
+    ...(Object.keys(files).length ? { files } : {}),
+    props: propNames,
+    encoding: pick.encoding,
+    schema,
+  };
+}
+
+/**
+ * Resolve the auth requirement for an operation → a header template (+ the params it introduces).
+ * Reads the applicable `security` (op-level, else global) against `components.securitySchemes`.
+ * Supports http bearer/basic, apiKey (header/query), and oauth2 (bearer). Best-effort, additive.
+ */
+function authFor(op: any, doc: any): { headers?: Record<string, string>; headerParams?: string[]; queryParams?: Array<{ name: string; tok: string }>; queryFields?: Record<string, FieldSpec> } {
+  const schemes = doc?.components?.securitySchemes && typeof doc.components.securitySchemes === 'object' ? doc.components.securitySchemes : {};
+  const requirements: any[] = Array.isArray(op?.security) ? op.security : Array.isArray(doc?.security) ? doc.security : [];
+  const req = requirements.find((r) => r && typeof r === 'object' && Object.keys(r).length); // first non-empty requirement
+  if (!req) return {};
+  const headers: Record<string, string> = {};
+  const headerParams: string[] = [];
+  const queryParams: Array<{ name: string; tok: string }> = [];
+  const queryFields: Record<string, FieldSpec> = {};
+  for (const schemeName of Object.keys(req)) {
+    const s = schemes[schemeName];
+    if (!s || typeof s !== 'object') continue;
+    if (s.type === 'http' && String(s.scheme).toLowerCase() === 'bearer') {
+      headers['authorization'] = 'Bearer :token'; headerParams.push('token');
+    } else if (s.type === 'http' && String(s.scheme).toLowerCase() === 'basic') {
+      headers['authorization'] = 'Basic :basic_auth'; headerParams.push('basic_auth');
+    } else if (s.type === 'oauth2') {
+      headers['authorization'] = 'Bearer :token'; headerParams.push('token');
+    } else if (s.type === 'apiKey' && typeof s.name === 'string') {
+      const tok = paramToken(s.name);
+      if (s.in === 'header') { headers[s.name.toLowerCase()] = `:${tok}`; headerParams.push(tok); }
+      else if (s.in === 'query') { queryParams.push({ name: s.name, tok }); queryFields[tok] = { in: 'query', required: true }; }
+    }
+  }
+  return {
+    ...(Object.keys(headers).length ? { headers } : {}),
+    ...(headerParams.length ? { headerParams } : {}),
+    ...(queryParams.length ? { queryParams } : {}),
+    ...(Object.keys(queryFields).length ? { queryFields } : {}),
+  };
+}
+
+/** Extract the 2xx JSON response schema for an operation → inline schema or a `#/…/schemas/<name>` ref. */
+function responseSchemaFor(op: any): { responseSchema?: unknown; schemaRef?: string } {
+  const responses = op?.responses;
+  if (!responses || typeof responses !== 'object') return {};
+  const code = Object.keys(responses).filter((c) => /^\d+$/.test(c)).map(Number).find((c) => c >= 200 && c < 300);
+  if (code == null) return {};
+  const content = (responses as any)[String(code)]?.content;
+  const schema = content?.['application/json']?.schema;
+  if (!schema || typeof schema !== 'object') return {};
+  const refName = refComponentName(schema.$ref);
+  if (refName) return { schemaRef: refName };
+  // Unwrap a top-level array of a $ref (`{ type: array, items: { $ref } }`) → still ref the item.
+  if (schema.type === 'array') {
+    const itemRef = refComponentName(schema.items?.$ref);
+    if (itemRef) return { schemaRef: itemRef };
+  }
+  return { responseSchema: schema };
+}
+
+/** `#/components/schemas/User` → `User` (else undefined). */
+function refComponentName(ref: unknown): string | undefined {
+  if (typeof ref !== 'string') return undefined;
+  const m = ref.match(/#\/components\/schemas\/([A-Za-z0-9_.-]+)$/);
+  return m ? m[1] : undefined;
+}
+
+export interface ImportReport {
+  queryParamsAdded: number;   // query/header params recovered from parameters[] (were dropped before)
+  authInferred: number;       // endpoints that got an inferred auth header
+  fieldsPopulated: number;    // endpoints with a fields: block
+  responseSchemas: number;    // endpoints with a 2xx response schema / ref
 }
 
 export interface ImportResult {
   entries: Record<string, ImportedApiEntry>;
   count: number;
   skipped: string[];
+  schemas: Record<string, unknown>; // component schemas → schemas.yaml (feeds `matches schema` assertions)
+  report: ImportReport;
 }
 
 /**
@@ -87,8 +237,10 @@ export interface ImportResult {
 export function importOpenApi(doc: any, datasource = 'app_api'): ImportResult {
   const entries: Record<string, ImportedApiEntry> = {};
   const skipped: string[] = [];
+  const report: ImportReport = { queryParamsAdded: 0, authInferred: 0, fieldsPopulated: 0, responseSchemas: 0 };
+  const componentSchemas = doc?.components?.schemas && typeof doc.components.schemas === 'object' ? doc.components.schemas : {};
   const paths = doc && typeof doc === 'object' ? doc.paths : undefined;
-  if (!paths || typeof paths !== 'object') return { entries, count: 0, skipped: ['no `paths` object found'] };
+  if (!paths || typeof paths !== 'object') return { entries, count: 0, skipped: ['no `paths` object found'], schemas: {}, report };
 
   for (const [rawPath, pathItem] of Object.entries(paths as Record<string, any>)) {
     if (!pathItem || typeof pathItem !== 'object') continue;
@@ -98,8 +250,44 @@ export function importOpenApi(doc: any, datasource = 'app_api'): ImportResult {
 
       const catalogPath = toCatalogPath(rawPath);
       const pathParams = (catalogPath.match(/:([A-Za-z_][A-Za-z0-9_]*)/g) || []).map((s) => s.slice(1));
-      const { body, props, encoding } = bodyTemplate(op);
-      const params = [...new Set([...pathParams, ...props])];
+      const { body, files, bodyFile, props, encoding, schema: reqSchema } = bodyTemplate(op, componentSchemas);
+
+      // parameters[] — query params join `params` (a `?a=:a&b=:b` query string on the path); header
+      // params become header templates. Both were dropped before this. Auth (apiKey-in-query) also
+      // contributes a query key so it lands on the path (not just declared → would fail the lint).
+      const parameters = collectParameters(pathItem, op);
+      const auth = authFor(op, doc);
+      const declaredQuery = parameters.filter((p) => p.in === 'query').map((p) => ({ name: p.name, tok: paramToken(p.name) }));
+      const queryParams = [...declaredQuery, ...(auth.queryParams || [])];
+      // A header param whose name collides with an inferred auth header (e.g. an explicitly documented
+      // `Authorization`) is dropped in favour of the richer auth-scheme template — else its token would
+      // be a declared-but-unreferenced param (lint break) and the `Bearer :token` scheme would be lost.
+      const authHeaderKeys = new Set(Object.keys(auth.headers || {}));
+      const headerParamDefs = parameters.filter((p) => p.in === 'header' && typeof p.name === 'string' && !authHeaderKeys.has(String(p.name).toLowerCase()));
+
+      const paramFields = fieldsFromParameters(parameters);
+      const bodyFields = reqSchema ? fieldsFromSchema(reqSchema, 'body') : {};
+      const fields = mergeFields(bodyFields, paramFields, auth.queryFields);
+
+      // Assemble the request path: append recovered query params as `?a=:a&b=:b` (deterministic order).
+      let finalPath = catalogPath;
+      if (queryParams.length) {
+        const qs = queryParams.map((q) => `${q.name}=:${q.tok}`).join('&');
+        finalPath += (catalogPath.includes('?') ? '&' : '?') + qs;
+      }
+      report.queryParamsAdded += declaredQuery.length + headerParamDefs.length;
+
+      const headers: Record<string, string> = { ...(auth.headers || {}) };
+      for (const hp of headerParamDefs) headers[String(hp.name).toLowerCase()] = `:${paramToken(hp.name)}`;
+
+      const paramNames = [
+        ...pathParams,
+        ...queryParams.map((q) => q.tok),
+        ...headerParamDefs.map((h) => paramToken(h.name)),
+        ...props,
+        ...(auth.headerParams || []),
+      ];
+      const params = [...new Set(paramNames)];
 
       let name = typeof op.operationId === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(op.operationId)
         ? op.operationId
@@ -108,18 +296,67 @@ export function importOpenApi(doc: any, datasource = 'app_api'): ImportResult {
       if (entries[name]) { skipped.push(`${method.toUpperCase()} ${rawPath} (duplicate name "${name}")`); continue; }
 
       const status = expectedStatus(op.responses);
+      const { responseSchema, schemaRef } = responseSchemaFor(op);
+      if (Object.keys(headers).length && auth.headers) report.authInferred++;
+      if (fields) report.fieldsPopulated++;
+      if (responseSchema || schemaRef) report.responseSchemas++;
+
       entries[name] = {
         datasource,
         area: areaOf(op, rawPath),
         description: typeof op.summary === 'string' ? op.summary : undefined,
         method: method.toUpperCase(),
-        path: catalogPath,
+        path: finalPath,
         ...(params.length ? { params } : {}),
+        ...(files ? { files } : {}),
+        ...(bodyFile ? { bodyFile } : {}),
         ...(body ? { body } : {}),
         ...(encoding ? { encoding } : {}),
+        ...(Object.keys(headers).length ? { headers } : {}),
+        ...(fields ? { fields } : {}),
+        ...(responseSchema ? { responseSchema } : {}),
+        ...(schemaRef ? { schemaRef } : {}),
         ...(status != null ? { expect: { status } } : {}),
       };
     }
   }
-  return { entries, count: Object.keys(entries).length, skipped };
+
+  // Emit only the component schemas actually referenced by an entry (+ transitive $refs) so
+  // schemas.yaml stays lean and Ajv can resolve internal refs (phase: schema assertion).
+  const schemas = collectReferencedSchemas(entries, componentSchemas);
+  return { entries, count: Object.keys(entries).length, skipped, schemas, report };
+}
+
+/** Walk `schemaRef`s + their transitive `#/components/schemas/*` refs → the schemas to persist. */
+function collectReferencedSchemas(entries: Record<string, ImportedApiEntry>, componentSchemas: Record<string, any>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  const queue: string[] = [];
+  for (const e of Object.values(entries)) {
+    if (e.schemaRef) queue.push(e.schemaRef);
+    // An inline 2xx response schema (envelope/pagination/array-of-inline) may still nest component
+    // $refs — walk them so the referenced components land in schemas.yaml (Ajv can then resolve them).
+    if (e.responseSchema) for (const ref of refsInObject(e.responseSchema)) { const n = refComponentName(ref); if (n) queue.push(n); }
+  }
+  const seen = new Set<string>();
+  while (queue.length) {
+    const name = queue.shift()!;
+    if (seen.has(name)) continue;
+    seen.add(name);
+    const schema = componentSchemas[name];
+    if (schema === undefined) continue;
+    out[name] = schema;
+    // find nested refs
+    for (const ref of refsInObject(schema)) { const n = refComponentName(ref); if (n && !seen.has(n)) queue.push(n); }
+  }
+  return out;
+}
+
+/** All `$ref` string values anywhere inside an object. */
+function refsInObject(obj: any, acc: string[] = []): string[] {
+  if (!obj || typeof obj !== 'object') return acc;
+  for (const [k, v] of Object.entries(obj)) {
+    if (k === '$ref' && typeof v === 'string') acc.push(v);
+    else if (v && typeof v === 'object') refsInObject(v, acc);
+  }
+  return acc;
 }