docs: spec, implementation plan, jev goal gate

2026-09-21 14:14:12 +03:00
commit 2778ce74ba
5 changed files with 2824 additions and 0 deletions
@@ -0,0 +1,84 @@
+# 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**.
+
+## 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.