Add Studio Query Insights

[sorenbs]

Summary

Adds Studio-owned Query Insights and moves the Console Query Insights experience into the Studio surface behind the optional adapter/BFF bridge. The new Queries navigation item appears directly under Visualizer only when the adapter provides queryInsights; stale #view=queries URLs fall back to the normal default view when the capability is absent.

Also updates the SQL view AI flow so generated SQL is validated and corrected before it is shown, and replaces SQL result visualizations with Studio-owned Bklit chart configs/components.

Screenshots

Queries view

Query analysis details

SQL result visualization

Query Insights

• Adds the optional Adapter.queryInsights contract and BFF procedure: "query-insights" snapshot bridge.
• Wires the BFF client, adapter factories, Studio context, URL state, navigation, and Studio view routing for #view=queries.
• Documents implementer requirements in README.md, FEATURES.md, and Architecture/query-insights.md, including the lowest-fidelity provider Studio supports, counter semantics, traffic exclusion, sanitization, sidecar topology, and sqlcommenter metadata mapping.
• Adds a demo provider for pnpm demo:ppg that records successful demo BFF query executions and excludes Studio metadata/lint/introspection traffic.
• Keeps Query Insights optional: omit the provider and Studio hides the menu item and view.

Query Insights UI And Data Model

• Adds a Studio-aligned Queries view with a live activity chart, table filter/sort controls, query list, and detail sheet.
• Tracks activity in a provider-keyed in-memory cache so samples survive leaving and returning to the view while the same provider is mounted.
• Derives chart samples and visible table rows from the same selected time window: 1m, 5m, 15m, or 1h.
• Uses cumulative provider snapshots, then computes selected-window executions, rows returned, reads, latency, and last-seen values from measured deltas or first-snapshot context samples.
• Avoids interpolating across long missing-data gaps, keeps short gaps connected, renders isolated one-point segments, and offsets latency scaling so the two lines remain distinguishable when values overlap.
• Adds hover readouts for exact Queries/s and average latency values.
• Renames Reads UI to Rows Returned while retaining reads as an internal/advisory signal.

Query Insights AI Analysis

• Reuses the existing shared llm({ task: "query-insights", prompt }) hook instead of adding a Query-specific AI transport.
• Hides all Query Insights AI affordances when the shared LLM hook is unavailable.
• Adds an Analysis column with queued/running state, manual Analyze, and completed Good, Info, or Warn badges.
• Automatically analyzes newly visible query groups in the background one at a time, stops automatic work after five groups, and lets users manually analyze additional groups from the row or detail sheet.
• Uses one callout/tooltip style for completed analysis and only prompts users to open for fixes when the severity has actionable advice.

SQL AI Generation

• Validates AI-generated SQL through the adapter sqlLint capability before inserting it into the editor.
• If generated SQL fails validation, sends the generated SQL and lint diagnostic back to the model and retries before showing anything to the user.
• Leaves the current editor unchanged and surfaces an inline generation error if the corrected SQL still fails validation.
• When SQL originally generated by AI fails during manual execution, feeds the database error back into the SQL-generation prompt and replaces the editor with corrected SQL without auto-running it.
• Keeps manual user-written SQL errors as normal inline query errors with no hidden AI correction.

SQL Result Visualization

• Replaces arbitrary Chart.js-style configs with a constrained Studio-owned Bklit chart schema.
• Supports bar, horizontal-bar, line, pie, doughnut, and stacked bar/horizontal-bar charts.
• Renders visualizations through the checked-in Bklit chart primitives inside the existing SQL result grid header band.
• Adds prompt and schema validation for Bklit configs, including retries for malformed JSON or unsupported chart configs.
• Auto-generates visualizations after the user manually runs AI-generated SQL that was marked graph-worthy.

Demo And Dependencies

• Updates the demo configuration so AI can be toggled through the shared demo LLM hook and Query Insights can be enabled independently.
• Updates the demo to use the latest @prisma/dev dependency available for this branch.
• Vendors the impeccable skill into .agents/skills/impeccable and updates repo agent guidance for future UI work.
• Adds the Bklit chart primitives under ui/components/charts.

Validation

