@njeybe/nativ 2.0.0

package/dist/core/test-generator.js

@@ -0,0 +1,1690 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { isNoSqlEngine } from '../db/types.js';
+import { loadContractEngine, loadContractTables } from '../db/diff.js';
+import { buildSchemaNode, DEFAULT_TEST_BASE_URL, DEFAULT_TEST_FRAMEWORK, DEFAULT_TEST_OUTPUT_DIR, isTestFramework, TEST_FRAMEWORKS, } from './test-generator-types.js';
+/**
+ * Contract-to-test generator (nativ test gen).
+ *
+ * Contracts are compiled into framework-agnostic TestSuiteSpecs, then rendered by a
+ * TestFrameworkAdapter. Generated endpoint tests never send a well-formed request to a
+ * mutating endpoint: POST/PUT/PATCH/DELETE are only exercised with invalid or anonymous
+ * requests, so running the suite cannot write data or trigger side effects.
+ */
+/** Present in the header of every generated file; files without it are never overwritten. */
+export const GENERATED_MARKER = 'Code generated by nativ test gen';
+const GENERATED_MARKER_PATTERN = /code generated by nativ test gen/i;
+export class TestGenError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'TestGenError';
+    }
+}
+// ─── Options & contract loading ────────────────────────────────────────────
+export function resolveTestGenOptions(options) {
+    const targetDir = path.resolve(options.targetDir);
+    const framework = options.framework ?? DEFAULT_TEST_FRAMEWORK;
+    if (!isTestFramework(framework)) {
+        throw new TestGenError('INVALID_FRAMEWORK', `Unsupported framework "${framework}". Expected one of: ${TEST_FRAMEWORKS.join(', ')}`);
+    }
+    const baseUrl = (options.baseUrl ?? DEFAULT_TEST_BASE_URL).trim().replace(/\/+$/, '');
+    let parsed = null;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        parsed = null;
+    }
+    if (!parsed || (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')) {
+        throw new TestGenError('INVALID_BASE_URL', `Base URL must be an absolute http(s) URL, got "${baseUrl}"`);
+    }
+    const outputDir = path.resolve(targetDir, options.outputDir || DEFAULT_TEST_OUTPUT_DIR);
+    return { targetDir, outputDir, framework, baseUrl, dryRun: options.dryRun === true };
+}
+function readContractJson(targetDir, file) {
+    const filePath = path.join(targetDir, '.ai', file);
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch (err) {
+        throw new TestGenError('INVALID_CONTRACT', `.ai/${file} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export function loadApiContracts(targetDir) {
+    const doc = readContractJson(targetDir, 'api_contracts.json');
+    if (!doc)
+        return null;
+    if (!Array.isArray(doc.endpoints)) {
+        throw new TestGenError('INVALID_CONTRACT', '.ai/api_contracts.json must contain an "endpoints" array');
+    }
+    return doc;
+}
+/** .ai/db_schema.json with tables normalized the same way `nativ db diff --target contract` reads them. */
+export function loadDbSchemaContract(targetDir) {
+    const doc = readContractJson(targetDir, 'db_schema.json');
+    if (!doc)
+        return null;
+    if (doc.tables !== undefined && !Array.isArray(doc.tables)) {
+        throw new TestGenError('INVALID_CONTRACT', '.ai/db_schema.json "tables" must be an array');
+    }
+    const engine = loadContractEngine(targetDir);
+    return {
+        version: doc.version,
+        projectName: doc.projectName ?? '',
+        ...(engine ? { engine } : {}),
+        tables: loadContractTables(targetDir),
+    };
+}
+// ─── Schema helpers ────────────────────────────────────────────────────────
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Same semantics as the generated shapeErrors helpers: true when `value` conforms to `node`. */
+export function matchesSchema(value, node) {
+    switch (node.kind) {
+        case 'primitive':
+            switch (node.type) {
+                case 'string':
+                    return typeof value === 'string';
+                case 'number':
+                    return typeof value === 'number' && Number.isFinite(value);
+                case 'integer':
+                    return Number.isInteger(value);
+                case 'boolean':
+                    return typeof value === 'boolean';
+                case 'null':
+                    return value === null;
+                default:
+                    return true;
+            }
+        case 'enum':
+            return node.values.includes(value);
+        case 'ref':
+            return isPlainObject(value);
+        case 'array':
+            return Array.isArray(value) && value.every((item) => matchesSchema(item, node.items));
+        case 'union':
+            return node.variants.some((v) => matchesSchema(value, v));
+        case 'object':
+            if (!isPlainObject(value))
+                return false;
+            return Object.entries(node.properties).every(([key, child]) => value[key] === undefined ? child.optional === true : matchesSchema(value[key], child));
+    }
+}
+/** A plausible valid value for `node` (enums use their first value). */
+function sampleValue(node) {
+    switch (node.kind) {
+        case 'enum':
+            return node.values[0];
+        case 'primitive':
+            if (node.type === 'number' || node.type === 'integer')
+                return 1;
+            if (node.type === 'boolean')
+                return true;
+            if (node.type === 'null')
+                return null;
+            return 'sample';
+        case 'object':
+            return Object.fromEntries(Object.entries(node.properties)
+                .filter(([, child]) => !child.optional)
+                .map(([key, child]) => [key, sampleValue(child)]));
+        case 'array':
+            return [];
+        case 'union': {
+            const nonNull = node.variants.find((v) => !(v.kind === 'primitive' && v.type === 'null'));
+            return sampleValue(nonNull ?? node.variants[0]);
+        }
+        case 'ref':
+            return {};
+    }
+}
+const INVALID_CANDIDATES = [12345, '__nativ_invalid__', true, ['__nativ_invalid__']];
+/** A value `node` rejects, or undefined when it accepts anything. */
+function invalidValue(node) {
+    return INVALID_CANDIDATES.find((candidate) => !matchesSchema(candidate, node));
+}
+function toObjectNode(value) {
+    if (value === null || value === undefined)
+        return null;
+    const node = buildSchemaNode(value);
+    return node.kind === 'object' && !node.open ? node : null;
+}
+function requiredEntries(node) {
+    return node ? Object.entries(node.properties).filter(([, child]) => !child.optional) : [];
+}
+function stringifyQuery(values) {
+    return Object.fromEntries(Object.entries(values).map(([k, v]) => [k, String(v)]));
+}
+function quoteList(names) {
+    return names.map((n) => `"${n}"`).join(', ');
+}
+// ─── Endpoint suite synthesis ──────────────────────────────────────────────
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+const SAFE_METHODS = new Set(['GET']);
+const INVALID_INPUT_STATUSES = [400, 422];
+const PATH_PARAM_PATTERN = /:([A-Za-z_]\w*)|\{([A-Za-z_]\w*)\}/g;
+/** Builds a request the contract says must be rejected, or null when no input can be invalidated. */
+function buildInvalidRequest(base, queryNode, bodyNode, safe) {
+    const requiredQuery = requiredEntries(queryNode);
+    const sampleQuery = stringifyQuery(Object.fromEntries(requiredQuery.map(([k, n]) => [k, sampleValue(n)])));
+    const withQuery = Object.keys(sampleQuery).length ? { query: sampleQuery } : {};
+    if (!safe && bodyNode) {
+        if (bodyNode.kind === 'object' && !bodyNode.open) {
+            const required = requiredEntries(bodyNode).map(([k]) => k);
+            if (required.length) {
+                return {
+                    request: { ...base, ...withQuery, body: {} },
+                    reason: `missing required field${required.length > 1 ? 's' : ''} ${quoteList(required)}`,
+                };
+            }
+            for (const [key, child] of Object.entries(bodyNode.properties)) {
+                const bad = invalidValue(child);
+                if (bad !== undefined)
+                    return { request: { ...base, ...withQuery, body: { [key]: bad } }, reason: `"${key}" has the wrong type` };
+            }
+        }
+        else {
+            const bad = invalidValue(bodyNode);
+            if (bad !== undefined)
+                return { request: { ...base, ...withQuery, body: bad }, reason: 'body has the wrong type' };
+        }
+    }
+    if (requiredQuery.length) {
+        const names = requiredQuery.map(([k]) => k);
+        return { request: { ...base }, reason: `missing required query parameter${names.length > 1 ? 's' : ''} ${quoteList(names)}` };
+    }
+    const enumParam = queryNode && Object.entries(queryNode.properties).find(([, n]) => n.kind === 'enum' && n.base === 'string');
+    if (enumParam) {
+        return { request: { ...base, query: { [enumParam[0]]: '__nativ_invalid__' } }, reason: `"${enumParam[0]}" is outside its allowed values` };
+    }
+    return null;
+}
+function successStatus(endpoint) {
+    const codes = Object.keys(endpoint.responses ?? {})
+        .map(Number)
+        .filter((c) => c >= 200 && c < 300)
+        .sort((a, b) => a - b);
+    return codes[0] ?? null;
+}
+export function buildEndpointSuite(endpoint) {
+    const method = String(endpoint.method ?? '').toUpperCase();
+    if (!HTTP_METHODS.includes(method) || typeof endpoint.path !== 'string' || !endpoint.path.startsWith('/')) {
+        throw new TestGenError('INVALID_CONTRACT', `Endpoint "${endpoint.id}" needs an HTTP method and a path starting with "/"`);
+    }
+    const id = endpoint.id || `${method} ${endpoint.path}`;
+    const request = endpoint.request ?? {};
+    const pathNode = toObjectNode(request.pathParams);
+    let hasPathParams = false;
+    const filledPath = endpoint.path.replace(PATH_PARAM_PATTERN, (_m, colon, brace) => {
+        hasPathParams = true;
+        const name = colon ?? brace ?? '';
+        const node = pathNode?.properties[name];
+        return encodeURIComponent(String(node ? sampleValue(node) : 'sample'));
+    });
+    // Authorization comes from NATIV_TEST_AUTH_HEADER at run time; Content-Type is set when a body is sent.
+    const headers = Object.fromEntries(Object.entries(request.headers ?? {}).filter(([k, v]) => typeof v === 'string' && !/^(authorization|content-type)$/i.test(k)));
+    const base = { method, path: filledPath, ...(Object.keys(headers).length ? { headers } : {}) };
+    const queryNode = toObjectNode(request.queryParams);
+    const bodyNode = request.body === null || request.body === undefined ? null : buildSchemaNode(request.body);
+    const safe = SAFE_METHODS.has(method);
+    const needsInputs = requiredEntries(queryNode).length > 0 || hasPathParams;
+    const invalid = buildInvalidRequest(base, queryNode, bodyNode, safe);
+    // Well-formed requests are only sent to safe endpoints that need no caller-supplied values.
+    const sampleRequest = safe && !needsInputs ? base : null;
+    const probeRequest = sampleRequest ?? invalid?.request ?? null;
+    const cases = [];
+    if (probeRequest && !hasPathParams) {
+        cases.push({ id: `${id}:route`, name: 'route is mounted (not 404/405)', kind: 'route', request: probeRequest, assertions: [] });
+    }
+    if (endpoint.auth) {
+        // Without an invalid request, a mutating endpoint is probed bare: it must reject before acting.
+        cases.push({
+            id: `${id}:auth-required`,
+            name: 'rejects anonymous requests with 401',
+            kind: 'auth-required',
+            request: probeRequest ?? base,
+            assertions: [{ kind: 'status', expected: 401 }],
+        });
+    }
+    if (invalid) {
+        cases.push({
+            id: `${id}:invalid-payload`,
+            name: `rejects invalid input with 400/422 (${invalid.reason})`,
+            kind: 'invalid-payload',
+            request: invalid.request,
+            assertions: [{ kind: 'status', expected: INVALID_INPUT_STATUSES }],
+        });
+    }
+    const status = successStatus(endpoint);
+    if (sampleRequest && status !== null) {
+        const assertions = [{ kind: 'status', expected: status }];
+        const body = endpoint.responses[String(status)]?.body;
+        if (body !== undefined)
+            assertions.push({ kind: 'response-shape', schema: buildSchemaNode(body) });
+        cases.push({
+            id: `${id}:response-schema`,
+            name: `returns ${status} matching the contract response schema`,
+            kind: 'response-schema',
+            request: sampleRequest,
+            assertions,
+        });
+    }
+    return {
+        id,
+        name: `${method} ${endpoint.path}`,
+        suiteType: 'api-contract',
+        source: { kind: 'endpoint', endpointId: id, method, path: endpoint.path },
+        cases,
+    };
+}
+export function buildEndpointSuites(doc) {
+    return doc.endpoints.map(buildEndpointSuite).filter((suite) => suite.cases.length > 0);
+}
+// ─── Database integrity suite synthesis ────────────────────────────────────
+/** Engines without unique secondary indexes; unique-constraint checks would always fail there. */
+const NO_UNIQUE_INDEX_ENGINES = new Set(['firestore']);
+/**
+ * Integrity checks for one contract table: existence, columns, primary key, nullability and
+ * unique constraints. Collections only get required-field checks, because sampled document
+ * stores report a field as nullable whenever some sampled document lacks it.
+ */
+export function buildTableSuite(table, engine) {
+    const t = table.name;
+    const entityType = table.entityType ?? (engine && isNoSqlEngine(engine) ? 'collection' : 'table');
+    const isCollection = entityType === 'collection';
+    const fieldWord = isCollection ? 'field' : 'column';
+    const cases = [
+        { id: `db:${t}:exists`, name: `${entityType} exists`, kind: 'table-exists', assertions: [{ kind: 'table-exists', table: t }] },
+    ];
+    for (const col of table.columns) {
+        cases.push({
+            id: `db:${t}:column:${col.name}`,
+            name: `has ${fieldWord} "${col.name}" (${col.type})`,
+            kind: 'column',
+            assertions: [{ kind: 'column-exists', table: t, column: col.name, type: col.type }],
+        });
+    }
+    const pkColumns = table.columns.filter((c) => c.primaryKey).map((c) => c.name);
+    if (pkColumns.length) {
+        cases.push({
+            id: `db:${t}:primary-key`,
+            name: `primary key is (${pkColumns.join(', ')})`,
+            kind: 'primary-key',
+            assertions: [{ kind: 'primary-key', table: t, columns: pkColumns }],
+        });
+    }
+    for (const col of table.columns) {
+        if (col.primaryKey || col.isSubcollection || (isCollection && col.nullable))
+            continue;
+        cases.push({
+            id: `db:${t}:nullability:${col.name}`,
+            name: col.nullable ? `"${col.name}" is nullable` : isCollection ? `"${col.name}" is always present` : `"${col.name}" is NOT NULL`,
+            kind: 'nullability',
+            assertions: [{ kind: 'nullability', table: t, column: col.name, nullable: col.nullable }],
+        });
+    }
+    if (!engine || !NO_UNIQUE_INDEX_ENGINES.has(engine)) {
+        for (const idx of table.indexes ?? []) {
+            if (!idx.unique || !idx.columns.length)
+                continue;
+            cases.push({
+                id: `db:${t}:unique:${idx.name}`,
+                name: `unique constraint ${idx.name} on (${idx.columns.join(', ')})`,
+                kind: 'unique-constraint',
+                assertions: [{ kind: 'unique-constraint', table: t, index: idx.name, columns: idx.columns }],
+            });
+        }
+    }
+    return {
+        id: `db:${t}`,
+        name: `${entityType} ${t}`,
+        suiteType: 'db-integrity',
+        source: { kind: 'table', table: t, entityType },
+        cases,
+    };
+}
+export function buildDbSuites(doc) {
+    return doc.tables.map((table) => buildTableSuite(table, doc.engine ?? null));
+}
+// ─── Rendering helpers ─────────────────────────────────────────────────────
+function slug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'suite';
+}
+function snake(value) {
+    const s = value.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'suite';
+    return /^\d/.test(s) ? `_${s}` : s;
+}
+function pascal(value) {
+    const s = value
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join('');
+    return /^\d/.test(s) ? `X${s}` : s || 'Suite';
+}
+/** Indents every line after the first, so multi-line literals nest under the current line. */
+function hang(text, pad) {
+    return text.split('\n').join(`\n${pad}`);
+}
+function statusList(expected) {
+    return Array.isArray(expected) ? expected : [expected];
+}
+function suiteHeader(comment, suite) {
+    const source = suite.source.kind === 'endpoint'
+        ? `.ai/api_contracts.json (endpoint "${suite.source.endpointId}")`
+        : `.ai/db_schema.json (${suite.source.entityType} "${suite.source.table}")`;
+    return [`${comment} ${GENERATED_MARKER} from ${source}. DO NOT EDIT.`, `${comment} Re-run \`nativ test gen\` to refresh this file.`];
+}
+function pyLiteral(value, depth = 0) {
+    if (value === null || value === undefined)
+        return 'None';
+    if (value === true)
+        return 'True';
+    if (value === false)
+        return 'False';
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? String(value) : 'None';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    const pad = '    '.repeat(depth + 1);
+    const close = '    '.repeat(depth);
+    if (Array.isArray(value)) {
+        if (!value.length)
+            return '[]';
+        return `[\n${value.map((v) => pad + pyLiteral(v, depth + 1)).join(',\n')},\n${close}]`;
+    }
+    const entries = Object.entries(value).filter(([, v]) => v !== undefined);
+    if (!entries.length)
+        return '{}';
+    return `{\n${entries.map(([k, v]) => `${pad}${JSON.stringify(k)}: ${pyLiteral(v, depth + 1)}`).join(',\n')},\n${close}}`;
+}
+function pyTuple(values) {
+    return values.length === 1 ? `(${values[0]},)` : `(${values.join(', ')})`;
+}
+/** A JSON document as a Go (and JSON) double-quoted string literal. */
+function goJson(value) {
+    return JSON.stringify(JSON.stringify(value));
+}
+function applyBaseUrl(source, baseUrl) {
+    return source.replace('__NATIV_BASE_URL__', JSON.stringify(baseUrl));
+}
+// ─── Support file sources ──────────────────────────────────────────────────
+// Written with String.raw and without template placeholders so the sources are emitted verbatim.
+const TS_SUPPORT = String.raw `// Code generated by nativ test gen. DO NOT EDIT.
+// Shared helpers for the generated contract tests. Re-run ${'`'}nativ test gen${'`'} to refresh this file.
+// Environment: NATIV_TEST_BASE_URL overrides the base URL, NATIV_TEST_AUTH_HEADER is sent as Authorization,
+// NATIV_DB_SCHEMA_JSON reads a saved "nativ db inspect --json" file, NATIV_DB_INSPECT_CMD replaces that command.
+
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+export const BASE_URL = (process.env.NATIV_TEST_BASE_URL || __NATIV_BASE_URL__).replace(/\/+$/, '');
+
+/** A parsed contract descriptor (see src/core/test-generator-types.ts in nativ). */
+export type SchemaNode = Record<string, any>;
+
+export interface ContractRequest {
+  method: string;
+  path: string;
+  query?: Record<string, string>;
+  headers?: Record<string, string>;
+  body?: unknown;
+}
+
+export interface ContractResponse {
+  status: number;
+  body: unknown;
+}
+
+export async function callEndpoint(request: ContractRequest, options: { anonymous?: boolean } = {}): Promise<ContractResponse> {
+  const url = new URL(BASE_URL + request.path);
+  for (const [key, value] of Object.entries(request.query ?? {})) url.searchParams.set(key, value);
+  const headers: Record<string, string> = { Accept: 'application/json', ...(request.headers ?? {}) };
+  const auth = process.env.NATIV_TEST_AUTH_HEADER;
+  if (auth && !options.anonymous) headers.Authorization = auth;
+  const init: RequestInit = { method: request.method, headers };
+  if (request.body !== undefined) {
+    headers['Content-Type'] = 'application/json';
+    init.body = JSON.stringify(request.body);
+  }
+  const res = await fetch(url, init);
+  const text = await res.text();
+  let body: unknown = text;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    // Non-JSON bodies are returned as text.
+  }
+  return { status: res.status, body };
+}
+
+function describeValue(value: unknown): string {
+  if (value === null) return 'null';
+  return Array.isArray(value) ? 'array' : typeof value;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function primitiveMatches(value: unknown, type: string): boolean {
+  switch (type) {
+    case 'string': return typeof value === 'string';
+    case 'number': return typeof value === 'number' && Number.isFinite(value);
+    case 'integer': return Number.isInteger(value);
+    case 'boolean': return typeof value === 'boolean';
+    case 'null': return value === null;
+    default: return true;
+  }
+}
+
+/** Every way value deviates from the contract schema; empty when it conforms. */
+export function shapeErrors(value: unknown, node: SchemaNode, path = '$'): string[] {
+  switch (node.kind) {
+    case 'primitive':
+      return primitiveMatches(value, node.type) ? [] : [path + ': expected ' + node.type + ', got ' + describeValue(value)];
+    case 'enum':
+      return node.values.includes(value) ? [] : [path + ': expected one of ' + JSON.stringify(node.values) + ', got ' + JSON.stringify(value)];
+    case 'ref':
+      return isPlainObject(value) ? [] : [path + ': expected ' + node.name + ' object, got ' + describeValue(value)];
+    case 'array':
+      if (!Array.isArray(value)) return [path + ': expected array, got ' + describeValue(value)];
+      return value.flatMap((item, i) => shapeErrors(item, node.items, path + '[' + i + ']'));
+    case 'union':
+      return node.variants.some((v: SchemaNode) => shapeErrors(value, v, path).length === 0)
+        ? []
+        : [path + ': ' + JSON.stringify(value) + ' matches none of the allowed types'];
+    case 'object': {
+      if (!isPlainObject(value)) return [path + ': expected object, got ' + describeValue(value)];
+      const errors: string[] = [];
+      for (const [key, child] of Object.entries(node.properties as Record<string, SchemaNode>)) {
+        if (value[key] === undefined) {
+          if (!child.optional) errors.push(path + '.' + key + ': missing required field');
+          continue;
+        }
+        errors.push(...shapeErrors(value[key], child, path + '.' + key));
+      }
+      return errors;
+    }
+    default:
+      return [];
+  }
+}
+
+// ─── Live database schema (structure only, read through nativ; never rows or credentials) ───
+
+export interface LiveColumn {
+  name: string;
+  primaryKey?: boolean;
+  nullable?: boolean;
+}
+
+export interface LiveIndex {
+  name: string;
+  columns: string[];
+  unique: boolean;
+}
+
+export interface LiveTable {
+  name: string;
+  columns: LiveColumn[];
+  indexes?: LiveIndex[];
+}
+
+export interface LiveSchema {
+  connected: boolean;
+  error: string | null;
+  tables: LiveTable[];
+}
+
+/** A generated database assertion: { kind, table, column?, columns?, nullable? }. */
+export type DbAssertion = Record<string, any>;
+
+let liveSchemaCache: LiveSchema | undefined;
+
+function readInspectOutput(): string {
+  const file = process.env.NATIV_DB_SCHEMA_JSON;
+  if (file) return readFileSync(file, 'utf8');
+  const command = process.env.NATIV_DB_INSPECT_CMD || 'nativ db inspect --json';
+  try {
+    return execSync(command, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 120000 });
+  } catch (err: any) {
+    // nativ exits 1 when the database is unreachable but still prints the JSON status.
+    return String(err?.stdout ?? '');
+  }
+}
+
+export function loadLiveSchema(): LiveSchema {
+  if (liveSchemaCache) return liveSchemaCache;
+  let parsed: any = null;
+  try {
+    const raw = readInspectOutput();
+    parsed = JSON.parse(raw.slice(raw.indexOf('{'), raw.lastIndexOf('}') + 1));
+  } catch {
+    parsed = null;
+  }
+  liveSchemaCache = parsed
+    ? { connected: parsed.status?.connected === true, error: parsed.status?.error ?? null, tables: Array.isArray(parsed.tables) ? parsed.tables : [] }
+    : { connected: false, error: 'could not read "nativ db inspect --json" output (set NATIV_DB_SCHEMA_JSON or NATIV_DB_INSPECT_CMD)', tables: [] };
+  return liveSchemaCache;
+}
+
+function sameNames(a: string[], b: string[]): boolean {
+  const x = a.map((n) => n.toLowerCase()).sort();
+  const y = b.map((n) => n.toLowerCase()).sort();
+  return x.length === y.length && x.every((n, i) => n === y[i]);
+}
+
+/** Checks one generated assertion against the live schema; returns a failure message or null. */
+export function dbCheck(live: LiveSchema, a: DbAssertion): string | null {
+  const name = String(a.table);
+  const table = live.tables.find((t) => t.name.toLowerCase() === name.toLowerCase());
+  if (!table) return '"' + name + '" not found in the live database';
+  const qualified = name + '.' + a.column;
+  const column = a.column === undefined ? undefined : table.columns.find((c) => c.name.toLowerCase() === String(a.column).toLowerCase());
+  const pk = table.columns.filter((c) => c.primaryKey).map((c) => c.name);
+  switch (a.kind) {
+    case 'table-exists':
+      return null;
+    case 'column-exists':
+      return column ? null : '"' + qualified + '" not found in the live database';
+    case 'primary-key':
+      return sameNames(pk, a.columns) ? null : 'primary key of "' + name + '" is (' + pk.join(', ') + '), contract says (' + a.columns.join(', ') + ')';
+    case 'nullability':
+      if (!column) return '"' + qualified + '" not found in the live database';
+      return Boolean(column.nullable) === a.nullable
+        ? null
+        : '"' + qualified + '" is ' + (column.nullable ? 'nullable' : 'NOT NULL') + ' in the live database, contract says ' + (a.nullable ? 'nullable' : 'NOT NULL');
+    case 'unique-constraint': {
+      const found = sameNames(pk, a.columns) || (table.indexes ?? []).some((i) => i.unique && sameNames(i.columns, a.columns));
+      return found ? null : 'no unique index on "' + name + '" (' + a.columns.join(', ') + ')';
+    }
+    default:
+      return 'unknown assertion kind "' + a.kind + '"';
+  }
+}
+`;
+const JS_SUPPORT = String.raw `// Code generated by nativ test gen. DO NOT EDIT.
+// Shared helpers for the generated contract tests. Re-run ${'`'}nativ test gen${'`'} to refresh this file.
+// Environment: NATIV_TEST_BASE_URL overrides the base URL, NATIV_TEST_AUTH_HEADER is sent as Authorization,
+// NATIV_DB_SCHEMA_JSON reads a saved "nativ db inspect --json" file, NATIV_DB_INSPECT_CMD replaces that command.
+
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+export const BASE_URL = (process.env.NATIV_TEST_BASE_URL || __NATIV_BASE_URL__).replace(/\/+$/, '');
+
+export async function callEndpoint(request, options = {}) {
+  const url = new URL(BASE_URL + request.path);
+  for (const [key, value] of Object.entries(request.query ?? {})) url.searchParams.set(key, value);
+  const headers = { Accept: 'application/json', ...(request.headers ?? {}) };
+  const auth = process.env.NATIV_TEST_AUTH_HEADER;
+  if (auth && !options.anonymous) headers.Authorization = auth;
+  const init = { method: request.method, headers };
+  if (request.body !== undefined) {
+    headers['Content-Type'] = 'application/json';
+    init.body = JSON.stringify(request.body);
+  }
+  const res = await fetch(url, init);
+  const text = await res.text();
+  let body = text;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    // Non-JSON bodies are returned as text.
+  }
+  return { status: res.status, body };
+}
+
+function describeValue(value) {
+  if (value === null) return 'null';
+  return Array.isArray(value) ? 'array' : typeof value;
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function primitiveMatches(value, type) {
+  switch (type) {
+    case 'string': return typeof value === 'string';
+    case 'number': return typeof value === 'number' && Number.isFinite(value);
+    case 'integer': return Number.isInteger(value);
+    case 'boolean': return typeof value === 'boolean';
+    case 'null': return value === null;
+    default: return true;
+  }
+}
+
+/** Every way value deviates from the contract schema; empty when it conforms. */
+export function shapeErrors(value, node, path = '$') {
+  switch (node.kind) {
+    case 'primitive':
+      return primitiveMatches(value, node.type) ? [] : [path + ': expected ' + node.type + ', got ' + describeValue(value)];
+    case 'enum':
+      return node.values.includes(value) ? [] : [path + ': expected one of ' + JSON.stringify(node.values) + ', got ' + JSON.stringify(value)];
+    case 'ref':
+      return isPlainObject(value) ? [] : [path + ': expected ' + node.name + ' object, got ' + describeValue(value)];
+    case 'array':
+      if (!Array.isArray(value)) return [path + ': expected array, got ' + describeValue(value)];
+      return value.flatMap((item, i) => shapeErrors(item, node.items, path + '[' + i + ']'));
+    case 'union':
+      return node.variants.some((v) => shapeErrors(value, v, path).length === 0)
+        ? []
+        : [path + ': ' + JSON.stringify(value) + ' matches none of the allowed types'];
+    case 'object': {
+      if (!isPlainObject(value)) return [path + ': expected object, got ' + describeValue(value)];
+      const errors = [];
+      for (const [key, child] of Object.entries(node.properties)) {
+        if (value[key] === undefined) {
+          if (!child.optional) errors.push(path + '.' + key + ': missing required field');
+          continue;
+        }
+        errors.push(...shapeErrors(value[key], child, path + '.' + key));
+      }
+      return errors;
+    }
+    default:
+      return [];
+  }
+}
+
+// ─── Live database schema (structure only, read through nativ; never rows or credentials) ───
+
+let liveSchemaCache;
+
+function readInspectOutput() {
+  const file = process.env.NATIV_DB_SCHEMA_JSON;
+  if (file) return readFileSync(file, 'utf8');
+  const command = process.env.NATIV_DB_INSPECT_CMD || 'nativ db inspect --json';
+  try {
+    return execSync(command, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 120000 });
+  } catch (err) {
+    // nativ exits 1 when the database is unreachable but still prints the JSON status.
+    return String(err?.stdout ?? '');
+  }
+}
+
+export function loadLiveSchema() {
+  if (liveSchemaCache) return liveSchemaCache;
+  let parsed = null;
+  try {
+    const raw = readInspectOutput();
+    parsed = JSON.parse(raw.slice(raw.indexOf('{'), raw.lastIndexOf('}') + 1));
+  } catch {
+    parsed = null;
+  }
+  liveSchemaCache = parsed
+    ? { connected: parsed.status?.connected === true, error: parsed.status?.error ?? null, tables: Array.isArray(parsed.tables) ? parsed.tables : [] }
+    : { connected: false, error: 'could not read "nativ db inspect --json" output (set NATIV_DB_SCHEMA_JSON or NATIV_DB_INSPECT_CMD)', tables: [] };
+  return liveSchemaCache;
+}
+
+function sameNames(a, b) {
+  const x = a.map((n) => n.toLowerCase()).sort();
+  const y = b.map((n) => n.toLowerCase()).sort();
+  return x.length === y.length && x.every((n, i) => n === y[i]);
+}
+
+/** Checks one generated assertion against the live schema; returns a failure message or null. */
+export function dbCheck(live, a) {
+  const name = String(a.table);
+  const table = live.tables.find((t) => t.name.toLowerCase() === name.toLowerCase());
+  if (!table) return '"' + name + '" not found in the live database';
+  const qualified = name + '.' + a.column;
+  const column = a.column === undefined ? undefined : table.columns.find((c) => c.name.toLowerCase() === String(a.column).toLowerCase());
+  const pk = table.columns.filter((c) => c.primaryKey).map((c) => c.name);
+  switch (a.kind) {
+    case 'table-exists':
+      return null;
+    case 'column-exists':
+      return column ? null : '"' + qualified + '" not found in the live database';
+    case 'primary-key':
+      return sameNames(pk, a.columns) ? null : 'primary key of "' + name + '" is (' + pk.join(', ') + '), contract says (' + a.columns.join(', ') + ')';
+    case 'nullability':
+      if (!column) return '"' + qualified + '" not found in the live database';
+      return Boolean(column.nullable) === a.nullable
+        ? null
+        : '"' + qualified + '" is ' + (column.nullable ? 'nullable' : 'NOT NULL') + ' in the live database, contract says ' + (a.nullable ? 'nullable' : 'NOT NULL');
+    case 'unique-constraint': {
+      const found = sameNames(pk, a.columns) || (table.indexes ?? []).some((i) => i.unique && sameNames(i.columns, a.columns));
+      return found ? null : 'no unique index on "' + name + '" (' + a.columns.join(', ') + ')';
+    }
+    default:
+      return 'unknown assertion kind "' + a.kind + '"';
+  }
+}
+`;
+const PY_SUPPORT = String.raw `# Code generated by nativ test gen. DO NOT EDIT.
+# Shared helpers for the generated contract tests. Re-run "nativ test gen" to refresh this file.
+# Environment: NATIV_TEST_BASE_URL overrides the base URL, NATIV_TEST_AUTH_HEADER is sent as Authorization,
+# NATIV_DB_SCHEMA_JSON reads a saved "nativ db inspect --json" file, NATIV_DB_INSPECT_CMD replaces that command.
+import json
+import os
+import subprocess
+import urllib.error
+import urllib.parse
+import urllib.request
+
+BASE_URL = (os.environ.get("NATIV_TEST_BASE_URL") or __NATIV_BASE_URL__).rstrip("/")
+
+
+def call_endpoint(request, anonymous=False):
+    """Sends a contract request and returns (status, parsed_body)."""
+    url = BASE_URL + request["path"]
+    query = request.get("query") or {}
+    if query:
+        url += "?" + urllib.parse.urlencode(query)
+    headers = {"Accept": "application/json"}
+    headers.update(request.get("headers") or {})
+    auth = os.environ.get("NATIV_TEST_AUTH_HEADER")
+    if auth and not anonymous:
+        headers["Authorization"] = auth
+    data = None
+    if "body" in request:
+        data = json.dumps(request["body"]).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+    req = urllib.request.Request(url, data=data, headers=headers, method=request["method"])
+    try:
+        with urllib.request.urlopen(req, timeout=30) as res:
+            status, raw = res.status, res.read()
+    except urllib.error.HTTPError as err:
+        status, raw = err.code, err.read()
+    text = raw.decode("utf-8", "replace")
+    try:
+        body = json.loads(text) if text else None
+    except ValueError:
+        body = text
+    return status, body
+
+
+def _describe(value):
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, (int, float)):
+        return "number"
+    if isinstance(value, str):
+        return "string"
+    if isinstance(value, list):
+        return "array"
+    if isinstance(value, dict):
+        return "object"
+    return type(value).__name__
+
+
+def _primitive_matches(value, kind):
+    if kind == "string":
+        return isinstance(value, str)
+    if kind == "number":
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    if kind == "integer":
+        if isinstance(value, bool):
+            return False
+        return isinstance(value, int) or (isinstance(value, float) and value.is_integer())
+    if kind == "boolean":
+        return isinstance(value, bool)
+    if kind == "null":
+        return value is None
+    return True
+
+
+def shape_errors(value, node, path="$"):
+    """Every way value deviates from the contract schema; empty when it conforms."""
+    kind = node.get("kind")
+    if kind == "primitive":
+        if _primitive_matches(value, node["type"]):
+            return []
+        return ["%s: expected %s, got %s" % (path, node["type"], _describe(value))]
+    if kind == "enum":
+        if any(v == value and isinstance(v, bool) == isinstance(value, bool) for v in node["values"]):
+            return []
+        return ["%s: expected one of %s, got %r" % (path, node["values"], value)]
+    if kind == "ref":
+        return [] if isinstance(value, dict) else ["%s: expected %s object, got %s" % (path, node["name"], _describe(value))]
+    if kind == "array":
+        if not isinstance(value, list):
+            return ["%s: expected array, got %s" % (path, _describe(value))]
+        errors = []
+        for i, item in enumerate(value):
+            errors.extend(shape_errors(item, node["items"], "%s[%d]" % (path, i)))
+        return errors
+    if kind == "union":
+        if any(not shape_errors(value, v, path) for v in node["variants"]):
+            return []
+        return ["%s: %r matches none of the allowed types" % (path, value)]
+    if kind == "object":
+        if not isinstance(value, dict):
+            return ["%s: expected object, got %s" % (path, _describe(value))]
+        errors = []
+        for key, child in node.get("properties", {}).items():
+            if key not in value:
+                if not child.get("optional"):
+                    errors.append("%s.%s: missing required field" % (path, key))
+                continue
+            errors.extend(shape_errors(value[key], child, "%s.%s" % (path, key)))
+        return errors
+    return []
+
+
+# --- Live database schema (structure only, read through nativ; never rows or credentials) ---
+
+_LIVE_SCHEMA = None
+
+
+def _read_inspect_output():
+    path = os.environ.get("NATIV_DB_SCHEMA_JSON")
+    if path:
+        with open(path, encoding="utf-8") as handle:
+            return handle.read()
+    command = os.environ.get("NATIV_DB_INSPECT_CMD") or "nativ db inspect --json"
+    # nativ exits 1 when the database is unreachable but still prints the JSON status.
+    result = subprocess.run(command, shell=True, capture_output=True, encoding="utf-8", errors="replace", timeout=120)
+    return result.stdout or ""
+
+
+def load_live_schema():
+    """The live schema as {connected, error, tables}; cached for the test session."""
+    global _LIVE_SCHEMA
+    if _LIVE_SCHEMA is not None:
+        return _LIVE_SCHEMA
+    try:
+        raw = _read_inspect_output()
+        parsed = json.loads(raw[raw.index("{"):raw.rindex("}") + 1])
+    except (OSError, ValueError, subprocess.SubprocessError):
+        parsed = None
+    if isinstance(parsed, dict):
+        status = parsed.get("status") or {}
+        tables = parsed.get("tables")
+        _LIVE_SCHEMA = {
+            "connected": status.get("connected") is True,
+            "error": status.get("error"),
+            "tables": tables if isinstance(tables, list) else [],
+        }
+    else:
+        _LIVE_SCHEMA = {
+            "connected": False,
+            "error": 'could not read "nativ db inspect --json" output (set NATIV_DB_SCHEMA_JSON or NATIV_DB_INSPECT_CMD)',
+            "tables": [],
+        }
+    return _LIVE_SCHEMA
+
+
+def _same_names(a, b):
+    return sorted(str(n).lower() for n in a) == sorted(str(n).lower() for n in b)
+
+
+def _find_by_name(items, name):
+    wanted = str(name).lower()
+    return next((item for item in items or [] if str(item.get("name", "")).lower() == wanted), None)
+
+
+def _nullability(nullable):
+    return "nullable" if nullable else "NOT NULL"
+
+
+def db_check(live, assertion):
+    """Checks one generated assertion against the live schema; returns a failure message or None."""
+    name = assertion["table"]
+    table = _find_by_name(live["tables"], name)
+    if table is None:
+        return '"%s" not found in the live database' % name
+    columns = table.get("columns") or []
+    column = _find_by_name(columns, assertion["column"]) if "column" in assertion else None
+    qualified = "%s.%s" % (name, assertion.get("column"))
+    pk = [c.get("name", "") for c in columns if c.get("primaryKey")]
+    kind = assertion["kind"]
+    if kind == "table-exists":
+        return None
+    if kind == "column-exists":
+        return None if column else '"%s" not found in the live database' % qualified
+    if kind == "primary-key":
+        if _same_names(pk, assertion["columns"]):
+            return None
+        return 'primary key of "%s" is (%s), contract says (%s)' % (name, ", ".join(pk), ", ".join(assertion["columns"]))
+    if kind == "nullability":
+        if column is None:
+            return '"%s" not found in the live database' % qualified
+        actual = bool(column.get("nullable"))
+        if actual == assertion["nullable"]:
+            return None
+        return '"%s" is %s in the live database, contract says %s' % (qualified, _nullability(actual), _nullability(assertion["nullable"]))
+    if kind == "unique-constraint":
+        indexes = table.get("indexes") or []
+        if _same_names(pk, assertion["columns"]) or any(
+            i.get("unique") and _same_names(i.get("columns") or [], assertion["columns"]) for i in indexes
+        ):
+            return None
+        return 'no unique index on "%s" (%s)' % (name, ", ".join(assertion["columns"]))
+    return 'unknown assertion kind "%s"' % kind
+`;
+const GO_SUPPORT = String.raw `// Code generated by nativ test gen. DO NOT EDIT.
+// Shared helpers for the generated contract tests. Re-run "nativ test gen" to refresh this file.
+// Environment: NATIV_TEST_BASE_URL overrides the base URL, NATIV_TEST_AUTH_HEADER is sent as Authorization,
+// NATIV_DB_SCHEMA_JSON reads a saved "nativ db inspect --json" file, NATIV_DB_INSPECT_CMD replaces that command.
+
+package contract
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"math"
+	"net/http"
+	"net/url"
+	"os"
+	"os/exec"
+	"runtime"
+	"sort"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+var baseURL = strings.TrimRight(envOr("NATIV_TEST_BASE_URL", __NATIV_BASE_URL__), "/")
+
+func envOr(key, fallback string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return fallback
+}
+
+type contractResponse struct {
+	Status int
+	Body   any
+}
+
+// callEndpoint sends a request described as JSON: {method, path, query?, headers?, body?}.
+func callEndpoint(t *testing.T, requestJSON string, anonymous bool) contractResponse {
+	t.Helper()
+	var spec struct {
+		Method  string            ` + '`json:"method"`' + String.raw `
+		Path    string            ` + '`json:"path"`' + String.raw `
+		Query   map[string]string ` + '`json:"query"`' + String.raw `
+		Headers map[string]string ` + '`json:"headers"`' + String.raw `
+		Body    json.RawMessage   ` + '`json:"body"`' + String.raw `
+	}
+	if err := json.Unmarshal([]byte(requestJSON), &spec); err != nil {
+		t.Fatalf("invalid generated request: %v", err)
+	}
+	target, err := url.Parse(baseURL + spec.Path)
+	if err != nil {
+		t.Fatalf("invalid request URL: %v", err)
+	}
+	q := target.Query()
+	for k, v := range spec.Query {
+		q.Set(k, v)
+	}
+	target.RawQuery = q.Encode()
+	var body io.Reader
+	if len(spec.Body) > 0 {
+		body = bytes.NewReader(spec.Body)
+	}
+	req, err := http.NewRequest(spec.Method, target.String(), body)
+	if err != nil {
+		t.Fatalf("cannot build request: %v", err)
+	}
+	req.Header.Set("Accept", "application/json")
+	for k, v := range spec.Headers {
+		req.Header.Set(k, v)
+	}
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	if auth := os.Getenv("NATIV_TEST_AUTH_HEADER"); auth != "" && !anonymous {
+		req.Header.Set("Authorization", auth)
+	}
+	client := &http.Client{Timeout: 30 * time.Second}
+	res, err := client.Do(req)
+	if err != nil {
+		t.Fatalf("%s %s failed: %v", spec.Method, target.String(), err)
+	}
+	defer res.Body.Close()
+	raw, _ := io.ReadAll(res.Body)
+	var parsed any
+	if len(raw) > 0 {
+		if json.Unmarshal(raw, &parsed) != nil {
+			parsed = string(raw)
+		}
+	}
+	return contractResponse{Status: res.StatusCode, Body: parsed}
+}
+
+func expectRouteMounted(t *testing.T, res contractResponse) {
+	t.Helper()
+	if res.Status == 404 || res.Status == 405 {
+		t.Fatalf("route not mounted: HTTP %d", res.Status)
+	}
+}
+
+func expectStatus(t *testing.T, res contractResponse, codes ...int) {
+	t.Helper()
+	for _, c := range codes {
+		if res.Status == c {
+			return
+		}
+	}
+	t.Fatalf("expected HTTP status in %v, got %d (body: %v)", codes, res.Status, res.Body)
+}
+
+func expectShape(t *testing.T, res contractResponse, schemaJSON string) {
+	t.Helper()
+	var node map[string]any
+	if err := json.Unmarshal([]byte(schemaJSON), &node); err != nil {
+		t.Fatalf("invalid generated schema: %v", err)
+	}
+	if errs := shapeErrors(res.Body, node, "$"); len(errs) > 0 {
+		t.Fatalf("response does not match the contract:\n  %s", strings.Join(errs, "\n  "))
+	}
+}
+
+func describeValue(value any) string {
+	switch value.(type) {
+	case nil:
+		return "null"
+	case string:
+		return "string"
+	case float64:
+		return "number"
+	case bool:
+		return "boolean"
+	case []any:
+		return "array"
+	case map[string]any:
+		return "object"
+	}
+	return fmt.Sprintf("%T", value)
+}
+
+func primitiveMatches(value any, kind string) bool {
+	switch kind {
+	case "string":
+		_, ok := value.(string)
+		return ok
+	case "number":
+		_, ok := value.(float64)
+		return ok
+	case "integer":
+		f, ok := value.(float64)
+		return ok && f == math.Trunc(f)
+	case "boolean":
+		_, ok := value.(bool)
+		return ok
+	case "null":
+		return value == nil
+	}
+	return true
+}
+
+func enumMatches(value any, values []any) bool {
+	for _, v := range values {
+		switch value.(type) {
+		case string, float64, bool:
+			if v == value {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+// shapeErrors lists every way value deviates from the contract schema; empty when it conforms.
+func shapeErrors(value any, node map[string]any, path string) []string {
+	switch node["kind"] {
+	case "primitive":
+		kind, _ := node["type"].(string)
+		if primitiveMatches(value, kind) {
+			return nil
+		}
+		return []string{fmt.Sprintf("%s: expected %s, got %s", path, kind, describeValue(value))}
+	case "enum":
+		values, _ := node["values"].([]any)
+		if enumMatches(value, values) {
+			return nil
+		}
+		return []string{fmt.Sprintf("%s: expected one of %v, got %v", path, values, value)}
+	case "ref":
+		if _, ok := value.(map[string]any); ok {
+			return nil
+		}
+		return []string{fmt.Sprintf("%s: expected %v object, got %s", path, node["name"], describeValue(value))}
+	case "array":
+		items, ok := value.([]any)
+		if !ok {
+			return []string{fmt.Sprintf("%s: expected array, got %s", path, describeValue(value))}
+		}
+		child, _ := node["items"].(map[string]any)
+		var errs []string
+		for i, item := range items {
+			errs = append(errs, shapeErrors(item, child, fmt.Sprintf("%s[%d]", path, i))...)
+		}
+		return errs
+	case "union":
+		variants, _ := node["variants"].([]any)
+		for _, v := range variants {
+			if m, ok := v.(map[string]any); ok && len(shapeErrors(value, m, path)) == 0 {
+				return nil
+			}
+		}
+		return []string{fmt.Sprintf("%s: %v matches none of the allowed types", path, value)}
+	case "object":
+		obj, ok := value.(map[string]any)
+		if !ok {
+			return []string{fmt.Sprintf("%s: expected object, got %s", path, describeValue(value))}
+		}
+		props, _ := node["properties"].(map[string]any)
+		keys := make([]string, 0, len(props))
+		for k := range props {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+		var errs []string
+		for _, key := range keys {
+			child, _ := props[key].(map[string]any)
+			v, present := obj[key]
+			if !present {
+				if optional, _ := child["optional"].(bool); !optional {
+					errs = append(errs, fmt.Sprintf("%s.%s: missing required field", path, key))
+				}
+				continue
+			}
+			errs = append(errs, shapeErrors(v, child, path+"."+key)...)
+		}
+		return errs
+	}
+	return nil
+}
+
+// ─── Live database schema (structure only, read through nativ; never rows or credentials) ───
+
+var (
+	liveOnce   sync.Once
+	liveSchema map[string]any
+	liveError  string
+)
+
+func readInspectOutput() []byte {
+	if file := os.Getenv("NATIV_DB_SCHEMA_JSON"); file != "" {
+		raw, _ := os.ReadFile(file)
+		return raw
+	}
+	command := envOr("NATIV_DB_INSPECT_CMD", "nativ db inspect --json")
+	var cmd *exec.Cmd
+	if runtime.GOOS == "windows" {
+		cmd = exec.Command("cmd", "/C", command)
+	} else {
+		cmd = exec.Command("sh", "-c", command)
+	}
+	// nativ exits 1 when the database is unreachable but still prints the JSON status.
+	raw, _ := cmd.Output()
+	return raw
+}
+
+// requireLiveSchema returns the live schema, skipping the test when the database is unreachable.
+func requireLiveSchema(t *testing.T) map[string]any {
+	t.Helper()
+	liveOnce.Do(func() {
+		raw := readInspectOutput()
+		start, end := bytes.IndexByte(raw, '{'), bytes.LastIndexByte(raw, '}')
+		var parsed map[string]any
+		if start < 0 || end < start || json.Unmarshal(raw[start:end+1], &parsed) != nil {
+			liveError = "could not read \"nativ db inspect --json\" output (set NATIV_DB_SCHEMA_JSON or NATIV_DB_INSPECT_CMD)"
+			return
+		}
+		status, _ := parsed["status"].(map[string]any)
+		if connected, _ := status["connected"].(bool); !connected {
+			liveError = fmt.Sprintf("live database unavailable: %v", status["error"])
+			return
+		}
+		liveSchema = parsed
+	})
+	if liveSchema == nil {
+		t.Skip(liveError)
+	}
+	return liveSchema
+}
+
+func stringsOf(value any) []string {
+	items, _ := value.([]any)
+	out := make([]string, 0, len(items))
+	for _, v := range items {
+		if s, ok := v.(string); ok {
+			out = append(out, s)
+		}
+	}
+	return out
+}
+
+func lowerSorted(values []string) []string {
+	out := make([]string, len(values))
+	for i, v := range values {
+		out[i] = strings.ToLower(v)
+	}
+	sort.Strings(out)
+	return out
+}
+
+func sameNames(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	x, y := lowerSorted(a), lowerSorted(b)
+	for i := range x {
+		if x[i] != y[i] {
+			return false
+		}
+	}
+	return true
+}
+
+func findByName(items any, name string) map[string]any {
+	list, _ := items.([]any)
+	for _, item := range list {
+		m, ok := item.(map[string]any)
+		if !ok {
+			continue
+		}
+		if n, _ := m["name"].(string); strings.EqualFold(n, name) {
+			return m
+		}
+	}
+	return nil
+}
+
+func nullability(nullable bool) string {
+	if nullable {
+		return "nullable"
+	}
+	return "NOT NULL"
+}
+
+// expectDB checks one generated assertion (JSON) against the live schema.
+func expectDB(t *testing.T, live map[string]any, assertionJSON string) {
+	t.Helper()
+	var a map[string]any
+	if err := json.Unmarshal([]byte(assertionJSON), &a); err != nil {
+		t.Fatalf("invalid generated assertion: %v", err)
+	}
+	if msg := dbCheck(live, a); msg != "" {
+		t.Fatal(msg)
+	}
+}
+
+// dbCheck returns a failure message, or "" when the live schema satisfies the assertion.
+func dbCheck(live map[string]any, a map[string]any) string {
+	name, _ := a["table"].(string)
+	table := findByName(live["tables"], name)
+	if table == nil {
+		return fmt.Sprintf("%q not found in the live database", name)
+	}
+	columnName, hasColumn := a["column"].(string)
+	var column map[string]any
+	if hasColumn {
+		column = findByName(table["columns"], columnName)
+	}
+	qualified := name + "." + columnName
+	var pk []string
+	cols, _ := table["columns"].([]any)
+	for _, c := range cols {
+		if m, ok := c.(map[string]any); ok {
+			if isPK, _ := m["primaryKey"].(bool); isPK {
+				n, _ := m["name"].(string)
+				pk = append(pk, n)
+			}
+		}
+	}
+	expected := stringsOf(a["columns"])
+	switch a["kind"] {
+	case "table-exists":
+		return ""
+	case "column-exists":
+		if column != nil {
+			return ""
+		}
+		return fmt.Sprintf("%q not found in the live database", qualified)
+	case "primary-key":
+		if sameNames(pk, expected) {
+			return ""
+		}
+		return fmt.Sprintf("primary key of %q is (%s), contract says (%s)", name, strings.Join(pk, ", "), strings.Join(expected, ", "))
+	case "nullability":
+		if column == nil {
+			return fmt.Sprintf("%q not found in the live database", qualified)
+		}
+		actual, _ := column["nullable"].(bool)
+		want, _ := a["nullable"].(bool)
+		if actual == want {
+			return ""
+		}
+		return fmt.Sprintf("%q is %s in the live database, contract says %s", qualified, nullability(actual), nullability(want))
+	case "unique-constraint":
+		if sameNames(pk, expected) {
+			return ""
+		}
+		indexes, _ := table["indexes"].([]any)
+		for _, i := range indexes {
+			m, _ := i.(map[string]any)
+			if unique, _ := m["unique"].(bool); unique && sameNames(stringsOf(m["columns"]), expected) {
+				return ""
+			}
+		}
+		return fmt.Sprintf("no unique index on %q (%s)", name, strings.Join(expected, ", "))
+	}
+	return fmt.Sprintf("unknown assertion kind %v", a["kind"])
+}
+`;
+const JEST_LIKE = {
+    expectRouteMounted: 'expect([404, 405]).not.toContain(res.status);',
+    expectStatus: (codes) => codes.length === 1 ? `expect(res.status).toBe(${codes[0]});` : `expect(${JSON.stringify(codes)}).toContain(res.status);`,
+    expectNoShapeErrors: 'expect(shapeErrors(res.body, schema)).toEqual([]);',
+    expectNull: (expr) => `expect(${expr}).toBeNull();`,
+};
+const VITEST_DIALECT = {
+    framework: 'vitest',
+    typed: true,
+    fileExtension: '.contract.test.ts',
+    supportFile: 'nativ-contract-support.ts',
+    supportImport: '../nativ-contract-support',
+    runnerImports: ["import { describe, it, expect } from 'vitest';"],
+    ...JEST_LIKE,
+};
+const JEST_DIALECT = {
+    framework: 'jest',
+    typed: true,
+    fileExtension: '.contract.test.ts',
+    supportFile: 'nativ-contract-support.ts',
+    supportImport: '../nativ-contract-support',
+    runnerImports: ["import { describe, it, expect } from '@jest/globals';"],
+    ...JEST_LIKE,
+};
+const NODE_TEST_DIALECT = {
+    framework: 'node:test',
+    typed: false,
+    fileExtension: '.contract.test.mjs',
+    supportFile: 'nativ-contract-support.mjs',
+    supportImport: '../nativ-contract-support.mjs',
+    runnerImports: ["import { describe, it } from 'node:test';", "import assert from 'node:assert/strict';"],
+    expectRouteMounted: "assert.ok(![404, 405].includes(res.status), 'route not mounted: HTTP ' + res.status);",
+    expectStatus: (codes) => `assert.ok(${JSON.stringify(codes)}.includes(res.status), 'expected HTTP ${codes.join('/')}, got ' + res.status);`,
+    expectNoShapeErrors: 'assert.deepEqual(shapeErrors(res.body, schema), []);',
+    expectNull: (expr) => `assert.equal(${expr}, null);`,
+};
+function renderJsApiCase(d, c) {
+    const pad = '    ';
+    const lines = [`  it(${JSON.stringify(c.name)}, async () => {`];
+    const requestType = d.typed ? ': ContractRequest' : '';
+    lines.push(`${pad}const request${requestType} = ${hang(JSON.stringify(c.request, null, 2), pad)};`);
+    lines.push(`${pad}const res = await callEndpoint(request${c.kind === 'auth-required' ? ', { anonymous: true }' : ''});`);
+    if (c.kind === 'route')
+        lines.push(pad + d.expectRouteMounted);
+    for (const a of c.assertions) {
+        if (a.kind === 'status')
+            lines.push(pad + d.expectStatus(statusList(a.expected)));
+        else if (a.kind === 'response-shape') {
+            const schemaType = d.typed ? ': SchemaNode' : '';
+            lines.push(`${pad}const schema${schemaType} = ${hang(JSON.stringify(a.schema, null, 2), pad)};`);
+            lines.push(pad + d.expectNoShapeErrors);
+        }
+    }
+    lines.push('  });');
+    return lines;
+}
+function renderJsApiSuite(d, suite) {
+    const usesShape = suite.cases.some((c) => c.assertions.some((a) => a.kind === 'response-shape'));
+    const names = ['callEndpoint', ...(usesShape ? ['shapeErrors'] : [])];
+    if (d.typed)
+        names.push('type ContractRequest', ...(usesShape ? ['type SchemaNode'] : []));
+    const lines = [
+        ...suiteHeader('//', suite),
+        ...d.runnerImports,
+        `import { ${names.join(', ')} } from '${d.supportImport}';`,
+        '',
+        `describe(${JSON.stringify(suite.name)}, () => {`,
+    ];
+    suite.cases.forEach((c, i) => {
+        if (i > 0)
+            lines.push('');
+        lines.push(...renderJsApiCase(d, c));
+    });
+    lines.push('});', '');
+    return lines.join('\n');
+}
+function tableOf(suite) {
+    return suite.source.kind === 'table' ? suite.source.table : suite.id;
+}
+function renderJsDbSuite(d, suite) {
+    const names = ['dbCheck', 'loadLiveSchema', ...(d.typed ? ['type DbAssertion'] : [])];
+    const lines = [
+        ...suiteHeader('//', suite),
+        ...d.runnerImports,
+        `import { ${names.join(', ')} } from '${d.supportImport}';`,
+        '',
+        'const live = loadLiveSchema();',
+    ];
+    if (d.framework === 'node:test') {
+        lines.push('', `describe(${JSON.stringify(suite.name)}, { skip: live.connected ? false : 'live database unavailable: ' + live.error }, () => {`);
+    }
+    else {
+        lines.push("if (!live.connected) console.warn('[nativ] skipping database contract tests: ' + live.error);", 'const describeLive = live.connected ? describe : describe.skip;', '', `describeLive(${JSON.stringify(suite.name)}, () => {`);
+    }
+    const pad = '    ';
+    suite.cases.forEach((c, i) => {
+        if (i > 0)
+            lines.push('');
+        lines.push(`  it(${JSON.stringify(c.name)}, () => {`);
+        for (const a of c.assertions) {
+            const cast = d.typed ? ' as DbAssertion' : '';
+            lines.push(pad + d.expectNull(`dbCheck(live, ${hang(JSON.stringify(a, null, 2), pad)}${cast})`));
+        }
+        lines.push('  });');
+    });
+    lines.push('});', '');
+    return lines.join('\n');
+}
+function createJsAdapter(d) {
+    return {
+        framework: d.framework,
+        language: d.typed ? 'typescript' : 'javascript',
+        fileExtension: d.fileExtension,
+        suiteFileName: (suite) => suite.suiteType === 'db-integrity' ? `db/${slug(tableOf(suite))}${d.fileExtension}` : `api/${slug(suite.id)}${d.fileExtension}`,
+        renderSuite: (suite) => (suite.suiteType === 'db-integrity' ? renderJsDbSuite(d, suite) : renderJsApiSuite(d, suite)),
+        renderSupportFiles: (ctx) => [
+            { relativePath: d.supportFile, content: applyBaseUrl(d.typed ? TS_SUPPORT : JS_SUPPORT, ctx.baseUrl), suiteType: 'support' },
+        ],
+    };
+}
+// ─── pytest adapter ────────────────────────────────────────────────────────
+function renderPyApiCase(suite, c) {
+    const pad = '    ';
+    const lines = [`def test_${snake(suite.id)}_${snake(c.kind)}():`, `${pad}${JSON.stringify(`${suite.name}: ${c.name}`)}`];
+    lines.push(`${pad}request = ${pyLiteral(c.request, 1)}`);
+    lines.push(`${pad}status, body = call_endpoint(request${c.kind === 'auth-required' ? ', anonymous=True' : ''})`);
+    if (c.kind === 'route')
+        lines.push(`${pad}assert status not in (404, 405), "route not mounted: HTTP %d" % status`);
+    for (const a of c.assertions) {
+        if (a.kind === 'status') {
+            const codes = statusList(a.expected);
+            lines.push(`${pad}assert status in ${pyTuple(codes)}, "expected HTTP ${codes.join('/')}, got %d: %r" % (status, body)`);
+        }
+        else if (a.kind === 'response-shape') {
+            lines.push(`${pad}schema = ${pyLiteral(a.schema, 1)}`);
+            lines.push(`${pad}errors = shape_errors(body, schema)`);
+            lines.push(`${pad}assert errors == [], "\\n".join(errors)`);
+        }
+    }
+    return lines;
+}
+function renderPyApiSuite(suite) {
+    const usesShape = suite.cases.some((c) => c.assertions.some((a) => a.kind === 'response-shape'));
+    const lines = [
+        ...suiteHeader('#', suite),
+        `from nativ_contract_support import call_endpoint${usesShape ? ', shape_errors' : ''}`,
+    ];
+    for (const c of suite.cases)
+        lines.push('', '', ...renderPyApiCase(suite, c));
+    lines.push('');
+    return lines.join('\n');
+}
+function renderPyDbSuite(suite) {
+    const lines = [
+        ...suiteHeader('#', suite),
+        'import pytest',
+        '',
+        'from nativ_contract_support import db_check, load_live_schema',
+        '',
+        'LIVE = load_live_schema()',
+        'pytestmark = pytest.mark.skipif(not LIVE["connected"], reason="live database unavailable: %s" % LIVE["error"])',
+    ];
+    for (const c of suite.cases) {
+        lines.push('', '', `def test_${snake(c.id)}():`, `    ${JSON.stringify(`${suite.name}: ${c.name}`)}`);
+        for (const a of c.assertions) {
+            lines.push(`    error = db_check(LIVE, ${pyLiteral(a, 1)})`, '    assert error is None, error');
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+const PYTEST_ADAPTER = {
+    framework: 'pytest',
+    language: 'python',
+    fileExtension: '.py',
+    suiteFileName: (suite) => suite.suiteType === 'db-integrity' ? `test_db_${snake(tableOf(suite))}.py` : `test_api_${snake(suite.id)}.py`,
+    renderSuite: (suite) => (suite.suiteType === 'db-integrity' ? renderPyDbSuite(suite) : renderPyApiSuite(suite)),
+    renderSupportFiles: (ctx) => [
+        { relativePath: 'nativ_contract_support.py', content: applyBaseUrl(PY_SUPPORT, ctx.baseUrl), suiteType: 'support' },
+    ],
+};
+// ─── Go adapter ────────────────────────────────────────────────────────────
+function renderGoApiCase(c) {
+    const pad = '\t\t';
+    const lines = [`\tt.Run(${JSON.stringify(c.name)}, func(t *testing.T) {`];
+    lines.push(`${pad}res := callEndpoint(t, ${goJson(c.request)}, ${c.kind === 'auth-required'})`);
+    if (c.kind === 'route')
+        lines.push(`${pad}expectRouteMounted(t, res)`);
+    for (const a of c.assertions) {
+        if (a.kind === 'status')
+            lines.push(`${pad}expectStatus(t, res, ${statusList(a.expected).join(', ')})`);
+        else if (a.kind === 'response-shape')
+            lines.push(`${pad}expectShape(t, res, ${goJson(a.schema)})`);
+    }
+    lines.push('\t})');
+    return lines;
+}
+function renderGoApiSuite(suite) {
+    const lines = [...suiteHeader('//', suite), '', 'package contract', '', 'import "testing"', '', `func TestAPI${pascal(suite.id)}(t *testing.T) {`];
+    suite.cases.forEach((c, i) => {
+        if (i > 0)
+            lines.push('');
+        lines.push(...renderGoApiCase(c));
+    });
+    lines.push('}', '');
+    return lines.join('\n');
+}
+function renderGoDbSuite(suite) {
+    const lines = [
+        ...suiteHeader('//', suite),
+        '',
+        'package contract',
+        '',
+        'import "testing"',
+        '',
+        `func TestDB${pascal(tableOf(suite))}(t *testing.T) {`,
+        '\tlive := requireLiveSchema(t)',
+    ];
+    for (const c of suite.cases) {
+        lines.push('', `\tt.Run(${JSON.stringify(c.name)}, func(t *testing.T) {`);
+        for (const a of c.assertions)
+            lines.push(`\t\texpectDB(t, live, ${goJson(a)})`);
+        lines.push('\t})');
+    }
+    lines.push('}', '');
+    return lines.join('\n');
+}
+const GO_ADAPTER = {
+    framework: 'go',
+    language: 'go',
+    fileExtension: '_test.go',
+    suiteFileName: (suite) => suite.suiteType === 'db-integrity' ? `db_${snake(tableOf(suite))}_test.go` : `api_${snake(suite.id)}_test.go`,
+    renderSuite: (suite) => (suite.suiteType === 'db-integrity' ? renderGoDbSuite(suite) : renderGoApiSuite(suite)),
+    renderSupportFiles: (ctx) => [
+        { relativePath: 'nativ_support_test.go', content: applyBaseUrl(GO_SUPPORT, ctx.baseUrl), suiteType: 'support' },
+    ],
+};
+export const TEST_FRAMEWORK_ADAPTERS = {
+    vitest: createJsAdapter(VITEST_DIALECT),
+    jest: createJsAdapter(JEST_DIALECT),
+    'node:test': createJsAdapter(NODE_TEST_DIALECT),
+    pytest: PYTEST_ADAPTER,
+    go: GO_ADAPTER,
+};
+// ─── Orchestration ─────────────────────────────────────────────────────────
+function toDisplayPath(targetDir, filePath) {
+    const rel = path.relative(targetDir, filePath);
+    const inside = rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+    return (inside ? rel || '.' : filePath).split(path.sep).join('/');
+}
+/** Writes generated files, refusing to overwrite any file that was not generated by nativ. */
+function writeGeneratedFiles(outputDir, files) {
+    const resolved = files.map((file) => {
+        const filePath = path.resolve(outputDir, file.relativePath);
+        const rel = path.relative(outputDir, filePath);
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+            throw new TestGenError('INVALID_OUTPUT_PATH', `Generated path escapes the output directory: ${file.relativePath}`);
+        }
+        return { filePath, file };
+    });
+    for (const { filePath, file } of resolved) {
+        if (!fs.existsSync(filePath))
+            continue;
+        const head = fs.readFileSync(filePath, 'utf8').slice(0, 512);
+        if (!GENERATED_MARKER_PATTERN.test(head)) {
+            throw new TestGenError('OUTPUT_CONFLICT', `Refusing to overwrite ${file.relativePath}: it was not generated by nativ test gen`);
+        }
+    }
+    for (const { filePath, file } of resolved) {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, file.content, 'utf8');
+    }
+}
+/** Compiles .ai contracts into test files for the chosen framework (written unless dryRun). */
+export function generateContractTests(options) {
+    const started = Date.now();
+    const opts = resolveTestGenOptions(options);
+    const api = loadApiContracts(opts.targetDir);
+    const db = loadDbSchemaContract(opts.targetDir);
+    if (!api && !db) {
+        throw new TestGenError('NO_CONTRACTS', `No .ai/api_contracts.json or .ai/db_schema.json found in ${opts.targetDir}`);
+    }
+    const endpointSuites = api ? buildEndpointSuites(api) : [];
+    const tableSuites = db ? buildDbSuites(db) : [];
+    const suites = [...endpointSuites, ...tableSuites];
+    const adapter = TEST_FRAMEWORK_ADAPTERS[opts.framework];
+    const ctx = {
+        projectName: api?.projectName || db?.projectName || path.basename(opts.targetDir),
+        baseUrl: opts.baseUrl,
+        engine: db?.engine ?? null,
+    };
+    const files = suites.length ? [...(adapter.renderSupportFiles?.(ctx) ?? [])] : [];
+    for (const suite of suites) {
+        files.push({ relativePath: adapter.suiteFileName(suite), content: adapter.renderSuite(suite, ctx), suiteType: suite.suiteType });
+    }
+    if (!opts.dryRun)
+        writeGeneratedFiles(opts.outputDir, files);
+    return {
+        projectName: ctx.projectName,
+        framework: opts.framework,
+        outputDir: toDisplayPath(opts.targetDir, opts.outputDir),
+        files,
+        endpointsCovered: endpointSuites.length,
+        tablesCovered: tableSuites.length,
+        durationMs: Date.now() - started,
+    };
+}