@rawsql-ts/ztd-cli 0.20.0 → 0.20.3

package/dist/perf/benchmark.js

@@ -0,0 +1,2186 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERF_BENCHMARK_DEFAULTS = void 0;
+exports.runPerfBenchmark = runPerfBenchmark;
+exports.toPerfPlannedSteps = toPerfPlannedSteps;
+exports.mapPipelineStatements = mapPipelineStatements;
+exports.diffPerfBenchmarkReports = diffPerfBenchmarkReports;
+exports.formatPerfBenchmarkReport = formatPerfBenchmarkReport;
+exports.formatPerfDiffReport = formatPerfDiffReport;
+exports.buildPerfPipelineAnalysis = buildPerfPipelineAnalysis;
+exports.summarizePerfDdlInventory = summarizePerfDdlInventory;
+exports.buildPerfTuningGuidance = buildPerfTuningGuidance;
+exports.buildPerfTuningSummary = buildPerfTuningSummary;
+exports.loadPerfBenchmarkReport = loadPerfBenchmarkReport;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const yaml_1 = require("yaml");
+const optionalDependencies_1 = require("../utils/optionalDependencies");
+const modelGenBinder_1 = require("../utils/modelGenBinder");
+const modelGenScanner_1 = require("../utils/modelGenScanner");
+const structure_1 = require("../query/structure");
+const scalarFilterAnalysis_1 = require("../query/scalarFilterAnalysis");
+const execute_1 = require("../query/execute");
+const planner_1 = require("../query/planner");
+const sandbox_1 = require("./sandbox");
+const DEFAULT_REPEAT = 10;
+const DEFAULT_WARMUP = 3;
+const DEFAULT_CLASSIFY_THRESHOLD_SECONDS = 60;
+const DEFAULT_TIMEOUT_MINUTES = 5;
+function assertValidPerfRunOptions(options) {
+    const issues = [];
+    if (!Number.isInteger(options.repeat) || options.repeat <= 0) {
+        issues.push('repeat must be a positive integer');
+    }
+    if (!Number.isInteger(options.warmup) || options.warmup < 0) {
+        issues.push('warmup must be a non-negative integer');
+    }
+    if (!Number.isFinite(options.timeoutMinutes) || options.timeoutMinutes <= 0) {
+        issues.push('timeoutMinutes must be greater than 0');
+    }
+    if (!Number.isFinite(options.classifyThresholdSeconds) || options.classifyThresholdSeconds <= 0) {
+        issues.push('classifyThresholdSeconds must be greater than 0');
+    }
+    if (issues.length > 0) {
+        throw new Error('invalid perf options: ' + issues.join('; '));
+    }
+}
+const PERF_REVIEW_POLICY_BY_SCALE = {
+    tiny: 'none',
+    small: 'none',
+    medium: 'recommended',
+    large: 'strongly-recommended',
+    batch: 'strongly-recommended'
+};
+const PERF_REVIEW_POLICY_SEVERITY = {
+    none: 0,
+    recommended: 1,
+    'strongly-recommended': 2
+};
+const PERF_SPEC_DISCOVERY_ROOTS = [
+    node_path_1.default.join('src', 'catalog', 'specs'),
+    node_path_1.default.join('src', 'specs'),
+    'specs'
+];
+function buildPerfQuerySpecGuidance(rootDir, queryFile, seedConfig, saveEvidence, dryRun) {
+    const discovered = discoverPerfQuerySpecMetadata(rootDir, queryFile);
+    if (!discovered) {
+        return undefined;
+    }
+    const reviewPolicy = toPerfReviewPolicy(discovered.expectedScale, discovered.expectedInputRows);
+    const relationsUsed = (0, structure_1.buildQueryStructureReport)(queryFile, 'ztd perf run').referenced_tables;
+    const fixtureRowsAvailable = countPerfSeedRows(seedConfig, relationsUsed);
+    const fixtureRowsStatus = toPerfFixtureRowsStatus(fixtureRowsAvailable, discovered.expectedInputRows);
+    const evidenceStatus = saveEvidence && !dryRun
+        ? 'captured'
+        : reviewPolicy === 'strongly-recommended' ? 'missing' : 'not-required';
+    return {
+        spec_id: discovered.specId,
+        spec_file: discovered.specFile,
+        expected_scale: discovered.expectedScale,
+        expected_input_rows: discovered.expectedInputRows,
+        expected_output_rows: discovered.expectedOutputRows,
+        review_policy: reviewPolicy,
+        evidence_status: evidenceStatus,
+        fixture_rows_available: fixtureRowsAvailable,
+        fixture_rows_status: fixtureRowsStatus
+    };
+}
+function toPerfReviewPolicy(expectedScale, expectedInputRows) {
+    const scalePolicy = expectedScale ? PERF_REVIEW_POLICY_BY_SCALE[expectedScale] : 'none';
+    const rowsPolicy = expectedInputRows === undefined
+        ? 'none'
+        : expectedInputRows >= 100000
+            ? 'strongly-recommended'
+            : expectedInputRows >= 10000
+                ? 'recommended'
+                : 'none';
+    return PERF_REVIEW_POLICY_SEVERITY[scalePolicy] >= PERF_REVIEW_POLICY_SEVERITY[rowsPolicy]
+        ? scalePolicy
+        : rowsPolicy;
+}
+function toPerfFixtureRowsStatus(fixtureRowsAvailable, expectedInputRows) {
+    if (expectedInputRows === undefined || fixtureRowsAvailable === undefined) {
+        return 'unknown';
+    }
+    return fixtureRowsAvailable >= expectedInputRows ? 'sufficient' : 'undersized';
+}
+function countPerfSeedRows(seedConfig, relationsUsed) {
+    const normalizedRelations = normalizePerfRelationNames(relationsUsed);
+    if (normalizedRelations.size === 0) {
+        return undefined;
+    }
+    let matched = false;
+    let rows = 0;
+    for (const [tableName, tableSeed] of Object.entries(seedConfig.tables)) {
+        if (!matchesPerfSeedRelation(tableName, normalizedRelations)) {
+            continue;
+        }
+        matched = true;
+        rows += tableSeed.rows;
+    }
+    return matched ? rows : undefined;
+}
+function discoverPerfQuerySpecMetadata(rootDir, queryFile) {
+    const queryCandidates = buildPerfQuerySpecSqlCandidates(rootDir, queryFile);
+    const matches = [];
+    for (const relativeRoot of PERF_SPEC_DISCOVERY_ROOTS) {
+        const absoluteRoot = node_path_1.default.resolve(rootDir, relativeRoot);
+        if (!(0, node_fs_1.existsSync)(absoluteRoot)) {
+            continue;
+        }
+        for (const filePath of walkPerfSpecFiles(absoluteRoot)) {
+            matches.push(...loadPerfQuerySpecMetadataFromFile(filePath, queryCandidates));
+        }
+    }
+    if (matches.length <= 1) {
+        return matches[0];
+    }
+    // Fail loudly when multiple specs claim the same SQL file so perf guidance stays deterministic.
+    throw new Error(`Multiple QuerySpecs matched ${node_path_1.default.resolve(queryFile)}: ${matches.map((match) => `${match.specId} (${match.specFile})`).join(', ')}`);
+}
+function buildPerfQuerySpecSqlCandidates(rootDir, queryFile) {
+    const absoluteQueryFile = node_path_1.default.resolve(queryFile);
+    const candidates = [
+        node_path_1.default.relative(rootDir, absoluteQueryFile),
+        node_path_1.default.relative(node_path_1.default.resolve(rootDir, 'src', 'sql'), absoluteQueryFile),
+        node_path_1.default.relative(node_path_1.default.resolve(rootDir, 'sql'), absoluteQueryFile)
+    ].map((value) => normalizePerfSpecPath(value))
+        .filter((value) => value.length > 0 && !value.startsWith('..'));
+    return new Set(candidates);
+}
+function normalizePerfSpecPath(value) {
+    return value.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\//, '');
+}
+function walkPerfSpecFiles(rootDir) {
+    const files = [];
+    const stack = [rootDir];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        const entries = (0, node_fs_1.readdirSync)(current, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            const absolute = node_path_1.default.join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(absolute);
+                continue;
+            }
+            if (!entry.isFile()) {
+                continue;
+            }
+            if (/\.(?:json|[cm]?[jt]s)$/iu.test(entry.name) && !/\.test\./iu.test(entry.name)) {
+                files.push(absolute);
+            }
+        }
+    }
+    return files.sort((left, right) => left.localeCompare(right));
+}
+function loadPerfQuerySpecMetadataFromFile(filePath, queryCandidates) {
+    if (node_path_1.default.extname(filePath).toLowerCase() === '.json') {
+        return loadPerfQuerySpecMetadataFromJson(filePath, queryCandidates);
+    }
+    const source = (0, node_fs_1.readFileSync)(filePath, 'utf8');
+    const discovered = [];
+    for (const block of extractPerfQuerySpecBlocks(source)) {
+        const parsed = parsePerfQuerySpecBlock(block, filePath, queryCandidates);
+        if (parsed) {
+            discovered.push(parsed);
+        }
+    }
+    return discovered;
+}
+function loadPerfQuerySpecMetadataFromJson(filePath, queryCandidates) {
+    const parsed = JSON.parse((0, node_fs_1.readFileSync)(filePath, 'utf8'));
+    if (Array.isArray(parsed)) {
+        const matches = [];
+        for (const entry of parsed) {
+            const discovered = parsePerfQuerySpecObject(entry, filePath, queryCandidates);
+            if (discovered) {
+                matches.push(discovered);
+            }
+        }
+        return matches;
+    }
+    if (typeof parsed === 'object' && parsed !== null && Array.isArray(parsed.specs)) {
+        const matches = [];
+        for (const entry of parsed.specs) {
+            const discovered = parsePerfQuerySpecObject(entry, filePath, queryCandidates);
+            if (discovered) {
+                matches.push(discovered);
+            }
+        }
+        return matches;
+    }
+    const discovered = parsePerfQuerySpecObject(parsed, filePath, queryCandidates);
+    return discovered ? [discovered] : [];
+}
+function parsePerfQuerySpecObject(value, filePath, queryCandidates) {
+    var _a, _b, _c;
+    if (typeof value !== 'object' || value === null) {
+        return undefined;
+    }
+    const record = value;
+    const sqlFile = typeof record.sqlFile === 'string' ? record.sqlFile : undefined;
+    if (!sqlFile || !matchesPerfQuerySpecSqlFile(queryCandidates, sqlFile)) {
+        return undefined;
+    }
+    const metadata = typeof record.metadata === 'object' && record.metadata !== null
+        ? record.metadata
+        : undefined;
+    const perf = metadata && typeof metadata.perf === 'object' && metadata.perf !== null
+        ? metadata.perf
+        : undefined;
+    const expectedScale = normalizePerfExpectedScale((_a = perf === null || perf === void 0 ? void 0 : perf.expectedScale) !== null && _a !== void 0 ? _a : perf === null || perf === void 0 ? void 0 : perf.expected_scale);
+    const expectedInputRows = normalizePerfMetadataNumber((_b = perf === null || perf === void 0 ? void 0 : perf.expectedInputRows) !== null && _b !== void 0 ? _b : perf === null || perf === void 0 ? void 0 : perf.expected_input_rows);
+    const expectedOutputRows = normalizePerfMetadataNumber((_c = perf === null || perf === void 0 ? void 0 : perf.expectedOutputRows) !== null && _c !== void 0 ? _c : perf === null || perf === void 0 ? void 0 : perf.expected_output_rows);
+    if (!expectedScale && expectedInputRows === undefined && expectedOutputRows === undefined) {
+        return undefined;
+    }
+    return {
+        specId: typeof record.id === 'string' ? record.id : normalizePerfSpecPath(sqlFile),
+        specFile: filePath,
+        expectedScale,
+        expectedInputRows,
+        expectedOutputRows
+    };
+}
+function extractPerfQuerySpecBlocks(source) {
+    const blocks = [];
+    const seen = new Set();
+    const sqlFileRegex = /sqlFile\s*:\s*['"`][^'"`\n]+['"`]/g;
+    for (const match of source.matchAll(sqlFileRegex)) {
+        if (typeof match.index !== 'number') {
+            continue;
+        }
+        const start = source.lastIndexOf('{', match.index);
+        if (start < 0) {
+            continue;
+        }
+        let depth = 0;
+        let end = -1;
+        for (let index = start; index < source.length; index += 1) {
+            const char = source[index];
+            if (char === '{') {
+                depth += 1;
+            }
+            else if (char === '}') {
+                depth -= 1;
+                if (depth === 0) {
+                    end = index;
+                    break;
+                }
+            }
+        }
+        if (end < 0) {
+            continue;
+        }
+        const block = source.slice(start, end + 1);
+        if (!seen.has(block)) {
+            seen.add(block);
+            blocks.push(block);
+        }
+    }
+    return blocks;
+}
+function parsePerfQuerySpecBlock(block, filePath, queryCandidates) {
+    var _a, _b, _c;
+    const sqlFile = (_a = block.match(/sqlFile\s*:\s*['"`]([^'"`\n]+)['"`]/u)) === null || _a === void 0 ? void 0 : _a[1];
+    if (!sqlFile || !matchesPerfQuerySpecSqlFile(queryCandidates, sqlFile)) {
+        return undefined;
+    }
+    const expectedScale = parsePerfExpectedScale(block);
+    const expectedInputRows = parsePerfMetadataNumber(block, ['expectedInputRows', 'expected_input_rows']);
+    const expectedOutputRows = parsePerfMetadataNumber(block, ['expectedOutputRows', 'expected_output_rows']);
+    if (!expectedScale && expectedInputRows === undefined && expectedOutputRows === undefined) {
+        return undefined;
+    }
+    const specId = (_c = (_b = block.match(/id\s*:\s*['"`]([^'"`\n]+)['"`]/u)) === null || _b === void 0 ? void 0 : _b[1]) !== null && _c !== void 0 ? _c : normalizePerfSpecPath(sqlFile);
+    return {
+        specId,
+        specFile: filePath,
+        expectedScale,
+        expectedInputRows,
+        expectedOutputRows
+    };
+}
+function matchesPerfQuerySpecSqlFile(queryCandidates, sqlFile) {
+    const normalizedSpecSqlFile = normalizePerfSpecPath(sqlFile);
+    return queryCandidates.has(normalizedSpecSqlFile);
+}
+function parsePerfExpectedScale(block) {
+    const match = block.match(/expected(?:Scale|_scale)\s*:\s*['"`](tiny|small|medium|large|batch)['"`]/u);
+    return normalizePerfExpectedScale(match === null || match === void 0 ? void 0 : match[1]);
+}
+function parsePerfMetadataNumber(block, keys) {
+    for (const key of keys) {
+        const escapedKey = key.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
+        const match = block.match(new RegExp(`${escapedKey}\\s*:\\s*(\\d+(?:_\\d+)*(?:\\.\\d+)?)`, 'u'));
+        const parsed = normalizePerfMetadataNumber(match === null || match === void 0 ? void 0 : match[1]);
+        if (parsed !== undefined) {
+            return parsed;
+        }
+    }
+    return undefined;
+}
+function normalizePerfExpectedScale(value) {
+    return value === 'tiny' || value === 'small' || value === 'medium' || value === 'large' || value === 'batch'
+        ? value
+        : undefined;
+}
+function normalizePerfMetadataNumber(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) && value >= 0 ? value : undefined;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number(value.replace(/_/g, ''));
+        return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+    }
+    return undefined;
+}
+function normalizePerfRelationNames(relationsUsed) {
+    const normalized = new Set();
+    for (const relation of relationsUsed !== null && relationsUsed !== void 0 ? relationsUsed : []) {
+        const relationName = normalizePerfRelationName(relation);
+        if (!relationName) {
+            continue;
+        }
+        normalized.add(relationName);
+        const unqualified = relationName.split('.').at(-1);
+        if (unqualified) {
+            normalized.add(unqualified);
+        }
+    }
+    return normalized;
+}
+function matchesPerfSeedRelation(tableName, relationsUsed) {
+    const normalizedTableName = normalizePerfRelationName(tableName);
+    if (!normalizedTableName) {
+        return false;
+    }
+    if (relationsUsed.has(normalizedTableName)) {
+        return true;
+    }
+    const unqualified = normalizedTableName.split('.').at(-1);
+    return Boolean(unqualified && relationsUsed.has(unqualified));
+}
+function normalizePerfRelationName(value) {
+    return value.trim().replace(/^"+|"+$/g, '').toLowerCase();
+}
+/**
+ * Execute or plan a perf benchmark against the sandbox using either direct or decomposed execution.
+ */
+async function runPerfBenchmark(options) {
+    var _a, _b, _c;
+    const strategy = (_a = options.strategy) !== null && _a !== void 0 ? _a : 'direct';
+    const material = (_b = options.material) !== null && _b !== void 0 ? _b : [];
+    assertValidPerfRunOptions({ ...options, strategy, material });
+    const prepared = prepareBenchmarkQuery(options.rootDir, options.queryFile, options.paramsFile);
+    const pipelineAnalysis = buildPerfPipelineAnalysis(prepared.absolutePath);
+    const strategyMetadata = buildRequestedStrategyMetadata(prepared.absolutePath, strategy, material);
+    const classifyThresholdMs = options.classifyThresholdSeconds * 1000;
+    const timeoutMs = options.timeoutMinutes * 60 * 1000;
+    const seedConfig = (0, sandbox_1.loadPerfSeedConfig)(options.rootDir);
+    const specGuidance = buildPerfQuerySpecGuidance(options.rootDir, prepared.absolutePath, seedConfig, options.save, options.dryRun);
+    const ddlInventory = (0, sandbox_1.inspectPerfDdlInventory)(options.rootDir);
+    const ddlInventorySummary = summarizePerfDdlInventory(ddlInventory);
+    const databaseVersion = options.dryRun ? undefined : await fetchPerfDatabaseVersion(options.rootDir);
+    const selection = options.dryRun
+        ? {
+            selectedMode: options.mode === 'auto' ? 'completion' : options.mode,
+            reason: options.mode === 'auto'
+                ? 'dry-run skips live auto classification; the real run will pick latency or completion after a thresholded probe'
+                : 'mode forced by user'
+        }
+        : options.mode === 'auto'
+            ? await classifyPerfBenchmarkMode(options.rootDir, prepared, strategy, material, classifyThresholdMs)
+            : {
+                selectedMode: options.mode,
+                reason: 'mode forced by user'
+            };
+    if (options.dryRun) {
+        const dryRunPlanFacts = {
+            observations: [],
+            statement_summary: '(no plan captured)',
+            hasCapturedPlan: false,
+            hasSequentialScan: false,
+            hasJoin: false
+        };
+        const tuningGuidance = buildPerfTuningGuidance(pipelineAnalysis, dryRunPlanFacts, specGuidance);
+        return {
+            schema_version: 1,
+            command: 'perf run',
+            query_file: prepared.absolutePath,
+            query_type: prepared.queryType,
+            params_file: options.paramsFile ? node_path_1.default.resolve(options.rootDir, options.paramsFile) : undefined,
+            params_shape: prepared.paramsShape,
+            ordered_param_names: prepared.orderedParamNames,
+            source_sql_file: prepared.absolutePath,
+            source_sql: prepared.sourceSql,
+            bound_sql: prepared.boundSql,
+            bindings: prepared.bindings,
+            strategy: strategy,
+            strategy_metadata: strategyMetadata,
+            requested_mode: options.mode,
+            selected_mode: selection.selectedMode,
+            selection_reason: selection.reason,
+            classify_threshold_ms: classifyThresholdMs,
+            timeout_ms: timeoutMs,
+            database_version: databaseVersion,
+            dry_run: true,
+            saved: false,
+            classification_probe: selection.probe ? toPerfClassificationProbe(selection.probe) : undefined,
+            executed_statements: buildDryRunStatements(prepared, strategy, strategyMetadata),
+            plan_observations: [],
+            recommended_actions: buildPerfRecommendedActions(selection.selectedMode, true, pipelineAnalysis, dryRunPlanFacts, specGuidance),
+            pipeline_analysis: pipelineAnalysis,
+            spec_guidance: specGuidance,
+            ddl_inventory: ddlInventorySummary,
+            tuning_guidance: tuningGuidance,
+            tuning_summary: buildPerfTuningSummary(tuningGuidance),
+            seed: { seed: seedConfig.seed }
+        };
+    }
+    const latencyRuns = [];
+    let representativeExecution;
+    let classificationProbe = selection.probe ? toPerfClassificationProbe(selection.probe) : undefined;
+    if (selection.selectedMode === 'latency') {
+        let remainingWarmups = options.warmup;
+        let remainingMeasuredRuns = options.repeat;
+        // Reuse the auto-classification probe so the benchmark does not hide an extra live execution.
+        if (selection.probe) {
+            if (selection.probe.timedOut) {
+                throw new Error('Latency benchmark classification probe timed out unexpectedly. Re-run with --mode completion or a larger timeout.');
+            }
+            if (remainingWarmups > 0) {
+                remainingWarmups -= 1;
+                classificationProbe = {
+                    ...toPerfClassificationProbe(selection.probe),
+                    reused_as_warmup: true
+                };
+            }
+            else if (remainingMeasuredRuns > 0) {
+                remainingMeasuredRuns -= 1;
+                latencyRuns.push(selection.probe.elapsedMs);
+                representativeExecution = selection.probe;
+                classificationProbe = {
+                    ...toPerfClassificationProbe(selection.probe),
+                    reused_as_measured_run: true
+                };
+            }
+        }
+        for (let index = 0; index < remainingWarmups; index += 1) {
+            const warmupExecution = await executePerfBenchmarkOnce(options.rootDir, prepared, strategy, material, timeoutMs, false);
+            if (warmupExecution.timedOut) {
+                throw new Error('Latency benchmark timed out during warmup. Re-run with --mode completion or a larger timeout.');
+            }
+        }
+        for (let index = 0; index < remainingMeasuredRuns; index += 1) {
+            const execution = await executePerfBenchmarkOnce(options.rootDir, prepared, strategy, material, timeoutMs, !representativeExecution);
+            if (execution.timedOut) {
+                throw new Error('Latency benchmark timed out during a measured run. Re-run with --mode completion or a larger timeout.');
+            }
+            latencyRuns.push(execution.elapsedMs);
+            if (!representativeExecution) {
+                representativeExecution = execution;
+            }
+        }
+    }
+    else {
+        if (selection.probe && !selection.probe.timedOut) {
+            representativeExecution = selection.probe;
+            classificationProbe = {
+                ...toPerfClassificationProbe(selection.probe),
+                reused_as_measured_run: true
+            };
+        }
+        else {
+            representativeExecution = await executePerfBenchmarkOnce(options.rootDir, prepared, strategy, material, timeoutMs, true);
+        }
+    }
+    if (!representativeExecution) {
+        throw new Error('Perf benchmark did not produce a representative execution.');
+    }
+    const executedStatements = toPerfStatementReports(representativeExecution.statements);
+    const planFacts = buildPerfPlanFactsFromStatements(representativeExecution.statements);
+    const tuningGuidance = buildPerfTuningGuidance(pipelineAnalysis, planFacts, specGuidance);
+    const report = {
+        schema_version: 1,
+        command: 'perf run',
+        query_file: prepared.absolutePath,
+        query_type: prepared.queryType,
+        params_file: options.paramsFile ? node_path_1.default.resolve(options.rootDir, options.paramsFile) : undefined,
+        params_shape: prepared.paramsShape,
+        ordered_param_names: prepared.orderedParamNames,
+        source_sql_file: prepared.absolutePath,
+        source_sql: prepared.sourceSql,
+        bound_sql: prepared.boundSql,
+        bindings: prepared.bindings,
+        strategy: strategy,
+        strategy_metadata: (_c = representativeExecution.strategyMetadata) !== null && _c !== void 0 ? _c : strategyMetadata,
+        requested_mode: options.mode,
+        selected_mode: selection.selectedMode,
+        selection_reason: selection.reason,
+        classify_threshold_ms: classifyThresholdMs,
+        timeout_ms: timeoutMs,
+        database_version: databaseVersion,
+        dry_run: false,
+        saved: false,
+        classification_probe: classificationProbe,
+        total_elapsed_ms: selection.selectedMode === 'latency'
+            ? latencyRuns.reduce((sum, value) => sum + value, 0)
+            : representativeExecution.elapsedMs,
+        latency_metrics: selection.selectedMode === 'latency'
+            ? buildLatencyMetrics(latencyRuns, options.warmup)
+            : undefined,
+        completion_metrics: selection.selectedMode === 'completion'
+            ? {
+                completed: !representativeExecution.timedOut,
+                timed_out: representativeExecution.timedOut,
+                wall_time_ms: representativeExecution.elapsedMs
+            }
+            : undefined,
+        executed_statements: executedStatements,
+        plan_summary: summarizePlanJson(representativeExecution.finalPlanJson),
+        plan_observations: planFacts.observations,
+        recommended_actions: buildPerfRecommendedActions(selection.selectedMode, !representativeExecution.timedOut, pipelineAnalysis, planFacts, specGuidance),
+        pipeline_analysis: pipelineAnalysis,
+        spec_guidance: specGuidance,
+        ddl_inventory: ddlInventorySummary,
+        tuning_guidance: tuningGuidance,
+        tuning_summary: buildPerfTuningSummary(tuningGuidance),
+        seed: { seed: seedConfig.seed }
+    };
+    if (options.save) {
+        const persisted = savePerfBenchmarkEvidence(options.rootDir, report, representativeExecution.statements);
+        report.run_id = persisted.runId;
+        report.evidence_dir = persisted.evidenceDir;
+        report.saved = true;
+        report.executed_statements = report.executed_statements.map((statement, index) => ({
+            ...statement,
+            sql_file: persisted.sqlFiles[index] || undefined,
+            resolved_sql_preview_file: persisted.resolvedSqlPreviewFiles[index] || undefined,
+            plan_file: persisted.planFiles[index] || undefined
+        }));
+    }
+    return report;
+}
+function buildRequestedStrategyMetadata(sqlFile, strategy, material) {
+    if (strategy !== 'decomposed') {
+        return undefined;
+    }
+    const plan = (0, planner_1.buildQueryPipelinePlan)(sqlFile, { material });
+    return toPerfStrategyMetadata(plan);
+}
+function buildDryRunStatements(prepared, strategy, strategyMetadata) {
+    if (strategy !== 'decomposed' || !strategyMetadata) {
+        return [
+            {
+                seq: 1,
+                role: 'final-query',
+                target: 'FINAL_QUERY',
+                sql: prepared.boundSql,
+                bindings: prepared.bindings,
+                resolved_sql_preview: renderResolvedSqlPreview(prepared.boundSql, prepared.bindings)
+            }
+        ];
+    }
+    return strategyMetadata.planned_steps.map((step) => ({
+        seq: step.step,
+        role: mapPipelineStepKindToRole(step.kind),
+        target: step.target,
+        sql: step.kind === 'materialize'
+            ? `create temp table "${step.target.replace(/"/g, '""')}" as -- resolved at runtime`
+            : prepared.boundSql,
+        bindings: prepared.bindings,
+        resolved_sql_preview: step.kind === 'materialize'
+            ? `materialize ${step.target} from ${node_path_1.default.basename(prepared.absolutePath)}`
+            : renderResolvedSqlPreview(prepared.boundSql, prepared.bindings)
+    }));
+}
+async function executePerfBenchmarkOnce(rootDir, prepared, strategy, material, timeoutMs, capturePlans) {
+    return strategy === 'decomposed'
+        ? executeDecomposedBenchmarkOnce(rootDir, prepared, material, timeoutMs, capturePlans)
+        : executeDirectBenchmarkDetailed(rootDir, prepared, timeoutMs, capturePlans);
+}
+function preparePgStatementExecution(sql, params) {
+    if (!params) {
+        return { sql, bindings: undefined, resolvedSqlPreview: undefined };
+    }
+    if (Array.isArray(params)) {
+        return {
+            sql,
+            bindings: params,
+            resolvedSqlPreview: renderResolvedSqlPreview(sql, params)
+        };
+    }
+    const scan = (0, modelGenScanner_1.scanModelGenSql)(sql);
+    if (scan.mode !== 'named') {
+        return { sql, bindings: undefined, resolvedSqlPreview: undefined };
+    }
+    const bound = (0, modelGenBinder_1.bindModelGenNamedSql)(sql);
+    const bindings = bound.orderedParamNames.map((name) => {
+        if (!(name in params)) {
+            throw new Error(`Missing named pipeline param: ${name}`);
+        }
+        return params[name];
+    });
+    return {
+        sql: bound.boundSql,
+        bindings,
+        resolvedSqlPreview: renderResolvedSqlPreview(bound.boundSql, bindings)
+    };
+}
+function buildExplainTargetSql(sql) {
+    var _a;
+    const match = /^create\s+temp\s+table\s+.+?\s+as\s+([\s\S]+)$/i.exec(sql.trim());
+    return ((_a = match === null || match === void 0 ? void 0 : match[1]) === null || _a === void 0 ? void 0 : _a.trim()) || sql;
+}
+async function executeDirectBenchmarkDetailed(rootDir, prepared, timeoutMs, capturePlans) {
+    const pg = await (0, optionalDependencies_1.ensurePgModule)();
+    const sandboxConfig = (0, sandbox_1.loadPerfSandboxConfig)(rootDir);
+    const resolvedConnection = await (0, sandbox_1.ensurePerfConnection)(rootDir, sandboxConfig);
+    const client = new pg.Client({
+        connectionString: resolvedConnection.connectionUrl,
+        connectionTimeoutMillis: 3000
+    });
+    let statementTrace;
+    let finalPlanJson = null;
+    try {
+        await client.connect();
+        await client.query(`SET statement_timeout = ${Math.max(1, Math.trunc(timeoutMs))}`);
+        // Measure only live statement execution so connection/auth and plan capture do not pollute SQL latency.
+        const startedAt = nowMs();
+        const result = await client.query(prepared.boundSql, prepared.bindings);
+        const elapsedMs = nowMs() - startedAt;
+        if (capturePlans) {
+            finalPlanJson = await capturePlanWithConnectedClient(client, prepared.boundSql, Array.isArray(prepared.bindings) ? prepared.bindings : undefined, true, timeoutMs);
+        }
+        statementTrace = {
+            role: 'final-query',
+            target: 'FINAL_QUERY',
+            sql: prepared.boundSql,
+            bindings: prepared.bindings,
+            resolvedSqlPreview: renderResolvedSqlPreview(prepared.boundSql, prepared.bindings),
+            elapsedMs,
+            rowCount: extractRowCount(result),
+            timedOut: false,
+            planJson: finalPlanJson
+        };
+    }
+    catch (error) {
+        if (!isQueryTimeout(error)) {
+            throw error;
+        }
+        statementTrace = {
+            role: 'final-query',
+            target: 'FINAL_QUERY',
+            sql: prepared.boundSql,
+            bindings: prepared.bindings,
+            resolvedSqlPreview: renderResolvedSqlPreview(prepared.boundSql, prepared.bindings),
+            elapsedMs: timeoutMs,
+            timedOut: true
+        };
+    }
+    finally {
+        await client.end().catch(() => undefined);
+    }
+    return {
+        elapsedMs: statementTrace.elapsedMs,
+        rowCount: statementTrace.rowCount,
+        timedOut: statementTrace.timedOut,
+        statements: [statementTrace],
+        finalPlanJson
+    };
+}
+async function executeDecomposedBenchmarkOnce(rootDir, prepared, material, timeoutMs, capturePlans) {
+    var _a, _b;
+    const pg = await (0, optionalDependencies_1.ensurePgModule)();
+    const sandboxConfig = (0, sandbox_1.loadPerfSandboxConfig)(rootDir);
+    const resolvedConnection = await (0, sandbox_1.ensurePerfConnection)(rootDir, sandboxConfig);
+    const plan = (0, planner_1.buildQueryPipelinePlan)(prepared.absolutePath, { material });
+    const rawStatements = [];
+    const client = new pg.Client({
+        connectionString: resolvedConnection.connectionUrl,
+        connectionTimeoutMillis: 3000
+    });
+    let totalElapsedMs = 0;
+    const sessionFactory = {
+        openSession: async () => ({
+            query: async (sql, params) => {
+                const execution = preparePgStatementExecution(sql, params);
+                if (shouldSkipPerfStatementCapture(sql)) {
+                    return client.query(execution.sql, execution.bindings);
+                }
+                const remainingMs = Math.max(1, Math.trunc(timeoutMs - totalElapsedMs));
+                await client.query(`SET statement_timeout = ${remainingMs}`);
+                // Track total elapsed time across decomposed statements while keeping per-statement timings separate.
+                const startedAt = nowMs();
+                try {
+                    const result = await client.query(execution.sql, execution.bindings);
+                    const elapsedMs = nowMs() - startedAt;
+                    totalElapsedMs += elapsedMs;
+                    const planJson = capturePlans
+                        ? await capturePlanWithConnectedClient(client, buildExplainTargetSql(execution.sql), execution.bindings, false, remainingMs)
+                        : null;
+                    rawStatements.push({
+                        sql: execution.sql,
+                        bindings: execution.bindings,
+                        resolvedSqlPreview: execution.resolvedSqlPreview,
+                        elapsedMs,
+                        rowCount: extractRowCount(result),
+                        timedOut: false,
+                        planJson
+                    });
+                    return result;
+                }
+                catch (error) {
+                    if (!isQueryTimeout(error)) {
+                        throw error;
+                    }
+                    const elapsedMs = Math.min(timeoutMs, Math.max(remainingMs, nowMs() - startedAt));
+                    totalElapsedMs += elapsedMs;
+                    rawStatements.push({
+                        sql: execution.sql,
+                        bindings: execution.bindings,
+                        resolvedSqlPreview: execution.resolvedSqlPreview,
+                        elapsedMs,
+                        timedOut: true
+                    });
+                    throw error;
+                }
+            },
+            end: async () => undefined
+        })
+    };
+    try {
+        await client.connect();
+        const pipelineResult = await (0, execute_1.executeQueryPipeline)(sessionFactory, {
+            sqlFile: prepared.absolutePath,
+            metadata: { material },
+            params: prepared.runtimeBindings
+        });
+        const statements = mapPipelineStatements(rawStatements, toPerfPlannedSteps(pipelineResult.steps));
+        const finalStatement = statements.find((statement) => statement.role === 'final-query');
+        return {
+            elapsedMs: totalElapsedMs,
+            rowCount: pipelineResult.final.rowCount,
+            timedOut: false,
+            statements,
+            finalPlanJson: (_a = finalStatement === null || finalStatement === void 0 ? void 0 : finalStatement.planJson) !== null && _a !== void 0 ? _a : null,
+            strategyMetadata: toPerfStrategyMetadata(plan)
+        };
+    }
+    catch (error) {
+        if (!isQueryTimeout(error)) {
+            throw error;
+        }
+        const statements = mapPipelineStatements(rawStatements, toPerfPlannedSteps(plan.steps.slice(0, rawStatements.length)));
+        const finalStatement = [...statements].reverse().find((statement) => statement.role === 'final-query');
+        return {
+            elapsedMs: totalElapsedMs,
+            rowCount: finalStatement === null || finalStatement === void 0 ? void 0 : finalStatement.rowCount,
+            timedOut: true,
+            statements,
+            finalPlanJson: (_b = finalStatement === null || finalStatement === void 0 ? void 0 : finalStatement.planJson) !== null && _b !== void 0 ? _b : null,
+            strategyMetadata: toPerfStrategyMetadata(plan)
+        };
+    }
+    finally {
+        await client.end().catch(() => undefined);
+    }
+}
+async function capturePlanWithConnectedClient(client, sql, params, analyze, timeoutMs) {
+    var _a, _b, _c, _d;
+    const explainPrefix = analyze
+        ? 'EXPLAIN (ANALYZE TRUE, BUFFERS TRUE, FORMAT JSON) '
+        : 'EXPLAIN (FORMAT JSON) ';
+    try {
+        await client.query(`SET statement_timeout = ${Math.max(1, Math.trunc(timeoutMs))}`);
+        const result = await client.query(`${explainPrefix}${sql}`, params);
+        const firstRow = ((_b = (_a = result.rows) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : {});
+        return (_d = (_c = firstRow['QUERY PLAN']) !== null && _c !== void 0 ? _c : firstRow['query plan']) !== null && _d !== void 0 ? _d : null;
+    }
+    catch (error) {
+        if (isQueryTimeout(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+function toPerfPlannedSteps(steps) {
+    return steps
+        // scalar-filter-bind is emitted by execution tracing, not QueryPipelinePlan metadata.
+        .filter((step) => step.kind !== 'scalar-filter-bind')
+        .map((step) => ({
+        kind: mapPipelineStepKindToRole(step.kind),
+        target: step.target
+    }));
+}
+function mapPipelineStatements(statements, plannedSteps) {
+    return statements.map((statement, index) => {
+        var _a, _b, _c, _d, _e;
+        return ({
+            role: (_b = (_a = plannedSteps === null || plannedSteps === void 0 ? void 0 : plannedSteps[index]) === null || _a === void 0 ? void 0 : _a.kind) !== null && _b !== void 0 ? _b : (index === statements.length - 1 ? 'final-query' : 'materialize'),
+            target: (_d = (_c = plannedSteps === null || plannedSteps === void 0 ? void 0 : plannedSteps[index]) === null || _c === void 0 ? void 0 : _c.target) !== null && _d !== void 0 ? _d : (index === statements.length - 1 ? 'FINAL_QUERY' : `stage_${index + 1}`),
+            sql: statement.sql,
+            bindings: statement.bindings,
+            resolvedSqlPreview: statement.resolvedSqlPreview,
+            elapsedMs: statement.elapsedMs,
+            rowCount: statement.rowCount,
+            timedOut: statement.timedOut,
+            planJson: (_e = statement.planJson) !== null && _e !== void 0 ? _e : null
+        });
+    });
+}
+function mapPipelineStepKindToRole(kind) {
+    return kind === 'materialize' ? 'materialize' : 'final-query';
+}
+function shouldSkipPerfStatementCapture(sql) {
+    return /^\s*drop\s+table\s+if\s+exists\b/i.test(sql);
+}
+function toPerfStrategyMetadata(plan) {
+    return {
+        materialized_ctes: [...plan.metadata.material],
+        scalar_filter_columns: [...plan.metadata.scalarFilterColumns],
+        planned_steps: plan.steps.map((step) => ({
+            step: step.step,
+            kind: step.kind,
+            target: step.target,
+            depends_on: [...step.depends_on]
+        }))
+    };
+}
+function toPerfStatementReports(statements) {
+    return statements.map((statement, index) => ({
+        seq: index + 1,
+        role: statement.role,
+        target: statement.target,
+        sql: statement.sql,
+        bindings: statement.bindings,
+        resolved_sql_preview: statement.resolvedSqlPreview,
+        row_count: statement.rowCount,
+        elapsed_ms: statement.elapsedMs,
+        timed_out: statement.timedOut,
+        plan_summary: summarizePlanJson(statement.planJson)
+    }));
+}
+function buildPerfPlanFactsFromStatements(statements) {
+    var _a;
+    const observations = [];
+    const summaries = [];
+    let hasCapturedPlan = false;
+    let hasSequentialScan = false;
+    let hasJoin = false;
+    for (const statement of statements) {
+        const facts = buildPerfPlanFacts((_a = statement.planJson) !== null && _a !== void 0 ? _a : null);
+        const prefix = `${statement.role}(${statement.target})`;
+        summaries.push(`${prefix}: ${facts.statement_summary}`);
+        observations.push(...facts.observations.map((observation) => `${prefix}: ${observation}`));
+        hasCapturedPlan = hasCapturedPlan || facts.hasCapturedPlan;
+        hasSequentialScan = hasSequentialScan || facts.hasSequentialScan;
+        hasJoin = hasJoin || facts.hasJoin;
+    }
+    return {
+        observations: Array.from(new Set(observations)),
+        statement_summary: summaries.join(' | ') || '(no plan captured)',
+        hasCapturedPlan,
+        hasSequentialScan,
+        hasJoin
+    };
+}
+/**
+ * Compare two saved benchmark evidence directories for AI-friendly tuning decisions.
+ */
+function diffPerfBenchmarkReports(baselineDir, candidateDir) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u;
+    const baseline = loadPerfBenchmarkReport(baselineDir);
+    const candidate = loadPerfBenchmarkReport(candidateDir);
+    const notes = [];
+    const modeChanged = baseline.selected_mode !== candidate.selected_mode;
+    const strategyChanged = baseline.strategy !== candidate.strategy;
+    const statementsDelta = candidate.executed_statements.length - baseline.executed_statements.length;
+    const statementDeltas = buildPerfStatementDeltas(baseline, candidate);
+    const planDeltas = buildPerfPlanDeltas(baseline, candidate);
+    let metricName = 'total_elapsed_ms';
+    let baselineMetric = (_a = baseline.total_elapsed_ms) !== null && _a !== void 0 ? _a : 0;
+    let candidateMetric = (_b = candidate.total_elapsed_ms) !== null && _b !== void 0 ? _b : 0;
+    if (baseline.selected_mode === 'latency' && candidate.selected_mode === 'latency') {
+        metricName = 'p95_ms';
+        baselineMetric = (_e = (_d = (_c = baseline.latency_metrics) === null || _c === void 0 ? void 0 : _c.p95_ms) !== null && _d !== void 0 ? _d : baseline.total_elapsed_ms) !== null && _e !== void 0 ? _e : 0;
+        candidateMetric = (_h = (_g = (_f = candidate.latency_metrics) === null || _f === void 0 ? void 0 : _f.p95_ms) !== null && _g !== void 0 ? _g : candidate.total_elapsed_ms) !== null && _h !== void 0 ? _h : 0;
+        notes.push('Compared latency-mode p95 because both runs are repeat benchmarks.');
+    }
+    else if (baseline.selected_mode === 'completion' && candidate.selected_mode === 'completion') {
+        metricName = 'wall_time_ms';
+        baselineMetric = (_l = (_k = (_j = baseline.completion_metrics) === null || _j === void 0 ? void 0 : _j.wall_time_ms) !== null && _k !== void 0 ? _k : baseline.total_elapsed_ms) !== null && _l !== void 0 ? _l : 0;
+        candidateMetric = (_p = (_o = (_m = candidate.completion_metrics) === null || _m === void 0 ? void 0 : _m.wall_time_ms) !== null && _o !== void 0 ? _o : candidate.total_elapsed_ms) !== null && _p !== void 0 ? _p : 0;
+        notes.push('Compared completion wall time because both runs are long-running benchmarks.');
+    }
+    else {
+        notes.push('Modes differ, so diff falls back to total elapsed time instead of p95.');
+    }
+    if (modeChanged) {
+        notes.push(`Mode changed from ${baseline.selected_mode} to ${candidate.selected_mode}.`);
+    }
+    if (strategyChanged) {
+        notes.push(`Strategy changed from ${baseline.strategy} to ${candidate.strategy}.`);
+    }
+    if (baseline.pipeline_analysis.should_consider_pipeline || candidate.pipeline_analysis.should_consider_pipeline) {
+        notes.push('Pipeline candidacy is present in at least one run; inspect candidate_ctes before rewriting SQL.');
+    }
+    if (((_r = (_q = baseline.pipeline_analysis.scalar_filter_candidates) === null || _q === void 0 ? void 0 : _q.length) !== null && _r !== void 0 ? _r : 0) > 0 || ((_t = (_s = candidate.pipeline_analysis.scalar_filter_candidates) === null || _s === void 0 ? void 0 : _s.length) !== null && _t !== void 0 ? _t : 0) > 0) {
+        notes.push('Scalar filter binding candidates are present; inspect scalar_filter_candidates before keeping optimizer-sensitive subqueries inline.');
+    }
+    if (baseline.database_version && candidate.database_version && baseline.database_version !== candidate.database_version) {
+        notes.push(`Database version changed from ${baseline.database_version} to ${candidate.database_version}.`);
+    }
+    const candidateActions = (_u = candidate.recommended_actions) !== null && _u !== void 0 ? _u : [];
+    if (candidateActions.length > 0) {
+        notes.push('Candidate recommended actions: ' + candidateActions.map((action) => action.action).join(', '));
+    }
+    return {
+        schema_version: 1,
+        command: 'perf report diff',
+        baseline_run_id: baseline.run_id,
+        candidate_run_id: candidate.run_id,
+        baseline_mode: baseline.selected_mode,
+        candidate_mode: candidate.selected_mode,
+        baseline_strategy: baseline.strategy,
+        candidate_strategy: candidate.strategy,
+        primary_metric: {
+            name: metricName,
+            baseline: baselineMetric,
+            candidate: candidateMetric,
+            improvement_percent: calculateImprovementPercent(baselineMetric, candidateMetric)
+        },
+        mode_changed: modeChanged,
+        strategy_changed: strategyChanged,
+        statements_delta: statementsDelta,
+        statement_deltas: statementDeltas,
+        plan_deltas: planDeltas,
+        notes
+    };
+}
+/**
+ * Render a benchmark report in either text or JSON for humans and agents.
+ */
+function formatPerfBenchmarkReport(report, format) {
+    var _a, _b, _c;
+    if (format === 'json') {
+        return `${JSON.stringify(report, null, 2)}\n`;
+    }
+    const lines = [
+        `Query: ${report.query_file}`,
+        `Mode: ${report.selected_mode} (requested: ${report.requested_mode})`,
+        `Selection: ${report.selection_reason}`,
+        `Strategy: ${report.strategy}`,
+        `Timeout: ${Math.round(report.timeout_ms / 1000)}s`,
+        `Statements: ${report.executed_statements.length}`,
+    ];
+    if (report.latency_metrics) {
+        lines.push(`Measured runs: ${report.latency_metrics.measured_runs}`);
+        lines.push(`avg: ${report.latency_metrics.avg_ms.toFixed(2)} ms`);
+        lines.push(`median: ${report.latency_metrics.median_ms.toFixed(2)} ms`);
+        lines.push(`p95: ${report.latency_metrics.p95_ms.toFixed(2)} ms`);
+    }
+    if (report.completion_metrics) {
+        lines.push(`completed: ${report.completion_metrics.completed ? 'yes' : 'no'}`);
+        lines.push(`timed_out: ${report.completion_metrics.timed_out ? 'yes' : 'no'}`);
+        lines.push(`wall_time: ${report.completion_metrics.wall_time_ms.toFixed(2)} ms`);
+    }
+    if (report.classification_probe) {
+        const probeSuffix = report.classification_probe.timed_out ? ' (timed out)' : '';
+        lines.push(`Classification probe: ${report.classification_probe.elapsed_ms.toFixed(2)} ms${probeSuffix}`);
+    }
+    if (report.tuning_summary) {
+        lines.push(`Decision summary: ${report.tuning_summary.headline}`);
+        for (const evidence of report.tuning_summary.evidence) {
+            lines.push(`  evidence: ${evidence}`);
+        }
+        lines.push(`  next: ${report.tuning_summary.next_step}`);
+    }
+    lines.push('');
+    if (report.spec_guidance) {
+        lines.push('');
+        lines.push('Query spec guidance:');
+        lines.push(`  spec_id: ${report.spec_guidance.spec_id}`);
+        lines.push(`  spec_file: ${report.spec_guidance.spec_file}`);
+        lines.push(`  expected_scale: ${(_a = report.spec_guidance.expected_scale) !== null && _a !== void 0 ? _a : '(unspecified)'}`);
+        lines.push(`  review_policy: ${report.spec_guidance.review_policy}`);
+        lines.push(`  evidence_status: ${report.spec_guidance.evidence_status}`);
+        lines.push(`  fixture_rows_available: ${(_b = report.spec_guidance.fixture_rows_available) !== null && _b !== void 0 ? _b : '(unknown)'}`);
+        lines.push(`  fixture_rows_status: ${report.spec_guidance.fixture_rows_status}`);
+        if (report.spec_guidance.expected_input_rows !== undefined) {
+            lines.push(`  expected_input_rows: ${report.spec_guidance.expected_input_rows}`);
+        }
+        if (report.spec_guidance.expected_output_rows !== undefined) {
+            lines.push(`  expected_output_rows: ${report.spec_guidance.expected_output_rows}`);
+        }
+        lines.push('');
+    }
+    if (report.ddl_inventory) {
+        lines.push('DDL inventory:');
+        lines.push(`  ddl_files: ${report.ddl_inventory.ddl_files}`);
+        lines.push(`  ddl_statement_count: ${report.ddl_inventory.ddl_statement_count}`);
+        lines.push(`  table_count: ${report.ddl_inventory.table_count}`);
+        lines.push(`  index_count: ${report.ddl_inventory.index_count}`);
+        lines.push(`  index_names: ${report.ddl_inventory.index_names.length > 0 ? report.ddl_inventory.index_names.join(', ') : '(none)'}`);
+        lines.push('');
+    }
+    if (report.tuning_guidance) {
+        lines.push('Tuning guidance:');
+        lines.push(`  primary_path: ${report.tuning_guidance.primary_path}`);
+        lines.push(`  requires_captured_plan: ${report.tuning_guidance.requires_captured_plan ? 'yes' : 'no'}`);
+        lines.push(`  index_branch: ${report.tuning_guidance.index_branch.recommended ? 'recommended' : 'secondary'}`);
+        for (const rationale of report.tuning_guidance.index_branch.rationale) {
+            lines.push(`    rationale: ${rationale}`);
+        }
+        for (const step of report.tuning_guidance.index_branch.next_steps) {
+            lines.push(`    next: ${step}`);
+        }
+        lines.push(`  pipeline_branch: ${report.tuning_guidance.pipeline_branch.recommended ? 'recommended' : 'secondary'}`);
+        for (const rationale of report.tuning_guidance.pipeline_branch.rationale) {
+            lines.push(`    rationale: ${rationale}`);
+        }
+        for (const step of report.tuning_guidance.pipeline_branch.next_steps) {
+            lines.push(`    next: ${step}`);
+        }
+        lines.push('');
+    }
+    lines.push('Executed statements:');
+    for (const statement of report.executed_statements) {
+        const statementLabel = statement.target ? `${statement.seq}. ${statement.role} (${statement.target})` : `${statement.seq}. ${statement.role}`;
+        lines.push(statementLabel);
+        lines.push(`   elapsed_ms: ${statement.elapsed_ms !== undefined ? statement.elapsed_ms.toFixed(2) : '(n/a)'}`);
+        lines.push(`   row_count: ${(_c = statement.row_count) !== null && _c !== void 0 ? _c : '(n/a)'}`);
+        if (statement.resolved_sql_preview) {
+            lines.push(`   resolved_sql_preview: ${truncateSingleLine(statement.resolved_sql_preview, 120)}`);
+        }
+        lines.push(`   sql: ${truncateSingleLine(statement.sql, 120)}`);
+        if (statement.sql_file) {
+            lines.push(`   sql_file: ${statement.sql_file}`);
+        }
+        if (statement.resolved_sql_preview_file) {
+            lines.push(`   resolved_sql_preview_file: ${statement.resolved_sql_preview_file}`);
+        }
+        if (statement.plan_file) {
+            lines.push(`   plan_file: ${statement.plan_file}`);
+        }
+    }
+    lines.push('');
+    lines.push('Pipeline analysis:');
+    lines.push(`  should_consider_pipeline: ${report.pipeline_analysis.should_consider_pipeline ? 'yes' : 'no'}`);
+    if (report.pipeline_analysis.candidate_ctes.length === 0) {
+        lines.push('  candidate_ctes: (none)');
+    }
+    else {
+        for (const candidate of report.pipeline_analysis.candidate_ctes) {
+            lines.push(`  - ${candidate.name}: downstream references=${candidate.downstream_references}`);
+        }
+    }
+    lines.push(`  scalar_filter_candidates: ${report.pipeline_analysis.scalar_filter_candidates.length > 0 ? report.pipeline_analysis.scalar_filter_candidates.join(', ') : '(none)'}`);
+    if (report.strategy_metadata) {
+        lines.push('');
+        lines.push('Strategy metadata:');
+        lines.push(`  materialized_ctes: ${report.strategy_metadata.materialized_ctes.length > 0 ? report.strategy_metadata.materialized_ctes.join(', ') : '(none)'}`);
+        lines.push(`  scalar_filter_columns: ${report.strategy_metadata.scalar_filter_columns.length > 0 ? report.strategy_metadata.scalar_filter_columns.join(', ') : '(none)'}`);
+        for (const step of report.strategy_metadata.planned_steps) {
+            lines.push(`  - step ${step.step}: ${step.kind} ${step.target} <= ${step.depends_on.length > 0 ? step.depends_on.join(', ') : '(root)'}`);
+        }
+    }
+    if (report.plan_observations.length > 0) {
+        lines.push('');
+        lines.push('Plan observations:');
+        for (const observation of report.plan_observations) {
+            lines.push(`- ${observation}`);
+        }
+    }
+    if (report.recommended_actions.length > 0) {
+        lines.push('');
+        lines.push('Recommended actions:');
+        for (const action of report.recommended_actions) {
+            lines.push(`- [${action.priority}] ${action.action}: ${action.rationale}`);
+        }
+    }
+    if (report.evidence_dir) {
+        lines.push('');
+        lines.push(`Evidence: ${report.evidence_dir}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function formatPerfDiffReport(report, format) {
+    var _a, _b, _c;
+    if (format === 'json') {
+        return `${JSON.stringify(report, null, 2)}\n`;
+    }
+    const statementDeltas = (_a = report.statement_deltas) !== null && _a !== void 0 ? _a : [];
+    const lines = [
+        `Baseline mode: ${report.baseline_mode}`,
+        `Candidate mode: ${report.candidate_mode}`,
+        `Baseline strategy: ${report.baseline_strategy}`,
+        `Candidate strategy: ${report.candidate_strategy}`,
+        `Primary metric: ${report.primary_metric.name}`,
+        `Baseline: ${report.primary_metric.baseline.toFixed(2)}`,
+        `Candidate: ${report.primary_metric.candidate.toFixed(2)}`,
+        `Improvement: ${report.primary_metric.improvement_percent.toFixed(2)}%`,
+        `Statements delta: ${report.statements_delta}`,
+    ];
+    if (statementDeltas.some((delta) => delta.elapsed_delta_ms !== undefined || delta.baseline_timed_out !== delta.candidate_timed_out)) {
+        lines.push('');
+        lines.push('Statement deltas:');
+        for (const delta of statementDeltas) {
+            const elapsed = delta.elapsed_delta_ms !== undefined
+                ? `${delta.elapsed_delta_ms >= 0 ? '+' : ''}${delta.elapsed_delta_ms.toFixed(2)} ms`
+                : '(n/a)';
+            lines.push(`- ${delta.statement_id}: baseline=${(_b = delta.baseline_elapsed_ms) !== null && _b !== void 0 ? _b : '(n/a)'} candidate=${(_c = delta.candidate_elapsed_ms) !== null && _c !== void 0 ? _c : '(n/a)'} delta=${elapsed}`);
+        }
+    }
+    if (report.plan_deltas.some((delta) => delta.changed)) {
+        lines.push('');
+        lines.push('Plan deltas:');
+        for (const delta of report.plan_deltas.filter((entry) => entry.changed)) {
+            lines.push(`- ${delta.statement_id}: ${delta.baseline_plan} -> ${delta.candidate_plan}`);
+        }
+    }
+    if (report.notes.length > 0) {
+        lines.push('');
+        lines.push('Notes:');
+        for (const note of report.notes) {
+            lines.push(`- ${note}`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+function buildPerfPipelineAnalysis(sqlFile) {
+    var _a, _b;
+    const structure = (0, structure_1.buildQueryStructureReport)(sqlFile, 'ztd perf run');
+    const referenceCounts = new Map(structure.ctes.map((cte) => [cte.name, 0]));
+    for (const cte of structure.ctes) {
+        for (const dependency of cte.depends_on) {
+            referenceCounts.set(dependency, ((_a = referenceCounts.get(dependency)) !== null && _a !== void 0 ? _a : 0) + 1);
+        }
+    }
+    for (const root of normalizeFinalQueryRoots(structure.final_query)) {
+        referenceCounts.set(root, ((_b = referenceCounts.get(root)) !== null && _b !== void 0 ? _b : 0) + 1);
+    }
+    const scalarFilterCandidates = (0, scalarFilterAnalysis_1.findScalarFilterCandidates)(sqlFile);
+    const candidateCtes = structure.ctes
+        .map((cte) => {
+        var _a;
+        const downstreamReferences = (_a = referenceCounts.get(cte.name)) !== null && _a !== void 0 ? _a : 0;
+        const reasons = [];
+        if (downstreamReferences >= 2) {
+            reasons.push('referenced by multiple downstream consumers');
+        }
+        if (!cte.unused && cte.depends_on.length >= 2) {
+            reasons.push('merges multiple upstream dependencies');
+        }
+        return {
+            name: cte.name,
+            downstream_references: downstreamReferences,
+            reasons
+        };
+    })
+        .filter((candidate) => candidate.reasons.length > 0);
+    const notes = [
+        'Pipeline candidacy is heuristic in this MVP and does not yet benchmark SqlSpec runtime materialization directly.'
+    ];
+    if (scalarFilterCandidates.length > 0) {
+        notes.push(`Optimizer-sensitive scalar predicates detected on columns: ${scalarFilterCandidates.join(', ')}`);
+    }
+    if (structure.unused_ctes.length > 0) {
+        notes.push(`Unused CTEs detected: ${structure.unused_ctes.join(', ')}`);
+    }
+    return {
+        query_type: structure.query_type,
+        cte_count: structure.cte_count,
+        should_consider_pipeline: candidateCtes.length > 0 || scalarFilterCandidates.length > 0,
+        candidate_ctes: candidateCtes,
+        scalar_filter_candidates: scalarFilterCandidates,
+        notes
+    };
+}
+/**
+ * Load a saved benchmark report from summary.json.
+ */
+function summarizePerfDdlInventory(inventory) {
+    return {
+        ddl_files: inventory.files.length,
+        ddl_statement_count: inventory.ddlStatementCount,
+        table_count: inventory.tableCount,
+        index_count: inventory.indexCount,
+        index_names: [...inventory.indexNames]
+    };
+}
+function buildPerfTuningGuidance(pipelineAnalysis, planFacts, specGuidance) {
+    const indexRationale = [];
+    const indexNextSteps = [
+        'Capture or review EXPLAIN (ANALYZE, BUFFERS) before changing the physical design.',
+        'Append CREATE INDEX statements to ztd/ddl/*.sql instead of making ad-hoc sandbox-only changes.',
+        'Run `ztd perf db reset` so the perf sandbox recreates both tables and indexes from local DDL.'
+    ];
+    const pipelineRationale = [];
+    const pipelineNextSteps = [
+        'Review candidate_ctes and scalar_filter_candidates before rewriting the query.',
+        'Use PIPELINE decomposition when the same intermediate result is reused or scalar filters are optimizer-sensitive.',
+        'After SQL changes, rerun `ztd perf db reset` and `ztd perf seed` so the benchmark uses the intended physical schema.'
+    ];
+    const hasPipelineSignals = pipelineAnalysis.should_consider_pipeline
+        || pipelineAnalysis.candidate_ctes.length > 0
+        || pipelineAnalysis.scalar_filter_candidates.length > 0;
+    const hasPlanSignals = planFacts.hasSequentialScan || planFacts.hasJoin;
+    if (pipelineAnalysis.candidate_ctes.length > 0) {
+        pipelineRationale.push('Reusable intermediate stages detected: ' + pipelineAnalysis.candidate_ctes.map((candidate) => candidate.name).join(', ') + '.');
+    }
+    if (pipelineAnalysis.scalar_filter_candidates.length > 0) {
+        pipelineRationale.push('Optimizer-sensitive scalar predicates detected: ' + pipelineAnalysis.scalar_filter_candidates.join(', ') + '.');
+    }
+    if (planFacts.hasSequentialScan) {
+        indexRationale.push('Captured plan shows a sequential scan, so index coverage is the first physical-design branch to review.');
+    }
+    if (planFacts.hasJoin) {
+        indexRationale.push('Captured plan shows join work, so supporting indexes or join-order changes may matter.');
+    }
+    if ((specGuidance === null || specGuidance === void 0 ? void 0 : specGuidance.review_policy) === 'strongly-recommended') {
+        indexRationale.push('QuerySpec marks this query as performance-sensitive, so preserve physical design changes in local DDL before benchmarking.');
+    }
+    let primaryPath = 'capture-plan';
+    if (hasPipelineSignals) {
+        primaryPath = 'pipeline';
+    }
+    if (hasPlanSignals && !hasPipelineSignals) {
+        primaryPath = 'index';
+    }
+    if (!planFacts.hasCapturedPlan && indexRationale.length === 0) {
+        indexRationale.push('No captured plan is available yet, so confirm whether scans or joins are the real bottleneck before adding indexes.');
+    }
+    if (!planFacts.hasCapturedPlan && pipelineRationale.length === 0) {
+        pipelineRationale.push('No pipeline-specific signal is available yet, so start by capturing a representative plan and row counts.');
+    }
+    return {
+        primary_path: primaryPath,
+        requires_captured_plan: !planFacts.hasCapturedPlan,
+        index_branch: {
+            recommended: primaryPath === 'index',
+            rationale: indexRationale,
+            next_steps: indexNextSteps
+        },
+        pipeline_branch: {
+            recommended: primaryPath === 'pipeline',
+            rationale: pipelineRationale,
+            next_steps: pipelineNextSteps
+        }
+    };
+}
+function buildPerfTuningSummary(guidance) {
+    var _a, _b, _c, _d;
+    if (guidance.primary_path === 'index') {
+        return {
+            headline: 'Start with index tuning.',
+            evidence: guidance.index_branch.rationale.slice(0, 2),
+            next_step: (_a = guidance.index_branch.next_steps[0]) !== null && _a !== void 0 ? _a : 'Review the captured plan before changing indexes.'
+        };
+    }
+    if (guidance.primary_path === 'pipeline') {
+        return {
+            headline: 'Start with pipeline tuning.',
+            evidence: guidance.pipeline_branch.rationale.slice(0, 2),
+            next_step: (_b = guidance.pipeline_branch.next_steps[0]) !== null && _b !== void 0 ? _b : 'Review candidate_ctes before rewriting the query.'
+        };
+    }
+    return guidance.requires_captured_plan
+        ? {
+            headline: 'Capture a representative plan before choosing index or pipeline work.',
+            evidence: [
+                'No captured plan signal is available yet.',
+                ...guidance.index_branch.rationale.slice(0, 1)
+            ],
+            next_step: (_c = guidance.index_branch.next_steps[0]) !== null && _c !== void 0 ? _c : 'Capture EXPLAIN (ANALYZE, BUFFERS) output first.'
+        }
+        : {
+            headline: 'A representative plan is already available; compare index and pipeline evidence next.',
+            evidence: guidance.index_branch.rationale.length > 0
+                ? guidance.index_branch.rationale.slice(0, 2)
+                : ['A captured plan exists, but it does not yet isolate scans, joins, or pipeline hotspots.'],
+            next_step: (_d = guidance.index_branch.next_steps[0]) !== null && _d !== void 0 ? _d : 'Review the captured plan before changing indexes.'
+        };
+}
+function buildPerfRecommendedActions(selectedMode, completed, pipelineAnalysis, planFacts, specGuidance) {
+    var _a;
+    const actions = [];
+    if (selectedMode === 'completion' && !completed) {
+        actions.push({
+            action: 'stabilize-completion-run',
+            priority: 'high',
+            rationale: 'The benchmark timed out in completion mode, so the next loop should focus on finishing the query before comparing latency percentiles.'
+        });
+    }
+    if (pipelineAnalysis.candidate_ctes.length > 0) {
+        actions.push({
+            action: 'consider-pipeline-materialization',
+            priority: 'medium',
+            rationale: `Pipeline candidates detected: ${pipelineAnalysis.candidate_ctes.map((candidate) => candidate.name).join(', ')}.`
+        });
+    }
+    if (pipelineAnalysis.scalar_filter_candidates.length > 0) {
+        actions.push({
+            action: 'consider-scalar-filter-binding',
+            priority: 'medium',
+            rationale: `Scalar filter candidates detected: ${pipelineAnalysis.scalar_filter_candidates.join(', ')}.`
+        });
+    }
+    if (planFacts.hasSequentialScan) {
+        actions.push({
+            action: 'review-index-coverage',
+            priority: 'medium',
+            rationale: 'The captured plan includes a sequential scan, so index coverage is a likely tuning branch.'
+        });
+    }
+    if (planFacts.hasJoin) {
+        actions.push({
+            action: 'inspect-join-strategy',
+            priority: 'medium',
+            rationale: 'The captured plan includes a join operator, so rewriting join shape or supporting it with indexes may help.'
+        });
+    }
+    if ((specGuidance === null || specGuidance === void 0 ? void 0 : specGuidance.evidence_status) === 'missing') {
+        actions.push({
+            action: 'capture-perf-evidence',
+            priority: 'high',
+            rationale: `QuerySpec guidance marks this query as ${(_a = specGuidance.expected_scale) !== null && _a !== void 0 ? _a : 'performance-sensitive'}, so save benchmark evidence for maintenance review.`
+        });
+    }
+    if ((specGuidance === null || specGuidance === void 0 ? void 0 : specGuidance.fixture_rows_status) === 'undersized' && specGuidance.expected_input_rows !== undefined) {
+        actions.push({
+            action: 'increase-perf-fixture-scale',
+            priority: specGuidance.review_policy === 'strongly-recommended' ? 'high' : 'medium',
+            rationale: `perf/seed.yml currently provisions ${specGuidance.fixture_rows_available} rows, below the expected input scale of ${specGuidance.expected_input_rows}.`
+        });
+    }
+    return uniqueRecommendedActions(actions);
+}
+function uniqueRecommendedActions(actions) {
+    const deduped = new Map();
+    for (const action of actions) {
+        deduped.set(action.action, action);
+    }
+    return Array.from(deduped.values());
+}
+function buildPerfPlanFacts(planJson) {
+    const observations = [];
+    const statementSummaryParts = [];
+    const hasCapturedPlan = planJson !== null && planJson !== undefined;
+    let hasSequentialScan = false;
+    let hasJoin = false;
+    walkPlanNodes(planJson, (node) => {
+        var _a;
+        const nodeType = normalizeString(node['Node Type']);
+        const relationName = normalizeString(node['Relation Name']);
+        const joinType = normalizeString(node['Join Type']);
+        const cteName = normalizeString(node['CTE Name']);
+        const filter = normalizeString((_a = node.Filter) !== null && _a !== void 0 ? _a : node['Index Cond']);
+        if (!nodeType) {
+            return;
+        }
+        statementSummaryParts.push(joinType ? `${joinType} ${nodeType}` : nodeType);
+        if (nodeType === 'Seq Scan' && relationName) {
+            hasSequentialScan = true;
+            observations.push(filter
+                ? `Seq Scan on ${relationName} with filter ${truncateSingleLine(filter, 90)}`
+                : `Seq Scan on ${relationName}`);
+        }
+        if (nodeType === 'Nested Loop' || nodeType.includes('Join') || Boolean(joinType)) {
+            hasJoin = true;
+        }
+        if (joinType) {
+            observations.push(`${joinType} ${nodeType} present in the captured plan`);
+        }
+        if (nodeType === 'CTE Scan' && cteName) {
+            observations.push(`CTE Scan reads ${cteName}`);
+        }
+    });
+    return {
+        observations: Array.from(new Set(observations)),
+        statement_summary: Array.from(new Set(statementSummaryParts)).join(' -> ') || '(no plan captured)',
+        hasCapturedPlan,
+        hasSequentialScan,
+        hasJoin
+    };
+}
+function buildPerfPlanDeltas(baseline, candidate) {
+    const keys = collectPerfStatementDiffKeys(baseline.executed_statements, candidate.executed_statements);
+    const baselineLookup = buildPerfStatementDiffLookup(baseline.executed_statements);
+    const candidateLookup = buildPerfStatementDiffLookup(candidate.executed_statements);
+    const deltas = [];
+    for (const key of keys) {
+        const baselineStatement = baselineLookup.get(key);
+        const candidateStatement = candidateLookup.get(key);
+        const statementId = formatPlanDeltaStatementId(candidateStatement !== null && candidateStatement !== void 0 ? candidateStatement : baselineStatement, key);
+        const baselinePlan = summarizeStatementPlan(baselineStatement, baseline.plan_observations, true);
+        const candidatePlan = summarizeStatementPlan(candidateStatement, candidate.plan_observations, true);
+        deltas.push({
+            statement_id: statementId,
+            baseline_plan: baselinePlan,
+            candidate_plan: candidatePlan,
+            changed: baselinePlan !== candidatePlan
+        });
+    }
+    return deltas;
+}
+function buildPerfStatementDeltas(baseline, candidate) {
+    var _a;
+    const keys = collectPerfStatementDiffKeys(baseline.executed_statements, candidate.executed_statements);
+    const baselineLookup = buildPerfStatementDiffLookup(baseline.executed_statements);
+    const candidateLookup = buildPerfStatementDiffLookup(candidate.executed_statements);
+    const deltas = [];
+    for (const key of keys) {
+        const baselineStatement = baselineLookup.get(key);
+        const candidateStatement = candidateLookup.get(key);
+        const statement = candidateStatement !== null && candidateStatement !== void 0 ? candidateStatement : baselineStatement;
+        deltas.push({
+            statement_id: formatPlanDeltaStatementId(statement, key),
+            role: (_a = statement === null || statement === void 0 ? void 0 : statement.role) !== null && _a !== void 0 ? _a : 'final-query',
+            baseline_elapsed_ms: baselineStatement === null || baselineStatement === void 0 ? void 0 : baselineStatement.elapsed_ms,
+            candidate_elapsed_ms: candidateStatement === null || candidateStatement === void 0 ? void 0 : candidateStatement.elapsed_ms,
+            elapsed_delta_ms: (baselineStatement === null || baselineStatement === void 0 ? void 0 : baselineStatement.elapsed_ms) !== undefined && (candidateStatement === null || candidateStatement === void 0 ? void 0 : candidateStatement.elapsed_ms) !== undefined
+                ? candidateStatement.elapsed_ms - baselineStatement.elapsed_ms
+                : undefined,
+            baseline_row_count: baselineStatement === null || baselineStatement === void 0 ? void 0 : baselineStatement.row_count,
+            candidate_row_count: candidateStatement === null || candidateStatement === void 0 ? void 0 : candidateStatement.row_count,
+            baseline_timed_out: baselineStatement === null || baselineStatement === void 0 ? void 0 : baselineStatement.timed_out,
+            candidate_timed_out: candidateStatement === null || candidateStatement === void 0 ? void 0 : candidateStatement.timed_out
+        });
+    }
+    return deltas;
+}
+function buildPerfStatementDiffLookup(statements) {
+    return new Map(buildPerfStatementDiffEntries(statements).map((entry) => [entry.key, entry.statement]));
+}
+function collectPerfStatementDiffKeys(baselineStatements, candidateStatements) {
+    const keys = [];
+    const seen = new Set();
+    for (const entry of [...buildPerfStatementDiffEntries(baselineStatements), ...buildPerfStatementDiffEntries(candidateStatements)]) {
+        if (seen.has(entry.key)) {
+            continue;
+        }
+        seen.add(entry.key);
+        keys.push(entry.key);
+    }
+    return keys;
+}
+function buildPerfStatementDiffEntries(statements) {
+    const counts = new Map();
+    return statements.map((statement) => {
+        var _a;
+        const baseKey = statement.target ? `${statement.role}:${statement.target}` : `${statement.role}:statement`;
+        const nextCount = ((_a = counts.get(baseKey)) !== null && _a !== void 0 ? _a : 0) + 1;
+        counts.set(baseKey, nextCount);
+        return {
+            key: nextCount === 1 ? baseKey : `${baseKey}#${nextCount}`,
+            statement
+        };
+    });
+}
+function formatPlanDeltaStatementId(statement, fallbackKey) {
+    if (!statement) {
+        return fallbackKey;
+    }
+    return statement.target ? `${statement.seq}:${statement.role}:${statement.target}` : `${statement.seq}:${statement.role}`;
+}
+function summarizeStatementPlan(statement, planObservations, includeObservations) {
+    var _a;
+    if (!statement) {
+        return '(missing statement)';
+    }
+    const parts = [];
+    const summary = statement.plan_summary;
+    if ((summary === null || summary === void 0 ? void 0 : summary.join_type) && summary.node_type) {
+        parts.push(`${summary.join_type} ${summary.node_type}`);
+    }
+    else if (summary === null || summary === void 0 ? void 0 : summary.node_type) {
+        parts.push(summary.node_type);
+    }
+    if (includeObservations && planObservations.length > 0) {
+        const prefix = `${statement.role}(${(_a = statement.target) !== null && _a !== void 0 ? _a : 'statement'})`;
+        const relevantObservations = planObservations.filter((observation) => observation.startsWith(prefix));
+        if (relevantObservations.length > 0) {
+            parts.push(relevantObservations.join(' | '));
+        }
+    }
+    return parts.join(' :: ') || '(no plan captured)';
+}
+function walkPlanNodes(planJson, visit) {
+    if (!Array.isArray(planJson)) {
+        return;
+    }
+    for (const entry of planJson) {
+        if (typeof entry !== 'object' || entry === null) {
+            continue;
+        }
+        const plan = entry.Plan;
+        if (typeof plan === 'object' && plan !== null) {
+            walkSinglePlanNode(plan, visit);
+        }
+    }
+}
+function walkSinglePlanNode(node, visit) {
+    visit(node);
+    const plans = node.Plans;
+    if (!Array.isArray(plans)) {
+        return;
+    }
+    for (const child of plans) {
+        if (typeof child === 'object' && child !== null) {
+            walkSinglePlanNode(child, visit);
+        }
+    }
+}
+function renderResolvedSqlPreview(sql, bindings) {
+    if (!Array.isArray(bindings) || bindings.length === 0) {
+        return undefined;
+    }
+    return sql.replace(/\$(\d+)/g, (token, rawIndex) => {
+        const binding = bindings[Number(rawIndex) - 1];
+        return binding === undefined ? token : renderSqlLiteral(binding);
+    });
+}
+function renderSqlLiteral(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (typeof value === 'number' || typeof value === 'bigint') {
+        return String(value);
+    }
+    if (typeof value === 'boolean') {
+        return value ? 'true' : 'false';
+    }
+    if (value instanceof Date) {
+        return `'${value.toISOString()}'`;
+    }
+    return `'${String(value).replace(/'/g, "''")}'`;
+}
+function loadPerfBenchmarkReport(evidenceDir) {
+    const summaryFile = node_path_1.default.join(node_path_1.default.resolve(evidenceDir), 'summary.json');
+    const parsed = JSON.parse((0, node_fs_1.readFileSync)(summaryFile, 'utf8'));
+    return validatePerfBenchmarkReport(summaryFile, parsed);
+}
+exports.PERF_BENCHMARK_DEFAULTS = {
+    repeat: DEFAULT_REPEAT,
+    warmup: DEFAULT_WARMUP,
+    classifyThresholdSeconds: DEFAULT_CLASSIFY_THRESHOLD_SECONDS,
+    timeoutMinutes: DEFAULT_TIMEOUT_MINUTES
+};
+function prepareBenchmarkQuery(rootDir, queryFile, paramsFile) {
+    const absolutePath = node_path_1.default.resolve(rootDir, queryFile);
+    const sourceSql = (0, node_fs_1.readFileSync)(absolutePath, 'utf8');
+    const structure = (0, structure_1.buildQueryStructureReport)(absolutePath, 'ztd perf run');
+    if (structure.query_type !== 'SELECT') {
+        throw new Error('ztd perf run currently supports SELECT queries only.');
+    }
+    const scan = (0, modelGenScanner_1.scanModelGenSql)(sourceSql);
+    const rawBindings = paramsFile ? loadPerfBindings(rootDir, paramsFile) : undefined;
+    if (scan.mode === 'named') {
+        if (!rawBindings || typeof rawBindings !== 'object' || Array.isArray(rawBindings)) {
+            throw new Error('Named SQL placeholders require an object in --params.');
+        }
+        const namedBindings = rawBindings;
+        const bound = (0, modelGenBinder_1.bindModelGenNamedSql)(sourceSql);
+        const orderedValues = bound.orderedParamNames.map((name) => {
+            if (!(name in namedBindings)) {
+                throw new Error(`Missing named benchmark param: ${name}`);
+            }
+            return namedBindings[name];
+        });
+        return {
+            absolutePath,
+            sourceSql,
+            boundSql: bound.boundSql,
+            queryType: 'SELECT',
+            paramsShape: scan.mode,
+            orderedParamNames: bound.orderedParamNames,
+            bindings: orderedValues,
+            runtimeBindings: namedBindings
+        };
+    }
+    if (scan.mode === 'positional') {
+        if (!Array.isArray(rawBindings)) {
+            throw new Error('Positional SQL placeholders require an array in --params.');
+        }
+        const orderedParamNames = scan.positionalTokens.map((token) => token.token);
+        const highestRequiredIndex = orderedParamNames.reduce((max, token) => {
+            const parsed = Number(token.slice(1));
+            return Number.isInteger(parsed) ? Math.max(max, parsed) : max;
+        }, 0);
+        if (rawBindings.length < highestRequiredIndex) {
+            throw new Error(`Positional SQL placeholders require at least ${highestRequiredIndex} parameters for $${highestRequiredIndex}.`);
+        }
+        return {
+            absolutePath,
+            sourceSql,
+            boundSql: sourceSql,
+            queryType: 'SELECT',
+            paramsShape: scan.mode,
+            orderedParamNames,
+            bindings: rawBindings,
+            runtimeBindings: rawBindings
+        };
+    }
+    if (rawBindings !== undefined) {
+        throw new Error('This SQL file has no placeholders, so --params is not needed.');
+    }
+    return {
+        absolutePath,
+        sourceSql,
+        boundSql: sourceSql,
+        queryType: 'SELECT',
+        paramsShape: 'none',
+        orderedParamNames: [],
+        bindings: undefined,
+        runtimeBindings: undefined
+    };
+}
+function loadPerfBindings(rootDir, paramsFile) {
+    const absolutePath = node_path_1.default.resolve(rootDir, paramsFile);
+    const rawContents = (0, node_fs_1.readFileSync)(absolutePath, 'utf8');
+    try {
+        if (node_path_1.default.extname(absolutePath).toLowerCase() === '.json') {
+            return JSON.parse(rawContents);
+        }
+        const parsed = (0, yaml_1.parse)(rawContents);
+        if (isPerfParamsEnvelope(parsed)) {
+            return parsed.params;
+        }
+        return parsed !== null && parsed !== void 0 ? parsed : {};
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to parse perf params file ${absolutePath}: ${message}`);
+    }
+}
+function isPerfParamsEnvelope(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) && 'params' in value;
+}
+async function fetchPerfDatabaseVersion(rootDir) {
+    var _a, _b;
+    const pg = await (0, optionalDependencies_1.ensurePgModule)();
+    const sandboxConfig = (0, sandbox_1.loadPerfSandboxConfig)(rootDir);
+    const resolvedConnection = await (0, sandbox_1.ensurePerfConnection)(rootDir, sandboxConfig);
+    const client = new pg.Client({
+        connectionString: resolvedConnection.connectionUrl,
+        connectionTimeoutMillis: 3000
+    });
+    try {
+        await client.connect();
+        const result = await client.query('SHOW server_version');
+        return (_b = (_a = result.rows) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.server_version;
+    }
+    finally {
+        await client.end().catch(() => undefined);
+    }
+}
+async function classifyPerfBenchmarkMode(rootDir, prepared, strategy, material, classifyThresholdMs) {
+    const probe = await executePerfBenchmarkOnce(rootDir, prepared, strategy, material, classifyThresholdMs, true);
+    if (probe.timedOut || probe.elapsedMs >= classifyThresholdMs) {
+        return {
+            selectedMode: 'completion',
+            reason: `classification probe exceeded ${classifyThresholdMs} ms`,
+            probe
+        };
+    }
+    return {
+        selectedMode: 'latency',
+        reason: `classification probe completed within ${classifyThresholdMs} ms`,
+        probe
+    };
+}
+function buildLatencyMetrics(runs, warmupRuns) {
+    var _a, _b;
+    const sorted = [...runs].sort((left, right) => left - right);
+    return {
+        measured_runs: runs.length,
+        warmup_runs: warmupRuns,
+        min_ms: (_a = sorted[0]) !== null && _a !== void 0 ? _a : 0,
+        max_ms: (_b = sorted[sorted.length - 1]) !== null && _b !== void 0 ? _b : 0,
+        avg_ms: runs.reduce((sum, value) => sum + value, 0) / Math.max(runs.length, 1),
+        median_ms: percentile(sorted, 0.5),
+        p95_ms: percentile(sorted, 0.95)
+    };
+}
+function percentile(sorted, ratio) {
+    var _a;
+    if (sorted.length === 0) {
+        return 0;
+    }
+    const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * ratio) - 1));
+    return (_a = sorted[index]) !== null && _a !== void 0 ? _a : 0;
+}
+function summarizePlanJson(planJson) {
+    var _a;
+    const topLevel = Array.isArray(planJson) ? planJson[0] : null;
+    if (!topLevel || typeof topLevel !== 'object') {
+        return null;
+    }
+    const record = topLevel;
+    const plan = ((_a = record.Plan) !== null && _a !== void 0 ? _a : null);
+    if (!plan) {
+        return null;
+    }
+    return {
+        node_type: normalizeString(plan['Node Type']),
+        join_type: normalizeString(plan['Join Type']),
+        total_cost: normalizeNumber(plan['Total Cost']),
+        plan_rows: normalizeNumber(plan['Plan Rows']),
+        actual_rows: normalizeNumber(plan['Actual Rows']),
+        actual_total_time: normalizeNumber(plan['Actual Total Time'])
+    };
+}
+function savePerfBenchmarkEvidence(rootDir, report, statements) {
+    const evidenceRoot = node_path_1.default.join(rootDir, 'perf', 'evidence');
+    (0, node_fs_1.mkdirSync)(evidenceRoot, { recursive: true });
+    const reserved = reservePerfEvidenceDir(evidenceRoot, report.label);
+    const plansDir = node_path_1.default.join(reserved.evidenceDir, 'plans');
+    const sqlDir = node_path_1.default.join(reserved.evidenceDir, 'executed-sql');
+    (0, node_fs_1.mkdirSync)(plansDir, { recursive: true });
+    (0, node_fs_1.mkdirSync)(sqlDir, { recursive: true });
+    (0, node_fs_1.copyFileSync)(report.source_sql_file, node_path_1.default.join(reserved.evidenceDir, 'source.sql'));
+    if (report.params_file && (0, node_fs_1.existsSync)(report.params_file)) {
+        (0, node_fs_1.copyFileSync)(report.params_file, node_path_1.default.join(reserved.evidenceDir, node_path_1.default.basename(report.params_file)));
+    }
+    const planFiles = [];
+    const sqlFiles = [];
+    const resolvedSqlPreviewFiles = [];
+    for (const [index, statement] of report.executed_statements.entries()) {
+        const trace = statements[index];
+        const targetSuffix = statement.target ? `-${sanitizeLabel(statement.target)}` : '';
+        const baseName = `${String(statement.seq).padStart(3, '0')}-${statement.role}${targetSuffix}`;
+        const sqlFileName = `${baseName}.bound.sql`;
+        const relativeSqlPath = node_path_1.default.join('executed-sql', sqlFileName).replace(/\\/g, '/');
+        (0, node_fs_1.writeFileSync)(node_path_1.default.join(sqlDir, sqlFileName), `${statement.sql.trimEnd()}\n`, 'utf8');
+        sqlFiles.push(relativeSqlPath);
+        if (statement.resolved_sql_preview) {
+            const resolvedFileName = `${baseName}.resolved-preview.sql`;
+            const relativeResolvedPath = node_path_1.default.join('executed-sql', resolvedFileName).replace(/\\/g, '/');
+            (0, node_fs_1.writeFileSync)(node_path_1.default.join(sqlDir, resolvedFileName), `${statement.resolved_sql_preview.trimEnd()}\n`, 'utf8');
+            resolvedSqlPreviewFiles.push(relativeResolvedPath);
+        }
+        else {
+            resolvedSqlPreviewFiles.push('');
+        }
+        if ((trace === null || trace === void 0 ? void 0 : trace.planJson) !== undefined && trace.planJson !== null) {
+            const planFileName = `${baseName}.plan.json`;
+            const relativePlanPath = node_path_1.default.join('plans', planFileName).replace(/\\/g, '/');
+            (0, node_fs_1.writeFileSync)(node_path_1.default.join(plansDir, planFileName), `${JSON.stringify(trace.planJson, null, 2)}\n`, 'utf8');
+            planFiles.push(relativePlanPath);
+        }
+        else {
+            planFiles.push('');
+        }
+    }
+    const summary = {
+        ...report,
+        run_id: reserved.runId,
+        evidence_dir: reserved.evidenceDir,
+        saved: true,
+        executed_statements: report.executed_statements.map((statement, index) => ({
+            ...statement,
+            sql_file: sqlFiles[index] || undefined,
+            resolved_sql_preview_file: resolvedSqlPreviewFiles[index] || undefined,
+            plan_file: planFiles[index] || undefined
+        }))
+    };
+    (0, node_fs_1.writeFileSync)(node_path_1.default.join(reserved.evidenceDir, 'summary.json'), `${JSON.stringify(summary, null, 2)}\n`, 'utf8');
+    (0, node_fs_1.writeFileSync)(node_path_1.default.join(reserved.evidenceDir, 'executed-statements.json'), `${JSON.stringify(summary.executed_statements, null, 2)}\n`, 'utf8');
+    return {
+        runId: reserved.runId,
+        evidenceDir: reserved.evidenceDir,
+        planFiles,
+        sqlFiles,
+        resolvedSqlPreviewFiles
+    };
+}
+function reservePerfEvidenceDir(evidenceRoot, label) {
+    const suffix = label ? `_${sanitizeLabel(label)}` : '';
+    let nextRun = readHighestPerfRunIndex(evidenceRoot) + 1;
+    // Reserve the run directory atomically so concurrent perf runs cannot collide.
+    for (let attempts = 0; attempts < 1024; attempts += 1) {
+        const runId = `run_${String(nextRun).padStart(3, '0')}${suffix}`;
+        const evidenceDir = node_path_1.default.join(evidenceRoot, runId);
+        try {
+            (0, node_fs_1.mkdirSync)(evidenceDir);
+            return { runId, evidenceDir };
+        }
+        catch (error) {
+            if (isAlreadyExistsError(error)) {
+                nextRun += 1;
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw new Error('Unable to allocate a perf evidence directory after repeated collisions.');
+}
+function readHighestPerfRunIndex(evidenceRoot) {
+    const existing = (0, node_fs_1.readdirSync)(evidenceRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+    return existing.reduce((max, name) => {
+        const match = /^run_(\d+)/.exec(name);
+        return match ? Math.max(max, Number(match[1])) : max;
+    }, 0);
+}
+function sanitizeLabel(label) {
+    return label.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
+}
+function isAlreadyExistsError(error) {
+    return error instanceof Error && 'code' in error && error.code === 'EEXIST';
+}
+function toPerfClassificationProbe(result) {
+    return {
+        elapsed_ms: result.elapsedMs,
+        timed_out: result.timedOut,
+        row_count: result.rowCount
+    };
+}
+function validatePerfBenchmarkReport(summaryFile, value) {
+    if (!isPerfBenchmarkReport(value)) {
+        throw new Error(`Invalid perf benchmark summary: ${summaryFile}`);
+    }
+    return value;
+}
+function isPerfBenchmarkReport(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const report = value;
+    if (report.schema_version !== 1 || report.command !== 'perf run') {
+        return false;
+    }
+    if (report.query_type !== 'SELECT' || !isPerfExecutionStrategy(report.strategy)) {
+        return false;
+    }
+    if (!isPerfSelectedMode(report.selected_mode) || !isPerfRequestedMode(report.requested_mode)) {
+        return false;
+    }
+    if (!isStringArray(report.ordered_param_names) || !isPerfStatementReportArray(report.executed_statements)) {
+        return false;
+    }
+    if (!isStringArray(report.plan_observations) || !isPerfRecommendedActionArray(report.recommended_actions)) {
+        return false;
+    }
+    if (!isPerfPipelineAnalysis(report.pipeline_analysis)
+        || !isOptionalPerfClassificationProbe(report.classification_probe)
+        || !isOptionalPerfQuerySpecGuidance(report.spec_guidance)
+        || !isOptionalPerfDdlInventorySummary(report.ddl_inventory)
+        || !isOptionalPerfTuningGuidance(report.tuning_guidance)
+        || !isOptionalPerfTuningSummary(report.tuning_summary)) {
+        return false;
+    }
+    return typeof report.query_file === 'string'
+        && typeof report.source_sql_file === 'string'
+        && typeof report.source_sql === 'string'
+        && typeof report.bound_sql === 'string'
+        && typeof report.selection_reason === 'string'
+        && typeof report.classify_threshold_ms === 'number'
+        && typeof report.timeout_ms === 'number'
+        && typeof report.dry_run === 'boolean'
+        && typeof report.saved === 'boolean'
+        && isOptionalString(report.params_file)
+        && isOptionalString(report.run_id)
+        && isOptionalString(report.label)
+        && isOptionalString(report.evidence_dir)
+        && isOptionalString(report.database_version)
+        && isOptionalNumber(report.total_elapsed_ms)
+        && isOptionalPerfPlanSummary(report.plan_summary)
+        && isOptionalLatencyMetrics(report.latency_metrics)
+        && isOptionalCompletionMetrics(report.completion_metrics)
+        && isOptionalPerfStrategyMetadata(report.strategy_metadata);
+}
+function isOptionalPerfQuerySpecGuidance(value) {
+    if (value === undefined) {
+        return true;
+    }
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const guidance = value;
+    return typeof guidance.spec_id === 'string'
+        && typeof guidance.spec_file === 'string'
+        && isOptionalPerfExpectedScale(guidance.expected_scale)
+        && isOptionalNumber(guidance.expected_input_rows)
+        && isOptionalNumber(guidance.expected_output_rows)
+        && isPerfReviewPolicy(guidance.review_policy)
+        && isPerfEvidenceStatus(guidance.evidence_status)
+        && isOptionalNumber(guidance.fixture_rows_available)
+        && isPerfFixtureRowsStatus(guidance.fixture_rows_status);
+}
+function isOptionalPerfDdlInventorySummary(value) {
+    if (value === undefined) {
+        return true;
+    }
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const inventory = value;
+    return typeof inventory.ddl_files === 'number'
+        && typeof inventory.ddl_statement_count === 'number'
+        && typeof inventory.table_count === 'number'
+        && typeof inventory.index_count === 'number'
+        && isStringArray(inventory.index_names);
+}
+function isOptionalPerfTuningGuidance(value) {
+    if (value === undefined) {
+        return true;
+    }
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const guidance = value;
+    return isPerfTuningPrimaryPath(guidance.primary_path)
+        && typeof guidance.requires_captured_plan === 'boolean'
+        && isPerfTuningBranchGuidance(guidance.index_branch)
+        && isPerfTuningBranchGuidance(guidance.pipeline_branch);
+}
+function isPerfTuningPrimaryPath(value) {
+    return value === 'index' || value === 'pipeline' || value === 'capture-plan';
+}
+function isOptionalPerfTuningSummary(value) {
+    if (value === undefined) {
+        return true;
+    }
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const summary = value;
+    return typeof summary.headline === 'string'
+        && isStringArray(summary.evidence)
+        && typeof summary.next_step === 'string';
+}
+function isPerfTuningBranchGuidance(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const guidance = value;
+    return typeof guidance.recommended === 'boolean'
+        && isStringArray(guidance.rationale)
+        && isStringArray(guidance.next_steps);
+}
+function isOptionalPerfExpectedScale(value) {
+    return value === undefined || value === 'tiny' || value === 'small' || value === 'medium' || value === 'large' || value === 'batch';
+}
+function isPerfReviewPolicy(value) {
+    return value === 'none' || value === 'recommended' || value === 'strongly-recommended';
+}
+function isPerfEvidenceStatus(value) {
+    return value === 'captured' || value === 'missing' || value === 'not-required';
+}
+function isPerfFixtureRowsStatus(value) {
+    return value === 'sufficient' || value === 'undersized' || value === 'unknown';
+}
+function isPerfExecutionStrategy(value) {
+    return value === 'direct' || value === 'decomposed';
+}
+function isPerfSelectedMode(value) {
+    return value === 'latency' || value === 'completion';
+}
+function isPerfRequestedMode(value) {
+    return value === 'auto' || value === 'latency' || value === 'completion';
+}
+function isPerfPipelineAnalysis(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const analysis = value;
+    // Older saved summaries may not include scalar_filter_candidates.
+    // Treat the field as optional so perf diff remains backward-compatible.
+    return typeof analysis.query_type === 'string'
+        && typeof analysis.cte_count === 'number'
+        && typeof analysis.should_consider_pipeline === 'boolean'
+        && isPerfPipelineCandidateArray(analysis.candidate_ctes)
+        && (analysis.scalar_filter_candidates === undefined || isStringArray(analysis.scalar_filter_candidates))
+        && isStringArray(analysis.notes);
+}
+function isPerfPipelineCandidateArray(value) {
+    return Array.isArray(value) && value.every((candidate) => {
+        if (typeof candidate !== 'object' || candidate === null) {
+            return false;
+        }
+        const record = candidate;
+        return typeof record.name === 'string'
+            && typeof record.downstream_references === 'number'
+            && isStringArray(record.reasons);
+    });
+}
+function isPerfStatementReportArray(value) {
+    return Array.isArray(value) && value.every((statement) => isPerfStatementReport(statement));
+}
+function isPerfStatementReport(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const statement = value;
+    return typeof statement.seq === 'number'
+        && isPerfStatementRole(statement.role)
+        && typeof statement.sql === 'string'
+        && isOptionalString(statement.target)
+        && isOptionalBindings(statement.bindings)
+        && isOptionalString(statement.resolved_sql_preview)
+        && isOptionalNumber(statement.row_count)
+        && isOptionalNumber(statement.elapsed_ms)
+        && isOptionalBoolean(statement.timed_out)
+        && isOptionalPerfPlanSummary(statement.plan_summary)
+        && isOptionalString(statement.sql_file)
+        && isOptionalString(statement.resolved_sql_preview_file)
+        && isOptionalString(statement.plan_file);
+}
+function isPerfStatementRole(value) {
+    return value === 'materialize' || value === 'scalar-filter-bind' || value === 'final-query';
+}
+function isPerfRecommendedActionArray(value) {
+    return Array.isArray(value) && value.every((action) => isPerfRecommendedAction(action));
+}
+function isPerfRecommendedAction(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const action = value;
+    return typeof action.action === 'string'
+        && (action.priority === 'high' || action.priority === 'medium')
+        && typeof action.rationale === 'string';
+}
+function isOptionalPerfClassificationProbe(value) {
+    if (value === undefined) {
+        return true;
+    }
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const probe = value;
+    return typeof probe.elapsed_ms === 'number'
+        && typeof probe.timed_out === 'boolean'
+        && isOptionalNumber(probe.row_count)
+        && isOptionalBoolean(probe.reused_as_warmup)
+        && isOptionalBoolean(probe.reused_as_measured_run);
+}
+function isOptionalPerfPlanSummary(value) {
+    if (value === undefined || value === null) {
+        return true;
+    }
+    if (typeof value !== 'object') {
+        return false;
+    }
+    const summary = value;
+    return isOptionalString(summary.node_type)
+        && isOptionalString(summary.join_type)
+        && isOptionalNumber(summary.total_cost)
+        && isOptionalNumber(summary.plan_rows)
+        && isOptionalNumber(summary.actual_rows)
+        && isOptionalNumber(summary.actual_total_time);
+}
+function isOptionalPerfStrategyMetadata(value) {
+    if (value === undefined) {
+        return true;
+    }
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const metadata = value;
+    return isStringArray(metadata.materialized_ctes)
+        && isStringArray(metadata.scalar_filter_columns)
+        && Array.isArray(metadata.planned_steps)
+        && metadata.planned_steps.every((step) => {
+            if (typeof step !== 'object' || step === null) {
+                return false;
+            }
+            const record = step;
+            return typeof record.step === 'number'
+                && (record.kind === 'materialize' || record.kind === 'final-query')
+                && typeof record.target === 'string'
+                && isStringArray(record.depends_on);
+        });
+}
+function isOptionalLatencyMetrics(value) {
+    if (value === undefined) {
+        return true;
+    }
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const metrics = value;
+    return typeof metrics.measured_runs === 'number'
+        && typeof metrics.warmup_runs === 'number'
+        && typeof metrics.min_ms === 'number'
+        && typeof metrics.max_ms === 'number'
+        && typeof metrics.avg_ms === 'number'
+        && typeof metrics.median_ms === 'number'
+        && typeof metrics.p95_ms === 'number';
+}
+function isOptionalCompletionMetrics(value) {
+    if (value === undefined) {
+        return true;
+    }
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const metrics = value;
+    return typeof metrics.completed === 'boolean'
+        && typeof metrics.timed_out === 'boolean'
+        && typeof metrics.wall_time_ms === 'number';
+}
+function isOptionalBindings(value) {
+    return value === undefined || Array.isArray(value) || (typeof value === 'object' && value !== null);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+function isOptionalString(value) {
+    return value === undefined || typeof value === 'string';
+}
+function isOptionalNumber(value) {
+    return value === undefined || typeof value === 'number';
+}
+function isOptionalBoolean(value) {
+    return value === undefined || typeof value === 'boolean';
+}
+function normalizeFinalQueryRoots(finalQuery) {
+    if (Array.isArray(finalQuery)) {
+        return finalQuery.map((value) => value.trim()).filter(Boolean);
+    }
+    if (typeof finalQuery === 'string') {
+        return finalQuery.split(',').map((value) => value.trim()).filter(Boolean);
+    }
+    return [];
+}
+function calculateImprovementPercent(baseline, candidate) {
+    if (baseline === 0) {
+        return 0;
+    }
+    return ((baseline - candidate) / baseline) * 100;
+}
+function extractRowCount(result) {
+    if (typeof result.rowCount === 'number') {
+        return result.rowCount;
+    }
+    return Array.isArray(result.rows) ? result.rows.length : undefined;
+}
+function isQueryTimeout(error) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === '57014';
+}
+function nowMs() {
+    return Number(process.hrtime.bigint()) / 1000000;
+}
+function normalizeNumber(value) {
+    return typeof value === 'number' ? value : undefined;
+}
+function normalizeString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function truncateSingleLine(value, limit) {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    if (normalized.length <= limit) {
+        return normalized;
+    }
+    return `${normalized.slice(0, limit - 3)}...`;
+}
+//# sourceMappingURL=benchmark.js.map