@rawsql-ts/ztd-cli 0.20.0 → 0.20.2

package/dist/perf/benchmark.d.ts

@@ -0,0 +1,277 @@
+import { type PlaceholderMode } from '../utils/modelGenScanner';
+import { type QueryPipelineStep } from '../query/planner';
+import { type PerfDdlInventory, type PerfSeedConfig } from './sandbox';
+export type PerfBenchmarkMode = 'auto' | 'latency' | 'completion';
+export type PerfSelectedBenchmarkMode = 'latency' | 'completion';
+export type PerfBenchmarkFormat = 'text' | 'json';
+export type PerfExecutionStrategy = 'direct' | 'decomposed';
+export type PerfStatementRole = 'materialize' | 'scalar-filter-bind' | 'final-query';
+export type PerfRecommendedActionName = 'consider-pipeline-materialization' | 'review-index-coverage' | 'inspect-join-strategy' | 'stabilize-completion-run' | 'capture-perf-evidence' | 'increase-perf-fixture-scale' | 'consider-scalar-filter-binding';
+export interface PerfRunOptions {
+    rootDir: string;
+    queryFile: string;
+    paramsFile?: string;
+    strategy: PerfExecutionStrategy;
+    material: string[];
+    mode: PerfBenchmarkMode;
+    repeat: number;
+    warmup: number;
+    classifyThresholdSeconds: number;
+    timeoutMinutes: number;
+    save: boolean;
+    dryRun: boolean;
+    label?: string;
+}
+export interface PerfStatementReport {
+    seq: number;
+    role: PerfStatementRole;
+    target?: string;
+    sql: string;
+    bindings: unknown[] | Record<string, unknown> | undefined;
+    resolved_sql_preview?: string;
+    row_count?: number;
+    elapsed_ms?: number;
+    timed_out?: boolean;
+    plan_summary?: PerfPlanSummary | null;
+    sql_file?: string;
+    resolved_sql_preview_file?: string;
+    plan_file?: string;
+}
+export interface PerfPlanSummary {
+    node_type?: string;
+    join_type?: string;
+    total_cost?: number;
+    plan_rows?: number;
+    actual_rows?: number;
+    actual_total_time?: number;
+}
+export interface PerfStrategyMetadata {
+    materialized_ctes: string[];
+    scalar_filter_columns: string[];
+    planned_steps: Array<{
+        step: number;
+        kind: QueryPipelineStep['kind'];
+        target: string;
+        depends_on: string[];
+    }>;
+}
+export interface PerfPipelineCandidate {
+    name: string;
+    downstream_references: number;
+    reasons: string[];
+}
+export interface PerfPipelineAnalysis {
+    query_type: string;
+    cte_count: number;
+    should_consider_pipeline: boolean;
+    candidate_ctes: PerfPipelineCandidate[];
+    scalar_filter_candidates: string[];
+    notes: string[];
+}
+export interface PerfRecommendedAction {
+    action: PerfRecommendedActionName;
+    priority: 'high' | 'medium';
+    rationale: string;
+}
+export interface PerfClassificationProbe {
+    elapsed_ms: number;
+    timed_out: boolean;
+    row_count?: number;
+    reused_as_warmup?: boolean;
+    reused_as_measured_run?: boolean;
+}
+export interface PerfPlanDelta {
+    statement_id: string;
+    baseline_plan: string;
+    candidate_plan: string;
+    changed: boolean;
+}
+export interface PerfStatementDelta {
+    statement_id: string;
+    role: PerfStatementRole;
+    baseline_elapsed_ms?: number;
+    candidate_elapsed_ms?: number;
+    elapsed_delta_ms?: number;
+    baseline_row_count?: number;
+    candidate_row_count?: number;
+    baseline_timed_out?: boolean;
+    candidate_timed_out?: boolean;
+}
+interface PerfPlanFacts {
+    observations: string[];
+    statement_summary: string;
+    hasCapturedPlan: boolean;
+    hasSequentialScan: boolean;
+    hasJoin: boolean;
+}
+export type PerfExpectedScale = 'tiny' | 'small' | 'medium' | 'large' | 'batch';
+export type PerfReviewPolicy = 'none' | 'recommended' | 'strongly-recommended';
+export type PerfEvidenceStatus = 'captured' | 'missing' | 'not-required';
+export type PerfFixtureRowsStatus = 'sufficient' | 'undersized' | 'unknown';
+export interface PerfQuerySpecGuidance {
+    spec_id: string;
+    spec_file: string;
+    expected_scale?: PerfExpectedScale;
+    expected_input_rows?: number;
+    expected_output_rows?: number;
+    review_policy: PerfReviewPolicy;
+    evidence_status: PerfEvidenceStatus;
+    fixture_rows_available?: number;
+    fixture_rows_status: PerfFixtureRowsStatus;
+}
+export interface PerfDdlInventorySummary {
+    ddl_files: number;
+    ddl_statement_count: number;
+    table_count: number;
+    index_count: number;
+    index_names: string[];
+}
+export type PerfTuningPrimaryPath = 'index' | 'pipeline' | 'capture-plan';
+export interface PerfTuningBranchGuidance {
+    recommended: boolean;
+    rationale: string[];
+    next_steps: string[];
+}
+export interface PerfTuningGuidance {
+    primary_path: PerfTuningPrimaryPath;
+    requires_captured_plan: boolean;
+    index_branch: PerfTuningBranchGuidance;
+    pipeline_branch: PerfTuningBranchGuidance;
+}
+export interface PerfTuningSummary {
+    headline: string;
+    evidence: string[];
+    next_step: string;
+}
+export interface PerfBenchmarkReport {
+    schema_version: 1;
+    command: 'perf run';
+    run_id?: string;
+    label?: string;
+    query_file: string;
+    query_type: 'SELECT';
+    params_file?: string;
+    params_shape: PlaceholderMode;
+    ordered_param_names: string[];
+    source_sql_file: string;
+    source_sql: string;
+    bound_sql: string;
+    bindings: unknown[] | Record<string, unknown> | undefined;
+    strategy: PerfExecutionStrategy;
+    strategy_metadata?: PerfStrategyMetadata;
+    requested_mode: PerfBenchmarkMode;
+    selected_mode: PerfSelectedBenchmarkMode;
+    selection_reason: string;
+    classify_threshold_ms: number;
+    timeout_ms: number;
+    database_version?: string;
+    dry_run: boolean;
+    saved: boolean;
+    evidence_dir?: string;
+    classification_probe?: PerfClassificationProbe;
+    total_elapsed_ms?: number;
+    latency_metrics?: {
+        measured_runs: number;
+        warmup_runs: number;
+        min_ms: number;
+        max_ms: number;
+        avg_ms: number;
+        median_ms: number;
+        p95_ms: number;
+    };
+    completion_metrics?: {
+        completed: boolean;
+        timed_out: boolean;
+        wall_time_ms: number;
+    };
+    executed_statements: PerfStatementReport[];
+    plan_summary?: PerfPlanSummary | null;
+    plan_observations: string[];
+    recommended_actions: PerfRecommendedAction[];
+    pipeline_analysis: PerfPipelineAnalysis;
+    spec_guidance?: PerfQuerySpecGuidance;
+    ddl_inventory?: PerfDdlInventorySummary;
+    tuning_guidance?: PerfTuningGuidance;
+    tuning_summary?: PerfTuningSummary;
+    seed?: Pick<PerfSeedConfig, 'seed'>;
+}
+export interface PerfDiffReport {
+    schema_version: 1;
+    command: 'perf report diff';
+    baseline_run_id?: string;
+    candidate_run_id?: string;
+    baseline_mode: PerfSelectedBenchmarkMode;
+    candidate_mode: PerfSelectedBenchmarkMode;
+    baseline_strategy: PerfExecutionStrategy;
+    candidate_strategy: PerfExecutionStrategy;
+    primary_metric: {
+        name: 'p95_ms' | 'wall_time_ms' | 'total_elapsed_ms';
+        baseline: number;
+        candidate: number;
+        improvement_percent: number;
+    };
+    mode_changed: boolean;
+    strategy_changed: boolean;
+    statements_delta: number;
+    statement_deltas: PerfStatementDelta[];
+    plan_deltas: PerfPlanDelta[];
+    notes: string[];
+}
+interface StatementExecutionTrace {
+    role: PerfStatementRole;
+    target: string;
+    sql: string;
+    bindings: unknown[] | Record<string, unknown> | undefined;
+    resolvedSqlPreview?: string;
+    elapsedMs: number;
+    rowCount?: number;
+    timedOut: boolean;
+    planJson?: unknown | null;
+}
+/**
+ * Execute or plan a perf benchmark against the sandbox using either direct or decomposed execution.
+ */
+export declare function runPerfBenchmark(options: PerfRunOptions): Promise<PerfBenchmarkReport>;
+export declare function toPerfPlannedSteps(steps: Array<{
+    kind: PerfStatementRole | QueryPipelineStep['kind'];
+    target: string;
+}>): Array<{
+    kind: PerfStatementRole;
+    target: string;
+}>;
+export declare function mapPipelineStatements(statements: Array<{
+    sql: string;
+    bindings: unknown[] | Record<string, unknown> | undefined;
+    resolvedSqlPreview?: string;
+    elapsedMs: number;
+    rowCount?: number;
+    timedOut: boolean;
+    planJson?: unknown | null;
+}>, plannedSteps?: Array<{
+    kind: PerfStatementRole;
+    target: string;
+}>): StatementExecutionTrace[];
+/**
+ * Compare two saved benchmark evidence directories for AI-friendly tuning decisions.
+ */
+export declare function diffPerfBenchmarkReports(baselineDir: string, candidateDir: string): PerfDiffReport;
+/**
+ * Render a benchmark report in either text or JSON for humans and agents.
+ */
+export declare function formatPerfBenchmarkReport(report: PerfBenchmarkReport, format: PerfBenchmarkFormat): string;
+export declare function formatPerfDiffReport(report: PerfDiffReport, format: PerfBenchmarkFormat): string;
+export declare function buildPerfPipelineAnalysis(sqlFile: string): PerfPipelineAnalysis;
+/**
+ * Load a saved benchmark report from summary.json.
+ */
+export declare function summarizePerfDdlInventory(inventory: PerfDdlInventory): PerfDdlInventorySummary;
+export declare function buildPerfTuningGuidance(pipelineAnalysis: PerfPipelineAnalysis, planFacts: PerfPlanFacts, specGuidance?: PerfQuerySpecGuidance): PerfTuningGuidance;
+export declare function buildPerfTuningSummary(guidance: PerfTuningGuidance): PerfTuningSummary;
+export declare function loadPerfBenchmarkReport(evidenceDir: string): PerfBenchmarkReport;
+export declare const PERF_BENCHMARK_DEFAULTS: {
+    readonly repeat: 10;
+    readonly warmup: 3;
+    readonly classifyThresholdSeconds: 60;
+    readonly timeoutMinutes: 5;
+};
+export {};