feat(conversation): hard-cut text2sql v2 workflow spine and RAG runtime gates

.context/compound-engineering/ce-review/20260429-022541-8f153efc/summary.md

@@ -0,0 +1,27 @@
+# ce:review summary
+
+- Scope: PR #23 against `origin/dev` (`b28e0df32113db7706cd65c88204ecbe2ec4a426`)
+- Intent: hard-cut the Text2SQL v2 workflow spine and RAG runtime/config surfaces without regressing run-view, delivery, or deployment gates
+- Reviewers completed: correctness, testing, maintainability, project-standards, security, data-migrations, frontend-agent-native
+- Additional local verification: `pnpm run backend:capability-boundary:check` (failed as reported)
+
+## Findings
+
+1. `apps/backend/src/modules/data/persistence/rag-task-config.repository.ts`
+   Stored RAG API keys are retained when provider/model/baseUrl changes omit `apiKey`, which lets persisted health checks forward the old secret to a new caller-controlled endpoint.
+2. `apps/backend/src/modules/data/persistence/rag-task-config.repository.ts`
+   Prisma read/write failures are swallowed and replaced with in-memory success semantics, so persisted RAG settings can appear saved but disappear after restart.
+3. `apps/backend/src/modules/conversation/chat/application/run-view.usecase.ts`
+   Legacy `latestRun` records now make the whole session-view endpoint unreadable because `getSessionView()` hard-fails while populating `latestRun`.
+4. `apps/backend/src/modules/conversation/artifacts/text2sql-v2-artifact-ref.service.ts`
+   The new conversation import of `knowledge/contracts/knowledge-facade.contract` fails the mandatory backend capability-boundary gate.
+5. `.github/workflows/backend-prisma-quality.yml`
+   The new hard-cut CI step only runs the synthetic focused-coverage gate spec and skips mandatory `collect:text2sql-v2-eval-gate` / `text2sql:no-legacy-compat:check` coverage.
+6. `apps/backend/src/modules/conversation/delivery/delivery-contract.mapper.ts`
+   Delivery evidence marks any skipped `generate-sql` stage as a saved-prior-SQL shortcut hit, which mislabels metadata/general no-SQL routes.
+
+## Residual risks
+
+- `/api/v1/settings/rag-configs` is still fetched on the frontend before role-gating settles, and the endpoint itself is not admin-guarded.
+- Overlapping `loadRagConfigView()` requests can still restore stale config state in the settings page.
+- One reviewer lane (`api-contract`) timed out; learnings were synthesized locally from plans/solutions instead of a dedicated subagent.

.github/workflows/backend-prisma-quality.yml

@@ -78,6 +78,14 @@ jobs:
       - name: Backend test
         run: pnpm --filter @text2sql/backend run test
 
+      - name: Text2SQL v2 focused coverage report
+        run: |
+          pnpm --filter @text2sql/backend exec jest \
+            --coverage \
+            --runInBand \
+            text2sql-v2-focused-coverage-gate.spec.ts
+          pnpm --filter @text2sql/backend run collect:text2sql-v2-focused-coverage-gate
+
       - name: R6 scenario package tests
         env:
           R6_REPORT_DIR: /tmp/r6-evidence

AGENTS.md

@@ -39,7 +39,7 @@
 
 常用后端 DB 命令：
 - 生成 Prisma Client：`pnpm --filter @text2sql/backend run prisma:generate`
-- 开发环境生成迁移：`pnpm --filter @text2sql/backend run prisma:migrate -- --name <migration_name>`
+- 开发环境生成迁移：`pnpm --filter @text2sql/backend run prisma:migrate --name <migration_name>`
 - 空库回放校验：`pnpm --filter @text2sql/backend run prisma:verify-empty-db`
 
 ## 3) 质量门禁
@@ -67,9 +67,17 @@ CI 参考：
 ## 4) 联调最小检查
 
 - 统一入口：`http://localhost:3000` 可访问，`/data-sources -> 创建会话 -> 发送消息` 主链路可用。
+- `/settings` 入口可访问，至少包含 `LLM 模型`、`RAG 配置`、`RAG 运行` 三个 tab；其中配置变更仅在 `RAG 配置` 下操作。
+- `RAG 配置` 健康检查需同时覆盖 `dry-check`（草稿）与 `persisted-check`（已保存），并校验返回 `checkedAgainst=draft|persisted`、`reasonCode` 可解释，且检测失败不应清空草稿输入。
 - 网关 smoke：`node tests/smoke/nginx-dev-gateway-smoke.mjs` 可区分 frontend/backend/stream 三类上游失败。