• pnpm typecheck
• pnpm test ui/hooks/use-introspection.test.tsx ui/studio/tanstack-db-performance-architecture.test.ts ui/studio/CommandPalette.test.tsx ui/studio/Navigation.test.tsx ui/studio/Studio.test.tsx ui/studio/views/queries/QueriesView.test.tsx ui/studio/views/queries/query-insights-ai.test.ts ui/studio/views/sql/SqlView.test.tsx ui/studio/views/sql/sql-ai-generation.test.ts ui/studio/views/sql/sql-result-visualization.test.tsx data/bff/bff-client.test.ts demo/ppg-dev/query-insights.test.ts demo/ppg-dev/config.test.ts ui/components/ui/select.test.tsx -- --run
• pnpm build
• COREPACK_ENABLE_STRICT=0 pnpm check:exports
• pnpm exec eslint ui/hooks/use-introspection.test.tsx ui/studio/CommandPalette.test.tsx ui/studio/tanstack-db-performance-architecture.test.ts ui/studio/views/queries/QueriesView.tsx ui/studio/views/queries/query-insights-ai.ts ui/studio/views/sql/SqlView.tsx ui/studio/views/sql/SqlResultVisualization.tsx ui/studio/views/sql/sql-ai-generation.ts ui/studio/views/sql/sql-result-visualization.ts data/bff/bff-client.ts demo/ppg-dev/query-insights.ts demo/ppg-dev/server.ts ui/studio/Navigation.tsx ui/studio/Studio.tsx ui/components/ui/select.tsx
• Browser smoke against http://localhost:4310/#view=queries and http://localhost:4310/#view=sql

Note: a full pnpm test -- --run pass printed all test-file success lines after the test-harness fixes, but Vitest retained a worker process and did not return to the shell. The focused regression suite above exits cleanly.

[github-actions]

Compute preview deployed.

Branch: codex/queries-studio-bridge
Service: codex-queries-studio-bridge
Preview: https://cmpuwi6ky1czzf2zl54dcjjgp.cdg.prisma.build
Version: https://cv-5a4a25c2209d.cdg.prisma.build

[tylerhogarth]

FYI from a local review pass: three things I'd flag as worth a look before merge. Not blockers, just heads-up.

[tylerhogarth]

FYI: StudioBFFClient.queryInsights is non-optional, so every embedder receives a queryInsights object even when their BFF doesn't implement the "query-insights" procedure. The architecture says embedders MUST omit it from the adapter in that case, but the type doesn't push them there; the demo gates it at runtime via config.queries.enabled === true ? bffClient.queryInsights : undefined, which is easy to forget for a new embedder. If they copy the wiring without the gate, Studio renders the Queries view and then fails on every poll because the BFF returns "unknown procedure".

Consider accepting a capability flag on createStudioBFFClient(...) and making queryInsights?: StudioQueryInsights optional on the returned client, so opting in is explicit at the construction site.

[tylerhogarth]

FYI: runSqlRequest stores its AbortController in abortControllerRef but there's no cleanup effect that aborts it on unmount. If the user navigates away mid-query (e.g. switches to view=queries), the adapter call and subsequent state updates keep running. QueriesView already does the right thing on cleanup; SqlView should match. Same applies to the AI generation AbortController if it lacks an unmount cleanup.

useEffect(() => {
  return () => {
    abortControllerRef.current?.abort();
    abortControllerRef.current = null;
  };
}, []);

[tylerhogarth]

FYI: Date.parse is notoriously lenient. Date.parse("12345") returns year 12345; Date.parse("123 456") may succeed depending on the runtime. The architecture constrains line-chart x-keys to "ISO dates, ISO datetimes, or epoch milliseconds," much tighter than Date.parse enforces. The validator will OK line charts on non-time data and the model will keep being encouraged to produce such configs.

function isDateLike(value: unknown): boolean {
  if (typeof value === "number") {
    return Number.isFinite(value) && value >= 0 && value <= 4_102_444_800_000;
  }
  if (typeof value !== "string") return false;
  return /^\d{4}-\d{2}-\d{2}(T[\d:.+\-Z]*)?$/.test(value);
}