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.