sql-server-query-ai/docs/superpowers/specs/2026-09-21-sql-server-qai.md

SQL Server qAI — Spec

Date: 2026-09-21 Owner: ahmedmohammed Status: agreed in chat, this file is the spec of record

Goal (verbatim from the owner)

portal that take xml of sql server query plan and use power of generative ai to analysis provide multiple action steps, multiple query rewrite if possible, Jev then rank and decide.

What it is

A containerised web tool. A DBA or consultant logs in, pastes a SQL Server execution plan (Showplan XML, or a .sqlplan file), and gets back:

1. What the plan says is wrong (bottleneck, missing indexes, spills, bad row guesses).
2. Multiple candidate action plans — several different remediations, not one.
3. Multiple candidate SQL rewrites where a rewrite is possible.
4. A Jev-ranked verdict: which candidate to run first, with typed probabilities and confidence, and why.
5. One final "best fast path": the recommended SQL and the steps to apply it.
6. The result rendered as structured UI elements (OpenUI Lang → React), not a wall of markdown. Export to PDF, copy to clipboard.

The demo value is Jev as the decision-maker: the generative model proposes, Jev disposes. Every ranking number on screen is a typed judgment from POST /v1/systemone, not a string the LLM wrote.

Product surface

Screen	Job
/signup, /login	Email + password. Nothing else.
/setup	First-run guide: 3 steps — analyst model, Jev, done.
/app	Left rail = previous analyses (rename, delete). Main = paste plan → run → live report.
/settings	Update analyst model (base URL, key, model, extra params), Jev (key, model), email/password, history.

Report actions: Export to PDF, Copy. History actions: rename, delete.

Getting the input, and the two keys

The portal cannot reach the SQL Server. The user brings the plan XML, and the app must say so in the run screen: SSMS → Ctrl+M (include actual execution plan) → run the query → save the Execution Plan tab as .sqlplan, or copy the Showplan XML cell; without SSMS, prefix the batch with SET STATISTICS XML ON; and copy the XML result cell. A .sqlplan file can be dropped in (SSMS writes UTF-16 with a BOM; decode both) or pasted.

Both model credentials are typed by the logged-in user in /setup or /settings — never server config, so every user brings their own analyst endpoint and their own TypeSafe/Jev key (console.typesafe.ai/keys). Stored keys come back masked, and a blank field means keep the stored one. Nothing leaves the container except the digest, and only to the endpoints that user configured.

Actors (two models, strict roles)

• Analyst — any OpenAI-compatible endpoint the user configures (base_url, key, model, extra params). Generates: candidate action plans, candidate SQL rewrites, and the final OpenUI Lang report. Text in, text out.
• Jev — TypeSafe System One (@typesafe-ai/sdk, model jev-latest). Never generates prose. Answers typed questions (score, choice, noul) about each candidate and returns probabilities + confidence. Code combines them.

Requirements

1. Auth: signup, login, logout, session survives reload. Per-user data isolation.
2. Credentials at rest are encrypted (AES-256-GCM, APP_SECRET env). Never echoed to the browser — masked (••••1234).
3. Plan input: paste XML, or drop/select a .sqlplan/.xml file. Clear inline error if it is not a ShowPlanXML document.
4. Deterministic digest first, model second: parse the XML in code (operators, costs, missing indexes, warnings, waits, spills, estimate vs actual). The model sees the digest, never 40 MB of XML.
5. 2–4 candidates per run. Each candidate: diagnosis, ordered actions with effort and change-control flag, optional rewrite SQL, expected effect.
6. Jev judges every candidate in parallel on 4 dimensions, then a second call picks first_to_run across all candidates. Composite weights live in code, visible in UI.
7. Safety gate: a candidate Jev rates as semantically unsafe is never presented as the recommended path without a visible "verify results before deploying" flag.
8. History: every run persisted (input digest, candidates, Jev verdict, rendered report). Reopening a history item replays the stored report — zero model calls.
9. Streaming: stage indicator while digesting/proposing/judging, then the report renders token-by-token. No spinner-for-30-seconds.
10. Single container: docker compose up → one image, one /data volume, no external DB, no queue, no Redis.

Non-goals

• No live connection to SQL Server. No plan-from-cache lookup. No automatic index creation. No multi-user teams, roles, or sharing. No billing. No mobile app. No markdown editor. No prompt marketplace. No agentic loop with tool calls.

Success looks like

Paste a real slow-query plan → under 60 s → a ranked set of remediations where the top pick is defensible because Jev's probabilities are on screen, and the winning SQL is one click from the clipboard.

Acceptance

What has to be true before this counts as done, and how each part is proven:

• Offline unit suites (npm test, no keys, no network): a real ShowPlan digests to the right numbers; input that is not a plan is refused with a named reason; analyst output is schema-checked and 2–4 options are enforced; Jev's scores rank, an unknown Jev label cannot lead, and a silent Jev degrades to a labelled composite order; credentials seal/open/mask and a blank field never wipes a stored key.
• One live run against the user's real analyst endpoint and a real Jev key: every SSE stage fires, several candidates come back, Jev returns a verdict with confidence, and OpenUI Lang arrives in deltas.
• Browser QA (Chromium): signup → guide → settings → run → rendered report; Copy puts SQL on the clipboard; print emulation flips to paper and hides the rail and buttons; rename sticks and delete confirms first; no horizontal scroll from 320 px up.
• A smoke script (scripts/smoke.sh) that a container or a plain npm start both pass: health, auth pages, signed-out redirect, and /api/analyze refusing an anonymous caller.
• A goal gate: Jev scores the written plan against the goal in this document and answers the named-gap question with nothing before implementation starts.