-- 健康检查：`GET http://localhost:3002/health` 应可用（后端内部端口检查）。
+- 健康检查：`GET http://localhost:3002/health` 应可用（后端内部端口检查），且 `dependencies.ragConfig.embedding/rerank` 应可见当前激活 provider+model+configSource 摘要。
 - 若本次改动涉及流式/工具调用：需关注 stream 与 tool 相关字段一致性（细节见 LLM 迁移规范）。
+- 若本次改动涉及 Text2SQL v2 read-model/delivery hard-cut：执行
+  - `pnpm --filter @text2sql/backend run collect:text2sql-v2-eval-gate`
+  - （发布阻断）`pnpm --filter @text2sql/backend run collect:text2sql-v2-eval-gate:strict`
+  - `pnpm --filter @text2sql/backend run collect:text2sql-v2-focused-coverage-gate`
+  - `pnpm run text2sql:no-legacy-compat:check`
+  - 并核对 `rollout.recommendedStage` 与 `rollout.rollbackSuggested`。
 - 若本次改动涉及 modeling parity 指标：执行 `pnpm --filter @text2sql/backend run collect:modeling-parity-shadow-gate`，确认 `relationshipPlatform/semanticSpine/modelingWorkspace` 三维输出可生成。
 - 若本次改动需要发布门禁（go/no-go）：执行 `pnpm --filter @text2sql/backend run collect:modeling-parity-shadow-gate:strict`，并检查 `rollout.recommendedStage` 与 `rollout.rollbackSuggested`。
 
@@ -121,11 +129,19 @@ CI 参考：
 - 同步接口保持 `AgentRunResponse` 合同。
 - 流式事件字段必须完整（`type/runId/sessionId/at/data`）。
 - 工具调用走 allowlist，失败可追踪。
-- 若接入提示词模板运行时，必须保证 `run.trace.promptTemplate` 与 `delivery.evidence.promptTemplate` 字段语义一致，且旧 run 缺字段可兼容读取。
+- Text2SQL v2 active runtime seam 固定为 `conversation/application/workflow/Text2SQLWorkflowRunner -> conversation/runtime/stages/RunV2LangGraphStage -> conversation/runtime/langgraph/Text2SqlV2LangGraphRunnerService`。
+- 若接入提示词模板运行时，必须保证 `run.trace.promptTemplate` 与 `delivery.evidence.promptTemplate` 字段语义一致。
+- hard-cut 生效后，run read/save-view/replay 仅支持显式 v2 读模型（`run.trace.v2.version/stageOrder/stages`）；历史 shape 必须返回 `410 LEGACY_RUN_UNSUPPORTED`（见 runbook）。
+- 叙事边界必须明确：`007 closeout` 仅覆盖 LangGraph topology + `delegation=0`，`008 strict-completion` 额外覆盖 metadata grounding / correction grounding / context-pack parity（含 `strictCompletionRows` 门禁），`009 runtime-intelligence` 额外覆盖 `runtimePlan` / `artifactRefs` / `smartDefaults`（含 runtime coverage rows 与 eval fixture families）。
 
 必跑检查：
 - `GET http://localhost:3002/health` 中 stream/tool-calling 相关字段应符合预期。
 - `pnpm --filter @text2sql/backend run collect:modeling-parity-shadow-gate` 输出需包含 `modelingWorkspace.metrics.deployBlockRate/rollbackRate/schemaBacklogAvg` 与 `rollout.recommendedStage`。
+- `pnpm --filter @text2sql/backend run collect:text2sql-v2-eval-gate` 输出需包含 closeout 五门禁（`evalMetrics/evalTraceability/characterization/noLegacyCompat/focusedCoverage`）及 `rollout.recommendedStage/rollbackSuggested/reasons`。
+- `pnpm --filter @text2sql/backend run collect:text2sql-v2-focused-coverage-gate` 输出需包含 scoped coverage、关键文件门槛、A-M flow blockers 与 eval fixture 行为测试追溯。
+- strict-completion 语义补齐后，focused coverage 输出还需包含 `strictCompletionRows` 评估结果（metadata grounding / correction grounding / context-pack parity）。
+- runtime-intelligence 生效后，focused/eval 输出还需覆盖 `runtime-plan-consistency`、`artifact-ref-compaction`、`smart-defaults-evidence`、`plain-general-no-sql`、`large-context-compaction`、`validation-diagnostics`、`correction-grounding`、`execution-preview`、`all-stage-stream-lifecycle`；focused coverage 还需包含 `runtimeArtifactProducerRows` 与 `streamLifecycleRows`。
+- `pnpm run text2sql:no-legacy-compat:check` 必须通过。
 
 ### D. Governance 术语硬切规范
 来源：`docs/standards/governance-terminology-spec.md`
