@njeybe/nativ 2.0.0

package/dist/core/telemetry.js

@@ -0,0 +1,416 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import pc from 'picocolors';
+import { withFileLock } from './lock-manager.js';
+/** Oldest entries are dropped past this, so a chatty agent cannot grow telemetry.json without bound. */
+export const MAX_ROLE_VIOLATIONS = 200;
+/** Model whose rates price heuristic estimates; matches the native engine's default model. */
+export const DEFAULT_TELEMETRY_MODEL = 'claude-opus-5-5';
+/** List price of DEFAULT_TELEMETRY_MODEL; also the fallback for models missing from MODEL_PRICING. */
+export const INPUT_TOKEN_COST_PER_M = 4.0; // $4.00 / 1M tokens
+export const OUTPUT_TOKEN_COST_PER_M = 20.0; // $20.00 / 1M tokens
+function standardPricing(inputPerM, outputPerM, cacheReadPerM = inputPerM * 0.1) {
+    return { inputPerM, outputPerM, cacheWritePerM: inputPerM * 1.25, cacheReadPerM };
+}
+/** First-party Claude API list prices in USD per 1M tokens. */
+export const MODEL_PRICING = {
+    'claude-fable-5-1': standardPricing(10, 50, 0.25),
+    'claude-fable-5': standardPricing(10, 50),
+    'claude-opus-5-5': standardPricing(4, 20, 0.2),
+    'claude-opus-5': standardPricing(5, 25),
+    'claude-opus-4-8': standardPricing(5, 25),
+    'claude-opus-4-7': standardPricing(5, 25),
+    'claude-opus-4-6': standardPricing(5, 25),
+    'claude-sonnet-5': standardPricing(2, 10),
+    'claude-sonnet-4-6': standardPricing(3, 15),
+    'claude-haiku-4-5': standardPricing(1, 5),
+};
+/** Unknown models fall back to the heuristic estimate rates so spend is never silently zero. */
+const FALLBACK_PRICING = standardPricing(INPUT_TOKEN_COST_PER_M, OUTPUT_TOKEN_COST_PER_M);
+/** True when MODEL_PRICING knows the model (exactly or as a dated / suffixed variant). */
+export function isPricedModel(model) {
+    return typeof model === 'string' && Object.keys(MODEL_PRICING).some((id) => model === id || model.startsWith(`${id}-`));
+}
+/** Resolves pricing by exact ID, then by longest known prefix (e.g. dated or `-fast` variants). */
+export function resolveModelPricing(model) {
+    const exact = MODEL_PRICING[model];
+    if (exact)
+        return exact;
+    const prefix = Object.keys(MODEL_PRICING)
+        .filter((id) => model.startsWith(id))
+        .sort((a, b) => b.length - a.length)[0];
+    return prefix ? MODEL_PRICING[prefix] : FALLBACK_PRICING;
+}
+/** Prices one usage slice with the model's input, output, cache-write and cache-read rates. */
+export function computeActualCostUsd(model, usage) {
+    const p = resolveModelPricing(model);
+    const cost = (usage.inputTokens * p.inputPerM +
+        usage.outputTokens * p.outputPerM +
+        usage.cacheCreationTokens * p.cacheWritePerM +
+        usage.cacheReadTokens * p.cacheReadPerM) /
+        1_000_000;
+    return Math.round(cost * 1_000_000) / 1_000_000;
+}
+export function emptyActualUsage(model) {
+    return {
+        model,
+        turns: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheCreationTokens: 0,
+        cacheReadTokens: 0,
+        thinkingTokens: 0,
+        costUsd: 0,
+    };
+}
+/** Sums two usage records; the result keeps `a.model` unless `a` is empty. */
+export function mergeActualUsage(a, b) {
+    return {
+        model: a.turns > 0 ? a.model : b.model,
+        turns: a.turns + b.turns,
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        cacheCreationTokens: a.cacheCreationTokens + b.cacheCreationTokens,
+        cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+        thinkingTokens: a.thinkingTokens + b.thinkingTokens,
+        costUsd: Math.round((a.costUsd + b.costUsd) * 1_000_000) / 1_000_000,
+    };
+}
+export function cacheHitRate(usage) {
+    const promptTokens = usage.inputTokens + usage.cacheCreationTokens + usage.cacheReadTokens;
+    return promptTokens > 0 ? Math.round((usage.cacheReadTokens / promptTokens) * 10000) / 10000 : 0;
+}
+/** Prices estimated input/output tokens at a model's list rates. */
+export function priceEstimate(model, inputEstimated, outputEstimated) {
+    const p = resolveModelPricing(model);
+    const cost = (inputEstimated / 1_000_000) * p.inputPerM + (outputEstimated / 1_000_000) * p.outputPerM;
+    return Math.round(cost * 10000) / 10000;
+}
+/**
+ * Calculates estimated tokens and cost based on contract slice, target files, and diff heuristics.
+ */
+export function estimateTokens(targetDir, task, model = DEFAULT_TELEMETRY_MODEL) {
+    let fileBytes = 0;
+    if (Array.isArray(task.targetFiles)) {
+        for (const relFile of task.targetFiles) {
+            const fullPath = path.resolve(targetDir, relFile);
+            if (fs.existsSync(fullPath)) {
+                try {
+                    const stat = fs.statSync(fullPath);
+                    if (stat.isFile()) {
+                        fileBytes += stat.size;
+                    }
+                }
+                catch {
+                    // ignore unreadable files
+                }
+            }
+        }
+    }
+    // Base prompt context (contracts + role guide + system prompt) ~ 3,500 tokens
+    const baseContextTokens = 3500;
+    const fileTokens = Math.round(fileBytes / 4);
+    const inputEstimated = baseContextTokens + fileTokens;
+    // Output estimation: diff or file modification approximation
+    let outputEstimated = 350; // minimum baseline generation
+    if (fileBytes > 0) {
+        outputEstimated = Math.max(350, Math.round(fileBytes / 6));
+    }
+    return {
+        inputEstimated,
+        outputEstimated,
+        totalEstimated: inputEstimated + outputEstimated,
+        costUsdEstimated: priceEstimate(model, inputEstimated, outputEstimated),
+    };
+}
+/**
+ * Loads project telemetry from .ai/telemetry.json or returns a fresh initialized state.
+ */
+export function loadTelemetry(telemetryPath, projectName = 'project') {
+    if (fs.existsSync(telemetryPath)) {
+        try {
+            const raw = fs.readFileSync(telemetryPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && Array.isArray(parsed.tasks)) {
+                // Files written before the current model table name retired models (e.g. claude-3-7-sonnet);
+                // estimates are priced at the current default instead.
+                if (!isPricedModel(parsed.modelTierDefault))
+                    parsed.modelTierDefault = DEFAULT_TELEMETRY_MODEL;
+                return parsed;
+            }
+        }
+        catch {
+            // Fall through to initial structure
+        }
+    }
+    return {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        version: '1.0.0',
+        projectName,
+        lastUpdated: new Date().toISOString(),
+        modelTierDefault: DEFAULT_TELEMETRY_MODEL,
+        summary: {
+            totalTasksCompleted: 0,
+            totalDurationMs: 0,
+            estimatedTotalTokens: 0,
+            estimatedTotalCostUsd: 0,
+            verificationPassRate: 1.0,
+            totalVerificationsRun: 0,
+            totalVerificationsPassed: 0,
+            circuitBreakerTrips: 0,
+        },
+        tasks: [],
+    };
+}
+/**
+ * Atomically writes telemetry to disk with Windows EPERM resilience.
+ */
+export function saveTelemetry(telemetryPath, telemetry) {
+    telemetry.lastUpdated = new Date().toISOString();
+    const dir = path.dirname(telemetryPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const tmpPath = `${telemetryPath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+    try {
+        fs.writeFileSync(tmpPath, JSON.stringify(telemetry, null, 2) + '\n', 'utf8');
+        let renamed = false;
+        for (let attempt = 0; attempt < 10; attempt++) {
+            try {
+                fs.renameSync(tmpPath, telemetryPath);
+                renamed = true;
+                break;
+            }
+            catch (err) {
+                if (err.code === 'EPERM' || err.code === 'EBUSY') {
+                    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+        if (!renamed) {
+            fs.copyFileSync(tmpPath, telemetryPath);
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch {
+                // Best effort
+            }
+        }
+        return true;
+    }
+    catch {
+        fs.rmSync(tmpPath, { force: true });
+        return false;
+    }
+}
+/**
+ * Recomputes aggregate summary metrics across all recorded tasks.
+ */
+export function recomputeTelemetrySummary(telemetry) {
+    const completedTasks = telemetry.tasks.filter((t) => t.status === 'completed');
+    telemetry.summary.totalTasksCompleted = completedTasks.length;
+    let totalDuration = 0;
+    let totalTokens = 0;
+    let totalCost = 0;
+    for (const t of completedTasks) {
+        totalDuration += t.durationMs || 0;
+        if (t.tokens) {
+            // Token estimates are kept as recorded; only the rate is current, so older records are re-priced.
+            t.tokens.costUsdEstimated = priceEstimate(telemetry.modelTierDefault, t.tokens.inputEstimated || 0, t.tokens.outputEstimated || 0);
+            totalTokens += t.tokens.totalEstimated || 0;
+            totalCost += t.tokens.costUsdEstimated;
+        }
+    }
+    telemetry.summary.totalDurationMs = totalDuration;
+    telemetry.summary.estimatedTotalTokens = totalTokens;
+    telemetry.summary.estimatedTotalCostUsd = Math.round(totalCost * 10000) / 10000;
+    let actual = emptyActualUsage(telemetry.modelTierDefault);
+    for (const t of telemetry.tasks) {
+        if (t.actualUsage)
+            actual = mergeActualUsage(actual, t.actualUsage);
+    }
+    telemetry.summary.actualSpendUsd = Math.round(actual.costUsd * 10000) / 10000;
+    telemetry.summary.actualInputTokens = actual.inputTokens;
+    telemetry.summary.actualOutputTokens = actual.outputTokens;
+    telemetry.summary.cacheReadTokens = actual.cacheReadTokens;
+    telemetry.summary.cacheCreationTokens = actual.cacheCreationTokens;
+    telemetry.summary.thinkingTokens = actual.thinkingTokens;
+    telemetry.summary.cacheHitRate = cacheHitRate(actual);
+    if (telemetry.summary.totalVerificationsRun > 0) {
+        telemetry.summary.verificationPassRate =
+            Math.round((telemetry.summary.totalVerificationsPassed / telemetry.summary.totalVerificationsRun) * 100) / 100;
+    }
+    else {
+        telemetry.summary.verificationPassRate = 1.0;
+    }
+}
+/**
+ * Records the start of an agent task in .ai/telemetry.json.
+ */
+export async function recordTaskStart(targetDir, task) {
+    const telemetryPath = path.join(targetDir, '.ai', 'telemetry.json');
+    await withFileLock(telemetryPath, () => {
+        const telemetry = loadTelemetry(telemetryPath, path.basename(targetDir));
+        const existing = telemetry.tasks.find((t) => t.taskId === task.id);
+        if (existing) {
+            existing.startedAt = new Date().toISOString();
+            existing.status = 'in_progress';
+        }
+        else {
+            telemetry.tasks.push({
+                taskId: task.id,
+                title: task.title,
+                assignedSubagent: task.assignedSubagent,
+                startedAt: new Date().toISOString(),
+                durationMs: 0,
+                status: 'in_progress',
+                notes: task.notes || '',
+            });
+        }
+        saveTelemetry(telemetryPath, telemetry);
+    });
+}
+/**
+ * Records completion of an agent task, tracking duration, verification results, tokens, and cost.
+ */
+export async function recordTaskComplete(targetDir, task, verificationResult, notes) {
+    const telemetryPath = path.join(targetDir, '.ai', 'telemetry.json');
+    return withFileLock(telemetryPath, () => {
+        const telemetry = loadTelemetry(telemetryPath, path.basename(targetDir));
+        let record = telemetry.tasks.find((t) => t.taskId === task.id);
+        const now = new Date();
+        const completedAt = now.toISOString();
+        if (!record) {
+            record = {
+                taskId: task.id,
+                title: task.title,
+                assignedSubagent: task.assignedSubagent,
+                startedAt: completedAt,
+                durationMs: 0,
+                status: 'completed',
+            };
+            telemetry.tasks.push(record);
+        }
+        const startTime = new Date(record.startedAt || completedAt).getTime();
+        record.completedAt = completedAt;
+        record.durationMs = Math.max(0, now.getTime() - startTime);
+        record.status = 'completed';
+        if (notes)
+            record.notes = notes;
+        if (verificationResult) {
+            record.verification = {
+                command: verificationResult.command,
+                durationMs: verificationResult.durationMs,
+                exitCode: verificationResult.exitCode,
+                skipped: verificationResult.skipped === true,
+            };
+            if (!verificationResult.skipped) {
+                telemetry.summary.totalVerificationsRun++;
+                if (verificationResult.success) {
+                    telemetry.summary.totalVerificationsPassed++;
+                }
+            }
+        }
+        record.tokens = estimateTokens(targetDir, task, telemetry.modelTierDefault);
+        recomputeTelemetrySummary(telemetry);
+        saveTelemetry(telemetryPath, telemetry);
+        return record;
+    });
+}
+/**
+ * Folds one native run's API-reported usage into the task's grounded telemetry.
+ * Creates the task record when the run was dispatched without `nativ task start`.
+ */
+export async function recordRunnerUsage(targetDir, task, usage) {
+    const telemetryPath = path.join(targetDir, '.ai', 'telemetry.json');
+    return withFileLock(telemetryPath, () => {
+        const telemetry = loadTelemetry(telemetryPath, path.basename(targetDir));
+        let record = telemetry.tasks.find((t) => t.taskId === task.id);
+        if (!record) {
+            record = {
+                taskId: task.id,
+                title: task.title,
+                assignedSubagent: task.assignedSubagent,
+                startedAt: new Date().toISOString(),
+                durationMs: 0,
+                status: 'in_progress',
+            };
+            telemetry.tasks.push(record);
+        }
+        record.actualUsage = record.actualUsage ? mergeActualUsage(record.actualUsage, usage) : { ...usage };
+        recomputeTelemetrySummary(telemetry);
+        saveTelemetry(telemetryPath, telemetry);
+        return record;
+    });
+}
+/**
+ * Logs a role-enforcement violation to .ai/telemetry.json. Best effort: it never throws, because the
+ * hook that calls it must not fail an agent's tool call over bookkeeping.
+ */
+export async function recordRoleViolation(targetDir, violation) {
+    try {
+        const telemetryPath = path.join(targetDir, '.ai', 'telemetry.json');
+        await withFileLock(telemetryPath, () => {
+            const telemetry = loadTelemetry(telemetryPath, path.basename(targetDir));
+            const violations = telemetry.violations ?? [];
+            violations.push({ at: new Date().toISOString(), ...violation });
+            telemetry.violations = violations.slice(-MAX_ROLE_VIOLATIONS);
+            telemetry.summary.roleViolations = (telemetry.summary.roleViolations ?? 0) + 1;
+            saveTelemetry(telemetryPath, telemetry);
+        });
+    }
+    catch {
+        // Bookkeeping only.
+    }
+}
+/**
+ * Increments circuit breaker trips counter in telemetry.
+ */
+export async function recordCircuitBreakerTrip(targetDir, taskId) {
+    const telemetryPath = path.join(targetDir, '.ai', 'telemetry.json');
+    await withFileLock(telemetryPath, () => {
+        const telemetry = loadTelemetry(telemetryPath, path.basename(targetDir));
+        telemetry.summary.circuitBreakerTrips++;
+        const record = telemetry.tasks.find((t) => t.taskId === taskId);
+        if (record) {
+            record.status = 'blocked';
+        }
+        saveTelemetry(telemetryPath, telemetry);
+    });
+}
+/**
+ * Returns formatted telemetry dashboard summary lines for CLI display.
+ */
+export function formatTelemetrySummary(telemetry, plan) {
+    const { summary } = telemetry;
+    const minutes = (summary.totalDurationMs / 60000).toFixed(1);
+    const passPct = Math.round(summary.verificationPassRate * 100);
+    // Tasks completed before telemetry existed (or with --no-verify from older builds) have no record.
+    const untracked = plan ? Math.max(0, plan.completedTasks - summary.totalTasksCompleted) : 0;
+    const lines = [
+        pc.bold(pc.cyan('\n⚡ Execution & Cost Telemetry')),
+        pc.dim('  Model Tier Benchmark: ') + pc.white(telemetry.modelTierDefault),
+        pc.dim('  Tasks Completed:      ') +
+            pc.green(`${summary.totalTasksCompleted}`) +
+            (untracked ? pc.dim(` measured (+${untracked} completed without telemetry)`) : ''),
+        pc.dim('  Total Time Active:    ') + pc.white(`${minutes} min (${summary.totalDurationMs}ms)`),
+        pc.dim('  Estimated Tokens:     ') + pc.yellow(`${summary.estimatedTotalTokens.toLocaleString()}`),
+        pc.dim('  Estimated Cost:       ') + pc.green(`$${summary.estimatedTotalCostUsd.toFixed(4)} USD`),
+        ...(summary.actualSpendUsd
+            ? [
+                pc.dim('  Actual Spend:         ') +
+                    pc.green(`$${summary.actualSpendUsd.toFixed(4)} USD`) +
+                    pc.dim(` (cache hit ${Math.round((summary.cacheHitRate ?? 0) * 100)}%)`),
+            ]
+            : []),
+        pc.dim('  Verification Pass:    ') +
+            (passPct >= 80 ? pc.green(`${passPct}%`) : pc.red(`${passPct}%`)) +
+            pc.dim(` (${summary.totalVerificationsPassed}/${summary.totalVerificationsRun} runs)`),
+        pc.dim('  Circuit Breaker Trips:') +
+            (summary.circuitBreakerTrips > 0 ? pc.red(` ${summary.circuitBreakerTrips}`) : pc.dim(' 0')),
+    ];
+    return lines.join('\n');
+}

package/dist/core/test-generator-types.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Contract-to-test generator types (nativ test gen).
+ * Result/request shapes conform to POST /api/tests/generate in .ai/api_contracts.json.
+ * Endpoint suites are built from .ai/api_contracts.json, database integrity suites from .ai/db_schema.json.
+ */
+import type { DatabaseEngine, TableSchema } from '../db/types.js';
+export type TestFramework = 'vitest' | 'jest' | 'node:test' | 'pytest' | 'go';
+export declare const TEST_FRAMEWORKS: readonly TestFramework[];
+export declare function isTestFramework(value: string): value is TestFramework;
+export type TestLanguage = 'typescript' | 'javascript' | 'python' | 'go';
+/** Kinds of generated suite; serialized as `suiteType` on each generated file. */
+export type TestSuiteType = 'api-contract' | 'db-integrity' | 'support';
+export declare const DEFAULT_TEST_OUTPUT_DIR = "tests/contract";
+export declare const DEFAULT_TEST_FRAMEWORK: TestFramework;
+export declare const DEFAULT_TEST_BASE_URL = "http://localhost:3000";
+/** POST /api/tests/generate request body. */
+export interface TestGenerateRequest {
+    outputDir?: string;
+    framework?: TestFramework;
+    baseUrl?: string;
+    dryRun?: boolean;
+}
+/** Options accepted by the generator (CLI flags, studio endpoint, MCP tool). */
+export interface TestGenOptions extends TestGenerateRequest {
+    /** Project root containing the .ai/ directory. */
+    targetDir: string;
+}
+/** TestGenOptions with every default applied. */
+export interface ResolvedTestGenOptions {
+    targetDir: string;
+    outputDir: string;
+    framework: TestFramework;
+    baseUrl: string;
+    dryRun: boolean;
+}
+export interface GeneratedTestFile {
+    /** Path relative to outputDir, forward slashes. */
+    relativePath: string;
+    content: string;
+    suiteType: TestSuiteType;
+}
+/** POST /api/tests/generate response body. */
+export interface TestGenResult {
+    projectName: string;
+    framework: TestFramework;
+    outputDir: string;
+    files: GeneratedTestFile[];
+    endpointsCovered: number;
+    tablesCovered: number;
+    durationMs: number;
+}
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * A field in a contract body is either a nested object of fields or a descriptor string
+ * such as "string ('dev' | 'prod')", "integer (optional, default 1)" or "array of TableSchema".
+ */
+export type ContractFieldValue = string | null | {
+    [field: string]: ContractFieldValue;
+};
+export interface ApiEndpointRequest {
+    headers?: Record<string, string>;
+    queryParams?: Record<string, string>;
+    pathParams?: Record<string, string>;
+    body?: ContractFieldValue;
+}
+export interface ApiEndpointResponse {
+    description?: string;
+    body?: ContractFieldValue;
+}
+export interface ApiEndpointContract {
+    id: string;
+    path: string;
+    method: HttpMethod;
+    description?: string;
+    auth: boolean;
+    request: ApiEndpointRequest;
+    /** Keyed by HTTP status code ("200", "400", ...). */
+    responses: Record<string, ApiEndpointResponse>;
+}
+export interface ApiContractsDocument {
+    version?: string;
+    projectName: string;
+    baseUrl?: string;
+    authScheme?: string;
+    endpoints: ApiEndpointContract[];
+}
+export interface DbSchemaDocument {
+    version?: string;
+    projectName: string;
+    engine: DatabaseEngine;
+    tables: TableSchema[];
+}
+export type PrimitiveKind = 'string' | 'number' | 'integer' | 'boolean' | 'null' | 'any';
+interface SchemaNodeBase {
+    /** Field may be absent ("optional", "required if ..."). */
+    optional?: boolean;
+    /** Condition from "required if <expr>" descriptors, kept verbatim. */
+    requiredIf?: string;
+    /** Free-text parenthetical from the descriptor, e.g. "default 1" or "e.g. 'MONGO_URI'". */
+    note?: string;
+}
+export interface PrimitiveNode extends SchemaNodeBase {
+    kind: 'primitive';
+    type: PrimitiveKind;
+}
+export interface EnumNode extends SchemaNodeBase {
+    kind: 'enum';
+    base: 'string' | 'number';
+    values: Array<string | number>;
+}
+export interface ObjectNode extends SchemaNodeBase {
+    kind: 'object';
+    /** Empty with `open: true` for untyped "object" descriptors. */
+    properties: Record<string, SchemaNode>;
+    open: boolean;
+}
+export interface ArrayNode extends SchemaNodeBase {
+    kind: 'array';
+    items: SchemaNode;
+}
+export interface UnionNode extends SchemaNodeBase {
+    kind: 'union';
+    variants: SchemaNode[];
+}
+/** Named model such as TableSchema or TableDiff; checked structurally as an object. */
+export interface RefNode extends SchemaNodeBase {
+    kind: 'ref';
+    name: string;
+}
+export type SchemaNode = PrimitiveNode | EnumNode | ObjectNode | ArrayNode | UnionNode | RefNode;
+/**
+ * Parses a contract descriptor string into a SchemaNode.
+ * Examples: "boolean", "string | null", "integer (optional, default 25, max 100)",
+ * "string ('dev' | 'prod')", "boolean (required if env === 'prod')", "array of TableSchema",
+ * "array of { key: string, targetEnv: 'dev' | 'prod' }".
+ */
+export declare function parseFieldDescriptor(descriptor: string): SchemaNode;
+/** Builds a SchemaNode from a contract body value (nested objects, descriptor strings, or null). */
+export declare function buildSchemaNode(value: ContractFieldValue | undefined): SchemaNode;
+/** True when a schema node accepts null (nullable union or explicit null). */
+export declare function isNullableNode(node: SchemaNode): boolean;
+export type TestCaseKind = 'route' | 'auth-required' | 'invalid-payload' | 'response-schema' | 'table-exists' | 'column' | 'primary-key' | 'nullability' | 'unique-constraint';
+export interface TestRequestSpec {
+    method: HttpMethod;
+    /** Contract path with `:param` placeholders filled from pathParams. */
+    path: string;
+    query?: Record<string, string | number | boolean>;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+export type TestAssertion = {
+    kind: 'status';
+    expected: number | number[];
+} | {
+    kind: 'response-shape';
+    schema: SchemaNode;
+} | {
+    kind: 'table-exists';
+    table: string;
+} | {
+    kind: 'column-exists';
+    table: string;
+    column: string;
+    type: string;
+} | {
+    kind: 'primary-key';
+    table: string;
+    columns: string[];
+} | {
+    kind: 'nullability';
+    table: string;
+    column: string;
+    nullable: boolean;
+} | {
+    kind: 'unique-constraint';
+    table: string;
+    index: string;
+    columns: string[];
+};
+export interface TestCaseSpec {
+    /** Stable id, e.g. "db-status:route". */
+    id: string;
+    name: string;
+    kind: TestCaseKind;
+    /** Present for endpoint cases; absent for database integrity cases. */
+    request?: TestRequestSpec;
+    assertions: TestAssertion[];
+}
+export type TestSuiteSource = {
+    kind: 'endpoint';
+    endpointId: string;
+    method: HttpMethod;
+    path: string;
+} | {
+    kind: 'table';
+    table: string;
+    entityType: 'table' | 'collection';
+};
+export interface TestSuiteSpec {
+    id: string;
+    name: string;
+    suiteType: TestSuiteType;
+    source: TestSuiteSource;
+    cases: TestCaseSpec[];
+}
+export interface TestRenderContext {
+    projectName: string;
+    baseUrl: string;
+    /** Engine from .ai/db_schema.json; null when no schema contract exists. */
+    engine: DatabaseEngine | null;
+    /** Relative import path from a suite file to the generated support file, when one is emitted. */
+    supportImportPath?: string;
+}
+/** Renders framework-agnostic suites into source files for one test framework. */
+export interface TestFrameworkAdapter {
+    framework: TestFramework;
+    language: TestLanguage;
+    /** Extension including the dot, e.g. ".test.ts" or "_test.go". */
+    fileExtension: string;
+    /** Relative path (under outputDir) for a suite's file. */
+    suiteFileName(suite: TestSuiteSpec): string;
+    renderSuite(suite: TestSuiteSpec, ctx: TestRenderContext): string;
+    /** Shared helpers (HTTP client, shape matcher, DB connection stub) emitted once per run. */
+    renderSupportFiles?(ctx: TestRenderContext): GeneratedTestFile[];
+}
+export type TestFrameworkAdapterRegistry = Partial<Record<TestFramework, TestFrameworkAdapter>>;
+export {};