@@ -172,7 +188,7 @@ CI 参考：
 
 1. 修改 `apps/backend/prisma/schema.prisma`
 2. 生成迁移：
-   - `pnpm --filter @text2sql/backend run prisma:migrate -- --name <migration_name>`
+   - `pnpm --filter @text2sql/backend run prisma:migrate --name <migration_name>`
 3. 生成 Client（必跑）：
    - `pnpm --filter @text2sql/backend run prisma:generate`
 

README.md

@@ -4,7 +4,7 @@ Text2SQL 学习演示版（阶段0-3路线）的单仓项目。
 
 ## 技术栈
 - 后端：NestJS + TypeScript + Prisma
-- Agent：LangGraph `StateGraph` 运行时编排（澄清 -> 生成SQL -> 安全检查 -> 执行 -> 格式化）
+- Agent：Text2SQL v2 LangGraph runtime（`intake -> retrieve -> assemble-context -> semantic-plan -> generate-sql -> validate -> correct? -> execute -> answer`，Phase A `delegation=0`），由 `conversation/text2sql` 统一入口驱动
 - 前端：Next.js + React + Tailwind CSS v4 + shadcn-ui
 - 查询数据：SQLite / MySQL / PostgreSQL / CSV / Excel（会话绑定数据源路由）
 - 功能数据：Redis 缓冲 + PostgreSQL 持久化
@@ -33,7 +33,7 @@ Text2SQL 学习演示版（阶段0-3路线）的单仓项目。
 
 ### 数据库结构改动铁律（必须遵守）
 - 禁止手写或手改 `apps/backend/prisma/migrations/*/migration.sql`。
-- 先改 `apps/backend/prisma/schema.prisma`，再执行 `pnpm --filter @text2sql/backend run prisma:migrate -- --name <migration_name>` 生成迁移。
+- 先改 `apps/backend/prisma/schema.prisma`，再执行 `pnpm --filter @text2sql/backend run prisma:migrate --name <migration_name>` 生成迁移。
 - 每次结构变更必须执行 `pnpm --filter @text2sql/backend run prisma:generate`。
 
 ## 目录结构
@@ -82,6 +82,21 @@ cp apps/frontend/.env.example apps/frontend/.env
 - `LLM_API_KEY=<api-key>`
 - `LLM_MODEL=<model-name>`
 - `LLM_MOCK_MODE=false`（联调真实模型时保持 false）
+- `EMBEDDING_PROVIDER=<provider>`（Text2SQL v2 dense retrieval 的 embedding provider）
+- `EMBEDDING_BASE_URL=<openai-compatible-base-url>`
+- `EMBEDDING_API_KEY=<api-key>`
+- `EMBEDDING_MODEL=text-embedding-3-small`
+- `EMBEDDING_DIMENSIONS=<optional>`
+- `EMBEDDING_VECTOR_VERSION=v1`
+- `RERANK_PROVIDER=<provider>`（可选，默认回退到 `LLM_PROVIDER`）
+- `RERANK_BASE_URL=<openai-compatible-base-url>`（可选，默认回退到 `LLM_BASE_URL`）
+- `RERANK_API_KEY=<api-key>`（可选，默认回退到 `LLM_API_KEY`）
+- `RERANK_MODEL=<model-name>`（可选，默认回退到 `LLM_MODEL`）
+- `RERANK_TIMEOUT_MS=<timeout-ms>`（可选，默认回退到 `LLM_TIMEOUT_MS`）
+- `/settings` 页面职责：
+  - `LLM 模型`：provider/model 目录治理
+  - `RAG 配置`：Embedding / Rerank 运行配置（settings first, env fallback），支持 `检测草稿（dry-check）` 与 `已保存配置检测（persisted-check）`
+  - `RAG 运行`：运行态观测与回放证据
 - `LANGSMITH_TRACING=true|false`（是否启用 LangSmith 追踪）
 - `LANGSMITH_API_KEY=<langsmith-api-key>`（启用追踪时必填）
 - `LANGSMITH_PROJECT=text2sql`（可选，默认 `text2sql`）
@@ -143,6 +158,7 @@ pnpm dev
 - `GET http://localhost:3002/health` 中 `dependencies.sessions.sync` 可查看会话同步状态统计（healthy/pending/degraded）。
 - `GET http://localhost:3002/health` 中 `dependencies.gateMetrics.acceptance` 可查看 R1 门禁指标快照（sampleReady/gatePass）。
 - `GET http://localhost:3002/api/v1/rag/quality/report` 中 `glossarySelectedContext` 可查看术语 selected_context 门禁（sampleVersion/relativeLift/status）。
+- `GET http://localhost:3002/health` 中 `dependencies.ragConfig.embedding/rerank` 可查看当前生效 provider + model + configSource 摘要。
 - 前端能经 `http://localhost:3000` 成功创建会话并发送消息，无跨域报错。
 - 前端从 `/data-sources` 选择任一可用数据源后，可自动创建绑定会话并跳转 `/chat`。
 - `GET /api/v1/sessions?datasource=<id>` 返回的会话均属于指定数据源。
@@ -182,6 +198,9 @@ ts-node apps/backend/scripts/langsmith-coverage-check.ts \
 - `POST /api/v1/settings/prompts`（管理员）
 - `PATCH /api/v1/settings/prompts/:templateId`（管理员）
 - `DELETE /api/v1/settings/prompts/:templateId`（管理员，软删除）
+- `GET /api/v1/settings/rag-configs`
+- `PUT /api/v1/settings/rag-configs/:taskType`（管理员，`taskType=embedding|rerank`）
+- `POST /api/v1/settings/rag-configs/:taskType/health`（管理员，支持可选 `draft` payload；返回 `checkedAgainst=draft|persisted` 与结构化 `reasonCode`）
 - `GET /api/v1/datasources`
 - `POST /api/v1/datasources`
 - `POST /api/v1/datasources/upload`
@@ -239,6 +258,27 @@ ts-node apps/backend/scripts/langsmith-coverage-check.ts \
 - 当前 Tool Calling 基础能力默认启用，首个工具为 `runReadOnlySql`（只读 SQL 执行，含输入校验与安全守卫）。
 - SQL 运行时提示词模板命中证据通过 `run.trace.promptTemplate` 与 `run.delivery.evidence.promptTemplate` 暴露（字段：`templateId/scene/scope/version/fallbackReason`）。
 - 上下文生效证据通过 `run.trace.effectiveContextSummary/conflictHint` 与 `run.delivery.evidence.effectiveContextSummary/conflictHint` 双层暴露，前端可区分用户显式上下文与系统上下文来源。
+- Text2SQL v2 artifact 通过 `run.trace.v2`、`run.delivery.evidence.v2`、SSE `state` 事件 `data.v2.stageArtifact` 暴露；不会破坏既有 `type/runId/sessionId/at/data` 合同。
+- Full Mermaid strict-completion（2026-04-27）语义补齐：
+  - metadata 路径走 `retrieve -> assemble-context -> semantic-plan -> answer`，不进入 `generate/validate/execute`。
+  - correction 重试携带结构化 `correctionGrounding`（失败 SQL 引用、失败码、重试原因、证据引用、attempt）。
+  - delivery 增补 `contextPackSummary / metadataAnswer / correctionGrounding`，用于 sync/stream/run-view/replay 一致诊断。
+  - 叙事分层：`007 closeout` 证明 LangGraph 拓扑与 `delegation=0`；`008 strict-completion` 额外要求 metadata grounding / correction grounding / context-pack parity 语义闭环。
+- hard-cut read-model policy：`/api/v1/runs/:runId`、`/api/v1/runs/:runId/save-as-view`、RAG audit replay 仅支持显式 v2 读模型（`run.trace.v2.version/stageOrder/stages`）。授权后若命中历史 shape，会返回 `410 LEGACY_RUN_UNSUPPORTED`（含迁移 runbook 提示）。
+
+## Text2SQL v2 评估门禁（新增）
+- 评估脚本：`pnpm --filter @text2sql/backend run collect:text2sql-v2-eval-gate`
+- 评估脚本（发布阻断模式）：`pnpm --filter @text2sql/backend run collect:text2sql-v2-eval-gate:strict`
+- focused coverage gate：先运行后端 Jest coverage，再执行 `pnpm --filter @text2sql/backend run collect:text2sql-v2-focused-coverage-gate`；发布阻断模式使用 `pnpm --filter @text2sql/backend run collect:text2sql-v2-focused-coverage-gate:strict`
+- focused flow matrix：`apps/backend/test/fixtures/text2sql-v2-closeout-flow-matrix.json`
+- fixture：`apps/backend/test/fixtures/text2sql-v2-eval-cases.json`
+- characterization fixture：`apps/backend/test/fixtures/text2sql-v2-characterization-cases.json`
+- 输出指标：`retrievalRelevance`、`rerankLift`、`planCoverageRate`、`validationPassRate`、`correctionSuccessRate`、`clarificationRate`、`executionSuccessRate`、`userVisibleFailureQuality`、`latencyP50Ms/P95Ms`、`denseUnavailableRate`、`rerankUnavailableRate`
+- rollout 输出：`summary.rollout`（eval 指标门禁）+ `rollout`（closeout 聚合门禁，含 `recommendedStage/rollbackSuggested/reasons`）
+- closeout 聚合门禁内容：`evalMetrics` + `evalTraceability` + `characterization` + `noLegacyCompat` + `focusedCoverage`（含 `delegationZero`；Full Mermaid strict-completion 场景还必须包含 `strictCompletionRows`：metadata grounding / correction grounding / context-pack parity）
+- anti-regression 静态检查：`pnpm run text2sql:no-legacy-compat:check`
+- 历史 run 迁移手册：`docs/runbooks/text2sql-v2-hardcut-read-model-migration.md`
+- 发布姿势：当前为 direct-v2，不提供进程内 `v1/v2/shadow` runtime 切换；回滚依赖 git/deploy rollback。
 
 ## 测试
 ```bash
@@ -261,6 +301,10 @@ pnpm test:frontend
   - 强门禁模式（失败返回非 0）：`pnpm --filter @text2sql/backend run collect:modeling-parity-shadow-gate:strict`
   - 聚合维度：`relationshipPlatform`、`semanticSpine`、`modelingWorkspace`
 - 迁移回放：`pnpm --filter @text2sql/backend run prisma:verify-empty-db`
+- Text2SQL v2 评估：`pnpm --filter @text2sql/backend run collect:text2sql-v2-eval-gate`
+- Text2SQL v2 评估（严格）：`pnpm --filter @text2sql/backend run collect:text2sql-v2-eval-gate:strict`
+- Text2SQL v2 focused coverage：`pnpm --filter @text2sql/backend run collect:text2sql-v2-focused-coverage-gate`
+- Text2SQL hard-cut anti-regression：`pnpm run text2sql:no-legacy-compat:check`
 - 启动 smoke：至少验证 `GET http://localhost:3002/health`；关键接口建议覆盖：
   - 网关快速检查：`node tests/smoke/nginx-dev-gateway-smoke.mjs`
   - 后端健康检查：`GET http://localhost:3002/health`

apps/backend/.env.example

@@ -27,7 +27,18 @@ LLM_TIMEOUT_MS=30000
 LLM_STREAM_TIMEOUT_MS=90000
 LLM_MOCK_MODE=false
 LLM_FALLBACK_PROVIDERS=siliconflow,minimax
+# Text2SQL v2 dense retrieval uses external embedding provider.
+# If omitted, it falls back to LLM_* provider runtime config.
+EMBEDDING_PROVIDER=volcengine
+EMBEDDING_BASE_URL=
+EMBEDDING_API_KEY=
+EMBEDDING_MODEL=text-embedding-3-small
+EMBEDDING_TIMEOUT_MS=30000
+# Optional: leave empty to use provider default dimensions.
+EMBEDDING_DIMENSIONS=
+EMBEDDING_VECTOR_VERSION=v1
 AGENT_PLANNING_SCAFFOLD_ENABLED=true
+AGENT_RAG_RETRIEVAL_ENABLED=true
 
 # Clarification hybrid gate defaults:
 # - enabled by default

apps/backend/data/reports/modeling-parity-shadow/gate-summary.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-04-25T06:47:56.724Z",
+  "generatedAt": "2026-04-26T12:28:00.057Z",
   "inputs": {
     "relationshipPlatform": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/relationship-platform-shadow/samples.json",
     "semanticSpine": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/semantic-spine-shadow/samples.json",
@@ -10,7 +10,7 @@
     "semanticSpine": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/semantic-spine-shadow/gate-summary.json",
     "modelingWorkspace": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/modeling-parity-shadow/gate-summary.json"
   },
-  "strictMode": true,
+  "strictMode": false,
   "gatePass": false,
   "reasons": [
     "relationship_platform:sample_not_ready",

apps/backend/data/reports/relationship-platform-shadow/gate-summary.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-04-25T06:47:56.690Z",
+  "generatedAt": "2026-04-26T12:28:00.020Z",
   "inputPath": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/relationship-platform-shadow/samples.json",
   "thresholds": {
     "minSamples": 30,

apps/backend/data/reports/semantic-spine-shadow/gate-summary.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-04-25T06:47:56.719Z",
+  "generatedAt": "2026-04-26T12:28:00.050Z",
   "inputPath": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/semantic-spine-shadow/samples.json",
   "thresholds": {
     "minSamples": 30,